Account setup

You need to follow these steps to be able to use the Agent API:

  1. Read our Agent API FAQ before you start
  2. Create an agent account on https://agent.rezdy.com. Agent accounts are free but can only sell products that suppliers have published on the Rezdy Marketplace.
  3. Check supplier rates. As an agent you have immediate access to all suppliers Marketplace rates. You can also request preferred rates from your preferred suppliers.
  4. Generate an API Key by going to Integrations -> My Website -> API.
  5. Read our API Overview, check out the examples below and our detailed data model. Build your client and feel free to get in touch if you have any question or if you’d like to discuss the implementation of our API services.
  6. A commercial agreement can be made between agents and Rezdy in order for agents to become certified Rezdy partners.

Example flow: From browsing to booking

This example shows the API requests and responses for a typical booking flow. You should follow this example to integrate your existing or new booking interface with Rezdy.

1. Load products

Agents do not own any product, so the GET /products endpoint will return an empty response. You must use the GET /products/marketplace endpoint to load products that suppliers have published on the Marketplace. Product details include general pricing, description and photos. There are many attributes available on the service, allowing you to filter products by location, supplier, category, or rate type.

Sample Request

GET /products/marketplace?automatedPayments=false

Sample Response

{
    "requestStatus": {
        "success": true,
        "version": "v1"
    },
    "products": [
        {
        "productType": "ACTIVITY",
        "name": "DEMO - Single Flight",
        "shortDescription": "DEMO - Single indoor skydiving flight.",
        "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec orci elit, hendrerit ut augue eget, mattis ullamcorper eros. Curabitur fermentum auctor augue, nec congue nunc luctus eget. In at risus id odio condimentum tempor. Vivamus sapien dui, congue eu nunc quis, laoreet mattis enim. Morbi sed consequat magna, a gravida ligula. Pellentesque sit amet mi quis ligula accumsan sagittis. Donec elementum ornare ultricies. Donec at nibh tristique, dapibus est et, vehicula augue.</p><p>Integer tincidunt quam elit, a consectetur augue pulvinar eget. Integer nec mollis velit. Donec et tristique tortor, a convallis massa. In tincidunt mauris a euismod sollicitudin. Quisque eu lobortis dolor. Phasellus vulputate nulla vel facilisis commodo. Mauris aliquet vitae odio id viverra. Vivamus ac arcu ut sem fringilla rhoncus id id neque. Ut ut diam sed mi malesuada tincidunt vel at velit. Ut vehicula tellus et ligula convallis lacinia.</p><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam dui ligula, feugiat quis laoreet id, molestie aliquam augue. Curabitur rhoncus accumsan dolor, non lobortis dui aliquet vel.</p>",
        "productCode": "PF6B25",
        "internalCode": "ABC1234",
        "supplierId": 9606,
        "supplierName": "Rezdy Demo",
        "timezone": "America/Los_Angeles",
        "advertisedPrice": 85,
        "priceOptions": [
            {
                "id": 18926,
                "price": 100,
                "label": "Adult",
                "seatsUsed": 1
            },
            {
                "id": 89426,
                "price": 90,
                "label": "Student",
                "seatsUsed": 1
            },
            {
                "id": 89427,
                "price": 80,
                "label": "Group",
                "seatsUsed": 1
            }
        ],
        "currency": "AUD",
        "unitLabel": "Participant",
        "unitLabelPlural": "Participants",
        "quantityRequired": true,
        "quantityRequiredMin": 1,
        "quantityRequiredMax": 100,
        "images": [
            {
                "itemUrl": "https://d2jh4nh0bx3cra.cloudfront.net/PRODUCT_IMAGE/9606/skydive.png",
                "thumbnailUrl": "https://d2jh4nh0bx3cra.cloudfront.net/PRODUCT_IMAGE/9606/skydive_tb.png"
            }
        ],
        "bookingMode": "INVENTORY",
        "charter": false,
        "terms": "",
        "generalTerms": "Bookings\r\n\r\n→ Full payment is required at time of booking via credit card, bank transfer, or cash\r\n→ Minimum numbers for group/public tours is 4 people\r\n→ We reserve the right to cancel or reschedule if these numbers aren’t met\r\n→ Tours can be transferred to another person\r\n\r\nBad weather\r\n\r\n→ We reserve the right to cancel/reschedule the activity due to an unforeseen event or adverse weather conditions\r\n→ Bookings will be refunded or credited. If you booked through a third party, you will receive a credit with them\r\n→ If it is raining we will give you rain jackets and go ahead with the tour\r\n\r\nCancellation\r\n\r\n→ You must read and agree to Indemnity form before the tour\r\n→ If you want to postpone your booking after 5pm on the day before, there are no refunds and you will incur an admin fee of $20\r\n",
        "extras": [
            {
                "name": "DVD Video Service",
                "description": "One DVD captures everyone in your party",
                "price": 25,
                "quantity": 0
            }
        ],
        "bookingFields": [
            {
                "label": "First Name",
                "requiredPerParticipant": false,
                "requiredPerBooking": true
            },
            {
                "label": "Last Name",
                "requiredPerParticipant": false,
                "requiredPerBooking": true
            },
            {
                "label": "Phone",
                "requiredPerParticipant": false,
                "requiredPerBooking": true
            },
            {
                "label": "Email",
                "requiredPerParticipant": false,
                "requiredPerBooking": true
            },
            {
                "label": "Do you have any dietary requirements?",
                "requiredPerParticipant": false,
                "requiredPerBooking": true,
                "listOptions": "No, I have no requirements. \r\nYes, I'm Vegetarian."
            },
            {
                "label": "Hotel Pickup",
                "requiredPerParticipant": false,
                "requiredPerBooking": false,
                "listOptions": "0800 Hilton\r\n0815 Sheraton"
            }
        ],
        "latitude": -33.8676981,
        "longitude": 151.2036001cccccc8,
        "confirmMode": "AUTOCONFIRM"
        "confirmModeMinParticipants": 0
        "agentPaymentType": "FULL_AGENT"
        "maxCommissionPercent": 20
        "cancellationPolicyDays": 1
    },
(...)

The response includes a few important attributes that you will need to make a booking:

  • Price options: You can see there are 3 price options, with different labels (Adult, Student, Group). When you make a booking you should send the exact same label in the Quantity.optionLabel attribute. You do not need to store or send priceOption Ids.
  • Agent Payment Type: This defines the payment rules for this product, and impacts the required data to create a booking (see below). Each supplier can set their own payment conditions when they share rates with an agent. PAYOUTS means automatic payment, where Rezdy automatically split the customer’s payment between supplier and agent, based on commission settings. Other types require manual reconciliation between agent and supplier outside of Rezdy. The agentPaymentType value can be one of these:
    • PAYOUTS – Rezdy Automated payment: Full payment is required at time of booking and it is automatically split and paid to supplier and agent. This requires a Stripe token to be sent alongside the booking, see below.
    • FULL_AGENT – Full payment to agent at time of booking. Manual reconciliation between agent and supplier outside of Rezdy.
    • DOWNPAYMENT – Commission payment to agent at time of booking. The balance is usually paid by the customer to the supplier on day of the tour
    • FULL_SUPPLIER – Full payment to supplier at time of booking. Manual reconciliation between supplier and agent outside of Rezdy.
    • NONE – No payment required at time of booking, no payment tracked on Rezdy.
  • Max commission net rate / Max commission percent: Response contains one of the two fields maxCommissionPercent or maxCommissionNetRate.
    • maxCommissionPercent – Maximum commission % you can receive as an agent, when the supplier setup a percentage for this product
    • maxCommissionNetRate – Maximum commission amount you can receive as an agent, when the supplier setup a net rate for this product
  • Booking Fields: This is a list of the various fields suppliers require when making a booking. Some fields can be required once per booking and should be added to the Booking.fields array. Others can be required once per participant and should be added to the BookingItem.participants.fields array for each participant. The API does not enforce any mandatory field, but agents should implement this feature to fulfill suppliers needs.

2. Check availability

Once you have product details, you must call the GET /availability endpoint to load availability.

Sample Request

GET /availability?productCode=PF6B25&startTimeLocal=2014-11-01&endTimeLocal=2014-11-31

This loads all the available sessions for product with code PF6B25 for the whole month of November 2014 in the supplier’s local timezone.

It is possible to load availability for multiple products in a single request. Simply add multiple productCode attributes to the request:

GET /availability?productCode=P11111&productCode=P22222&productCode=P33333&startTimeLocal=2014-11-01&endTimeLocal=2014-11-31

We recommend using startTimeLocal and endTimeLocal attributes, instead of startTime and endTime. They required you to send the timezone as part of your request.

GET /availability?productCode=PF6B25&startTime=2014-11-01T00:00:00%2B11:00&endTime=2014-11-31T00:00:00%2B11:00

Sample Response

{
    "requestStatus": {
        "success": true,
        "version": "v1"
    },
    "sessions": [
        {
            "id": 9843251,
            "startTime": "2014-10-31T16:00:00Z",
            "endTime": "2014-10-31T20:00:00Z",
            "startTimeLocal": "2014-11-01 05:00:00",
            "endTimeLocal": "2014-11-01 09:00:00",
            "allDay": false,
            "seats": 10,
            "seatsAvailable": 6,
            "priceOptions": [
                {
                    "id": 18926,
                    "price": 100,
                    "label": "Adult",
                    "seatsUsed": 1
                },
                {
                    "id": 89426,
                    "price": 90,
                    "label": "Student",
                    "seatsUsed": 1
                },
                {
                    "id": 89427,
                    "price": 80,
                    "label": "Group",
                    "seatsUsed": 1
                }
            ]
        },
        {
            "id": 9843373,
            "startTime": "2014-10-31T22:00:00Z",
            "endTime": "2014-11-01T02:00:00Z",
            "startTimeLocal": "2014-11-01 09:00:00",
            "endTimeLocal": "2014-11-01 13:00:00",
            "allDay": false,
            "seats": 10,
            "seatsAvailable": 6,
            "priceOptions": [
                {
                    "id": 18926,
                    "price": 100,
                    "label": "Adult",
                    "seatsUsed": 1
                },
                {
                    "id": 89426,
                    "price": 90,
                    "label": "Student",
                    "seatsUsed": 1
                },
                {
                    "id": 89427,
                    "price": 80,
                    "label": "Group",
                    "seatsUsed": 1
                }
            ]
        },
        {
            "id": 9843252,
            "startTime": "2014-11-01T16:00:00Z",
            "endTime": "2014-11-01T20:00:00Z",
            "startTimeLocal": "2014-11-02 05:00:00",
            "endTimeLocal": "2014-11-02 09:00:00",
            "allDay": false,
            "seats": 10,
            "seatsAvailable": 6,
            "priceOptions": [
                {
                    "id": 18926,
                    "price": 100,
                    "label": "Adult",
                    "seatsUsed": 1
                },
                {
                    "id": 89426,
                    "price": 90,
                    "label": "Student",
                    "seatsUsed": 1
                },
                {
                    "id": 89427,
                    "price": 80,
                    "label": "Group",
                    "seatsUsed": 1
                }
            ]
        },
(....)

 

Important information here is:

  • startTimeLocal: This is the localized session time you need to send when making a booking for a specific session.
  • seatsAvailable: This is the number of seats available for that specific session.
  • startTime: It is also possible to use timezone-independent session start time for the product booking. However, only one of the fields startTime or startTimeLocal can be used in the booking request, therefore it is up to you to choose which way is more convenient for your client-side code. See the Date format section of our Api Overview for details.

3. Make a booking

When you have loaded product details and availability, and when a customer has selected a specific time and checks out, you need to create the booking in Rezdy by calling the POST /bookings endpoint.

Sample Request (Manual payment reconciliation)

The following request creates a simple booking for 2 Adults for the product we previously loaded. It’s a $200 booking for November 3rd at 9:00AM in Sydney, with a full payment to agent recorded. That means you charged the customer outside of Rezdy, on your own website/gateway. You record that payment in the booking but do not process any payment through Rezdy.

POST /bookings

{
"customer": {
    "firstName": "Hugo",
    "lastName": "Sterin",
    "email": "noreply@rezdy.com",
    "phone": "0282443060"
},
"items": [ 
   {
      "productCode": "PF6B25",
      "startTimeLocal": "2014-11-03 09:00:00",
      "amount": 200,
      "quantities": [
    {
      "optionLabel": "Adult",
      "value": "2"
    }
      ],
       "participants": [
    {
        "fields": [
        {
            "label": "First Name",
            "value": "Hugo"
        },
        {
            "label": "Last Name",
            "value": "Sterin"
        }
        ]
    },
    {
        "fields": [
        {
            "label": "First Name",
            "value": "Simon"
        },
        {
            "label": "Last Name",
            "value": "Lenoir"
        }
        ]
    }
      ]
   }
],
"fields": [
   {
      "label": "Do you have any dietary requirements?",
      "value": "No, I have no requirements. "
   }
],
"comments": "Special requirements go here",
"resellerComments": "Your Agent voucher/redemption code should go here",
"payments": [
    {
      "type": "CREDITCARD",
      "amount": "200",
      "currency": "USD",
      "date": "2014-11-01T10:26:00Z",
      "label": "Payment processed by RezdyDemoAgent"
    }
  ]
}

Sample Response

The response will contain all the information for the booking that was just created. The most important information here is the OrderNumber (I.e. RD7PA1I). That’s the number you should show customers and print on booking confirmations.
Agent bookings also return the calculated commission you should receive for that booking

{
    "requestStatus": {
        "success": true,
        "version": "v1"
    },
    "booking": {
        "customer": {
            "id": 502281,
            "firstName": "Hugo",
            "lastName": "Sterin",
            "name": "Hugo Sterin",
            "email": "noreply@rezdy.com",
            "phone": "0282443060"
        },
        "supplierId": 9606,
        "supplierName": "Rezdy Demo",
        "resellerId": 2404,
        "resellerName": "Rezdy Agent Demo",
        "orderNumber": "RD7PA1I",
        "items": [
            {
                "productName": "DEMO - Single Flight",
                "productCode": "PF6B25",
                "startTime": "2014-11-02T22:00:00Z",
                "endTime": "2014-11-03T02:00:00Z",
                "startTimeLocal": "2014-11-03 09:00:00",
                "endTimeLocal": "2014-11-03 13:00:00",
                "quantities": [
                    {
                        "optionLabel": "Adult",
                        "optionPrice": 100,
                        "value": 2
                    }
                ],
                "totalQuantity": 2,
                "amount": 200,
                "extras": [],
                "participants": [
                    {
                        "fields": [
                            {
                                "label": "First Name",
                                "value": "Hugo",
                                "requiredPerParticipant": false,
                                "requiredPerBooking": false
                            },
                            {
                                "label": "Last Name",
                                "value": "Sterin",
                                "requiredPerParticipant": false,
                                "requiredPerBooking": false
                            }
                        ]
                    },
                    {
                        "fields": [
                            {
                                "label": "First Name",
                                "value": "Simon",
                                "requiredPerParticipant": false,
                                "requiredPerBooking": false
                            },
                            {
                                "label": "Last Name",
                                "value": "Lenoir",
                                "requiredPerParticipant": false,
                                "requiredPerBooking": false
                            }
                        ]
                    }
                ],
                "subtotal": 200
            }
        ],
        "totalAmount": 200,
        "totalCurrency": "USD",
        "totalPaid": 200,
        "totalDue": 0,
        "dateCreated": "2014-11-05T03:04:04.007Z",
        "datePaid": "2014-11-05T03:04:04.007Z",
        "status": "CONFIRMED",
        "comments": "Special requirements go here\r\n",
        "internalNotes": "Internal notes go here",
        "payments": [
            {
                "type": "CREDITCARD",
                "amount": 200,
                "currency": "USD",
                "date": "2014-11-11T10:26:00Z",
                "label": "Payment processed by Rezdy Agent Demo"
            }
        ],
        "fields": [
            {
                "label": "Do you have any dietary requirements?",
                "value": "No, I have no requirements. ",
                "requiredPerParticipant": false,
                "requiredPerBooking": false
            }
        ],
    "source": "PARTNERS",
        "resellerSource": "API",
        "sourceChannel": "REZDYAGENTDEMO",
        "commission": 15,
        "vouchers": []
    }
}

 

Booking request using Automatic payment reconciliation (PAYOUTS):

When a product is setup with agentPaymentType=PAYOUTS, you need to process the booking in 2 steps, and full payment must be processed through Rezdy. We use Stripe to process payments, and you therefore need to implement an extra call to their API, before calling Rezdy Booking API.

  1. Request a Stripe card token, by sending the customer’s credit card details to Stripe. You can use Stripe.js or Stripe API, and should refer to their documentation. Use Rezdy’s publishable key (see below) in your request, for the token to be generated on Rezdy’s account. The card is not charged at this stage.
  2. Call POST /bookings service, as above, but do not include any booking.payments data. You must instead send a creditCard.cardToken parameter that is Stripe’s generated token (id field from Stripe’s API response). Rezdy will confirm the booking, consume the token by processing the payment and record payment on the booking object.

Rezdy’s Stripe publishable keys are:

TEST – USD: pk_test_SRbNF82QH5IUz2VFcZ4JQIrF
TEST – AUD: pk_test_QWFOXrV6YAizJvsEuYxEkis9
PROD – USD: pk_live_zKs28ywqmpH5K6Vz9moNGwiM
PROD – AUD: pk_live_u97uquryvV6hj2FnTPj3p5r6

TEST keys are usable on api-test.rezdy.com. PROD keys are usable on api.rezdy.com. You must also check the product’s currency and use the appropriate key.

Sample Request (Automated payment reconciliation)

The following request is a payment variation of the manual payment above. Rezdy will charge $200 on the credit card that was used to generate the Stripe token, and automatically pay both the supplier and agent.

POST /bookings

{
"customer": {
    "firstName": "Hugo",
    "lastName": "Sterin",
    "email": "noreply@rezdy.com",
    "phone": "0282443060"
},
"items": [ 
   {
      "productCode": "PF6B25",
      "startTimeLocal": "2014-11-03 09:00:00",
      "amount": 200,
      "quantities": [
    {
      "optionLabel": "Adult",
      "value": "2"
    }
      ],
       "participants": [
    {
        "fields": [
        {
            "label": "First Name",
            "value": "Hugo"
        },
        {
            "label": "Last Name",
            "value": "Sterin"
        }
        ]
    },
    {
        "fields": [
        {
            "label": "First Name",
            "value": "Simon"
        },
        {
            "label": "Last Name",
            "value": "Lenoir"
        }
        ]
    }
      ]
   }
],
"fields": [
   {
      "label": "Do you have any dietary requirements?",
      "value": "No, I have no requirements. "
   }
],
"comments": "Special requirements go here",
"resellerComments": "Your Agent voucher/redemption code should go here",
"creditCard":
   {
    "cardToken": "tok_17WyKMDcyMLFVd76rrpDYuKV"
   }
}