RezdyConnect specification

Avatar
Dusan Zahoransky
Updated
Follow

Please read RezdyConnect Overview if you haven't done it yet, before continuing.

 

 

Steps for RezdyConnect integration

  1. Request an access - RezdyConnect configuration is not available by default. You need to contact us to access these options.

  2. Setup products on Rezdy - RezdyConnect allow you to synchronize availability and bookings with your system, however you still need to setup products on Rezdy.

  3. Select a scheduling mode and a booking strategy- Choose between 1-step or 2-step booking strategy and select a scheduling mode

  4. Implement REST endpoints - Implement endpoints that Rezdy will call to pull availability and pricing from, and push bookings to.

  5. Setup your RezdyConnect URLs - Setup your endpoints for each of your products on Rezdy

  6. Optionally use Webhooks or Rezdy API to fine tune your integration - To enhance your integration with additional features, setup webhooks to receive events like booking updates, or use other Rezdy API services to update or cancel your bookings, update a specific session price or availability, etc.

 

1- Request an access

Send an e-mail to api-support@rezdy.com including you company name or alias. We will review your request and enable RezdyConnect on your account if approved. 

Let us know any special configuration requirements for your integration. We can currently configure the following:

  • Availability refresh batch - interval. By default 6 months are synchronized.
  • Availability refresh batch - time schedule. By default the batch is running once a day and we setup a default time. We can change it to a specific time or multiple times a day.
  • Booking and batch refresh automated notifications. We can send an automated alert e-mail whenever a reservation, a booking, a booking cancellation or a batch refresh fails to a specified list of email addresses. Let us know if you would like to use this feature.

2- Setup products on Rezdy

Assuming that your supplier account is ready, you can either manually create products or use the Product API. 

 

3- Select a scheduling mode and a booking strategy

There are multiple scheduling modes available for a RezdyConnect-enabled product:

  • No Date - a product is available everyday and there is no availability limitation for these products, customer will not choose a time when making a booking
    • the product will not be part of the availability synchronization batch
    • the available capacity will not be checked before a booking
    • product startTime will not be passed in a booking request
  • Any Date - a product is available everyday and there is no availability limitation for these products, but customer will have to choose a time when making a booking
    • the product will not be part of the availability synchronization batch
    • the available capacity will not be checked before a booking
    • product startTime will be passed in a booking request
  • Inventory Free-sell - availability is determined by sessions, but there is no limit for these sessions. Sessions are synchronized using the availability endpoint calls in a synchronization batch
    • the product will be part of the availability synchronization batch
    • the available capacity will not be checked before a booking
    • product startTime will be passed in a booking request
  • Inventory Session based - availability is determined by sessions, they are synchronized using the availability endpoint calls, both batch and before checkout refresh
    • the product will be part of the availability synchronization batch
    • the available capacity will be checked before a booking
    • product startTime will be passed in a booking request

There are currently 2 common booking strategies to implement the integration:

  • 1-step booking strategy - requires implementation of availability and booking endpoints, and optionally cancellation endpoint
  • 2-steps booking strategy (recommended) - requires implementation of availability, reservation, confirmation and cancellation endpoints

1-step booking strategy

Flow for 1-step booking strategy:

  1. Once a day, Rezdy calls GET /availability to refresh the next 6 month's availability for each product (6 x 1 month)
  2. Rezdy shows cached sessions to customers and agents in general searches
  3. When the customer or agent selects a specific session, Rezdy calls GET /availability to refresh that single time's availability and pricing
  4. If there are seats available, checkout is possible
  5. During the checkout process, Rezdy will:
    1. GET /availability to refresh that single time's availability
    2. Process payment (when applicable)
    3. Create the booking on Rezdy (or external agent system)
  6. Rezdy then calls the product's POST /booking endpoint to create the booking in the supplier system

There are disadvantages using this strategy:

  • customer payment is processed before the booking is created in your system, which may lead to booking inconsistency. This is especially risky in case of credit card payment on the agent side.
  • In some situations there might be no evidence of the failed booking in your system (e.g. internal failure of supplier system). We will generate alerts by email which will need to be dealt with manually.

 

2-steps booking strategy (recommended)

We recommend using this strategy, because it minimizes the booking integrity issues between Rezdy and external systems.

Rezdy will use availability endpoint to refresh availability and pricing. Once a customer submits a booking to Rezdy, Rezdy will ensure the availability in your system. Rezdy will then send a booking in 'PROCESSING' state to your system by calling the Reservation endpoint. If that call fails, we stop the booking process.

Otherwise, we create booking internally and charge the customer. If the charge fails, we cancel the booking internally and call your Cancellation endpoint. If no error occur during the booking flow, we call the Confirmation endpoint.

Screen&requests flow for 2-steps booking strategy:

  1. Rezdy shows cached sessions to a customer
  2. Customer selects a session
  3. Rezdy calls the product's Availability endpoint to refresh the session availability and pricing
  4. If there are seats available, customer can proceed with the booking
  5. Booking is created on Rezdy
  6. Rezdy calls the product's Booking Reservation Endpoint
  7. If error response is received, the booking will be deleted and customer will be notified
  8. The customer's payment is processed
  9. If any error occur, the booking will be deleted and Booking Cancellation Endpoint will be called
  10. Otherwise Rezdy calls Booking Confirmation Endpoint

Note: Availability refresh call in the flow will be skipped for all scheduling modes except Inventory session based.

4- Implement REST endpoints

Product code mapping

Rezdy product codes are used when making availability or booking call, so you can either:

  • Map Rezdy product codes to your own internal codes in your RezdyConnect implementation
  • Specify your internal codes as a part of the endpoints URLs for each product using query parameters

 

Events triggering endpoint calls

There are several events that can result in a call to the external endpoints. Calls to the booking endpoints are based on the booking strategy you implement and scheduling mode.

Availability calls to refresh availability and pricing will occur when:

  1. Daily batch update - load the next 6 months availability for each product, in 1-month intervals
  2. Customer selects a specific session and starts a checkout process - refresh of the specific session, start and end time are same (does not apply for the requests with intervals, when  multiple sessions are matched)
  3. Product scheduling settings are updated - one week availability is pulled to test the endpoint

Note: Current limitations: public API availability calls currently don't triggers external availability refresh, just a booking request will internally check the session availability and triggers refresh, thus stops a booking if there is no availability. These are just use case when you use RezdyConnect integration and resell the same products using API. An update will be released soon, which will trigger the availability refresh in a case when a single session is matched in the API availability request.

There is an algorithm which determines if a session should be served from cache or a refresh is required. It applies when a specific session is requested (the case 2.), therefore the remote call might not be triggered, but the cached availability is used. 

The below rules force the availability refresh from the external endpoint:

  • the requested session startTime in less than 7 days ahead,
  • the requested session has less than 4 seats available 
  • the last update of the requested session was more then 10 mins ago

These default values can be overridden per company, please let us know if you need it.

Daily batch update availability calls

Below is an example of the start and end time parameters for batch availability refresh for 6 months. Rezdy will do separate calls for each month, start time is the 00:00 of the first day of the month, end time is 23:59:59 last day of the month of the suppliers timezone setup on Rezdy. Exception is the first month, when the start time is set to the current time. Past sessions are never refreshed. In the example batch starts on Mar 13 14:20:00 UTC, when supplier's timezone is UTC+14.

startTime - endTime: Mar 13 14:20:00 UTC - Mar 31 12:59:59 UTC
startTime - endTime: Mar 31 13:00:00 UTC - Apr 30 13:59:59 UTC
startTime - endTime: Apr 30 14:00:00 UTC - May 31 13:59:59 UTC
startTime - endTime: May 31 14:00:00 UTC - Jun 30 13:59:59 UTC
startTime - endTime: Jun 30 14:00:00 UTC - Jul 31 13:59:59 UTC
startTime - endTime: Jul 31 14:00:00 UTC - Aug 31 13:59:59 UTC

Note: Rezdy can use a customized configuration for batch availability refresh, which can be setup to better reflect your system. The batch start time, frequency and date range can be configured. Please let us know if you need to change the default configuration.

 

Model and sample Requests & Responses

Availability Endpoint

  • Regardless of using 1-step or 2-steps booking strategy, you will need to implement the availability endpoint. Rezdy will call the endpoint using HTTP GET method and decorate the endpoint URL with additional query parameters productCode, startTime, endTime. All three parameters are mandatory - always set by Rezdy.
  • Session response contain an array of Session objects
  • Session response should contain all the sessions between specified startTime and endTime, including session with 0 availability (Sold out).
  • If you don't need to support dynamic pricing per session, or the pricing of a certain session is the same as the product default price, you can omit priceOptions array.
  • Session startTime and endTime represents UTC time, not a local time. 

Let's consider the endpoint URL, configured as Product Availability Endpoint, to be:

https://api.supplier.com/availability?apiKey?ABC123456

Sample request made by Rezdy (to refresh availability and pricing of a single session), will be as follows:

GET: https://api.supplier.com/availability?apiKey?ABC123456&productCode=ABCDEF&endTime=2014-03-04T22:00:00Z&startTime=2014-03-04T22:00:00Z

Sample RESPONSE:

{
  "requestStatus": {
    "success": true,
    "version": "v1"
  },
  "sessions": [
    {
      "productCode": "ABCDEF",
      "startTime": "2014-03-04T22:00:00.000Z",
      "endTime": "2014-03-05T00:00:00.000Z",
      "allDay": false,
      "seats": 10,
      "seatsAvailable": 10,
      "priceOptions": [
        {
          "price": 99.99,
          "label": "Adult"
        }
      ]
    }
  ]
}

Booking (Reservation, Confirmation and Cancellation) endpoint

Booking workflow and endpoints are different based on your selected booking strategy. Some general rules apply in any case:

  • Request and (successful) response contain exactly one Booking object in the Request body/Response envelope
  • Rezdy always sends a single bookingItem per booking in the request, and you should never return multiple items per booking in your response. Also the order of participants in the participants array has to be maintained between request and response
  • you can either used the Rezdy generated orderNumber from the request in the format R12345 or you can generate you own and return it in the response, Rezdy will then use your order number to store the booking internally and use your orderNumber for the next requests (confirmation, cancellation) in case of 2-steps booking
  • Rezdy will append orderNumber as the last URL path segment, before the query part, for cancellation and confirmation endpoint calls, e.g. ...cancel/R123456?apiKey...
  • if you use your own orderNumber, it has to be unique for each booking and maximum 20 characters long
  • Successful reservation and booking response must contain a booking object with at least orderNumber field and request status with success flag set to true (Cancellation endpoint, does not need to return the booking object)
  • Other fields processed by Rezdy from the booking response include participants barcodes, comments, reseller comments, pickup location

1-step booking

Let's consider your endpoint URL, configured as Product Booking Endpoint, to be:

https://api.supplier.com/booking?apiKey=ABC123456

Sample request made by Rezdy, will be as follows:

POST: https://api.supplier.com/booking?apiKey?ABC123456

{
    "orderNumber": "RHQRL3N",
    "status": "CONFIRMED",
    "supplierId": 1075,
    "supplierName": "Rezdy Demo",
    "resellerId": 9401,
    "resellerName": "Dusan",
    "resellerUser": {
      "firstName": "Dusan",
      "lastName": "Zahoransky",
      "email": "dusan@test.com"
    },
    "customer": {
      "id": 2749,
      "firstName": "Dusan",
      "lastName": "Zahoransky",
      "name": "Dusan Zahoransky"
    },
    "items": [
      {
        "productName": "DEMO Lunch Cruise with Live Music on Sydney Harbour",
        "productCode": "P347HK",
        "startTime": "2016-10-02T13:00:00Z",
        "endTime": "2016-10-03T13:00:00Z",
        "startTimeLocal": "2016-10-03 00:00:00",
        "endTimeLocal": "2016-10-04 00:00:00",
        "quantities": [
          {
            "optionLabel": "Adult",
            "optionPrice": 75,
            "value": 1
          },
          {
            "optionLabel": "Child under 12",
            "optionPrice": 55,
            "value": 1
          }
        ],
        "totalQuantity": 2,
        "amount": 130,
        "extras": [],
        "participants": [
          {
            "fields": [
              {
                "label": "First Name",
                "value": "Dusan",
                "requiredPerParticipant": false,
                "requiredPerBooking": false
              },
              {
                "label": "Last Name",
                "value": "Zahoransky",
                "requiredPerParticipant": false,
                "requiredPerBooking": false
              }
            ]
          }
        ],
        "subtotal": 75,
        "pickupLocation": {
          "locationName": "Town hall Train Station",
          "address": "Town Hall Train Station, Sydney, New South Wales, Australia",
          "pickupTime": "2016-10-02 23:45:00",
          "pickupInstructions": "Meet outside the station\r\nPlease be at this location 15 minutes before pick up"
        },
        "vouchers": []
      }
    ],
    "totalAmount": 130,
    "totalCurrency": "AUD",
    "totalPaid": 130,
    "totalDue": 0,
    "dateCreated": "2016-09-28T06:40:03Z",
    "dateConfirmed": "2016-09-28T06:40:03Z",
    "datePaid": "2016-09-28T06:40:05Z",
    "dateReconciled": "2016-09-28T06:40:03Z",
    "comments": "",
    "internalNotes": "",
    "payments": [
      {
        "type": "CREDITCARD",
        "amount": 130,
        "currency": "AUD",
        "date": "2016-09-28T06:40:05Z",
        "label": "Payment proceed at agent side"
      }
    ],
    "fields": [],
    "source": "MARKETPLACE_PREF_RATE",
    "resellerSource": "INTERNAL",
    "sourceChannel": "dusan",
    "resellerComments": "",
    "commission": 11.25,
    "vouchers": [],
    "paymentOption": "CREDITCARD"
  }

Sample response:

{
  {
  "requestStatus": {
    "success": true,
    "version": "v1"
  },
  "bookings": [
    {
      "orderNumber": "MyOrderNumber1490069083572",
      "items": [
        {
          "participants": [
            {
              "fields": [
                {
                  "label": "Barcode",
                  "value": "XYZ123"
                }
              ]
            }
          ],
          "pickupLocation": {
            "locationName": "Central Station"
          }
        }
      ],
      "comments": "Thank you for booking. Please call us to confirm the pickup and specify drop-off location on 012345679.",
      "resellerComments": "BookingReference: 123456789"
    }
  ]
}

2-steps booking

Let's consider your endpoints configuration:

Capture.PNG

Endpoints URLs can be same or different, configuration is up to you. For all 3 requests, Reservation, booking and cancellation, the request data will be almost similar. Rezdy will always send a full booking object. Only differences among the calls is HTTP method used for the request and booking status:

  • Reservation endpoint: HTTP POST, booking.status = "PROCESSING"
  • Booking endpoint: HTTP PUT, booking.status = "CONFIRMED"
  • Cancellation endpoint: HTTP DELETE, booking.status = "CANCELLED" or "ABANDONED_CART"

Reservation request example made by Rezdy:

POST: https://api.supplier.com/reserve?apiKey?ABC123456 

{
    "orderNumber": "RHAUL5R",
    "status": "PROCESSING",
    "supplierId": 1075,
    "supplierName": "Rezdy Demo",
    "resellerId": 9401,
    "resellerName": "Dusan",
    "resellerUser": {
      "firstName": "Dusan",
      "lastName": "Zahoransky",
      "email": "dusan@test.com"
    },
    "customer": {
      "id": 2749,
      "firstName": "Dusan",
      "lastName": "Zahoransky",
      "name": "Dusan Zahoransky"
    },
    "items": [
      {
        "productName": "DEMO Lunch Cruise with Live Music on Sydney Harbour",
        "productCode": "P347HK",
        "startTime": "2016-10-02T13:00:00Z",
        "endTime": "2016-10-03T13:00:00Z",
        "startTimeLocal": "2016-10-03 00:00:00",
        "endTimeLocal": "2016-10-04 00:00:00",
        "quantities": [
          {
            "optionLabel": "Adult",
            "optionPrice": 75,
            "value": 1
          },
          {
            "optionLabel": "Child under 12",
            "optionPrice": 55,
            "value": 1
          }
        ],
        "totalQuantity": 2,
        "amount": 130,
        "extras": [],
        "participants": [
          {
            "fields": [
              {
                "label": "First Name",
                "value": "Dusan",
                "requiredPerParticipant": false,
                "requiredPerBooking": false
              },
              {
                "label": "Last Name",
                "value": "Zahoransky",
                "requiredPerParticipant": false,
                "requiredPerBooking": false
              }
            ]
          }
        ],
        "subtotal": 75,
        "pickupLocation": {
          "locationName": "Town hall Train Station",
          "address": "Town Hall Train Station, Sydney, New South Wales, Australia",
          "pickupTime": "2016-10-02 23:45:00",
          "pickupInstructions": "Meet outside the station\r\nPlease be at this location 15 minutes before pick up"
        },
        "vouchers": []
      }
    ],
    "totalAmount": 130,
    "totalCurrency": "AUD",
    "totalPaid": 130,
    "totalDue": 0,
    "dateCreated": "2016-09-28T06:40:03Z",
    "dateConfirmed": "2016-09-28T06:40:03Z",
    "datePaid": "2016-09-28T06:40:05Z",
    "dateReconciled": "2016-09-28T06:40:03Z",
    "comments": "",
    "internalNotes": "",
    "payments": [
      {
        "type": "CREDITCARD",
        "amount": 130,
        "currency": "AUD",
        "date": "2016-09-28T06:40:05Z",
        "label": "Payment proceed at agent side"
      }
    ],
    "fields": [],
    "source": "MARKETPLACE_PREF_RATE",
    "resellerSource": "INTERNAL",
    "sourceChannel": "dusan",
    "resellerComments": "",
    "commission": 11.25,
    "vouchers": [],
    "paymentOption": "CREDITCARD"
  }

Sample Reservation response:

{
  {
  "requestStatus": {
    "success": true,
    "version": "v1"
  },
  "bookings": [
    {
      "orderNumber": "RHAUL5R"
     }
  ]
}

 

Sample Booking request made by Rezdy:

PUT: https://api.supplier.com/book?apiKey?ABC123456

{
    "orderNumber": "RHAUL5R",
    "status": "CONFIRMED",
...

Sample Booking response:

{
  {
  "requestStatus": {
    "success": true,
    "version": "v1"
  },
  "bookings": [
    {
      "orderNumber": "RHAUL5R"
     }
  ]
}

 

Sample Cancellation request made by Rezdy:

PUT: https://api.supplier.com/cancel?apiKey?ABC123456

{
    "orderNumber": "RHAUL5R",
    "status": "CANCELLED",
...

Sample Cancellation response:

{
  {
  "requestStatus": {
    "success": true,
    "version": "v1"
  }
}

 


5- Setup your RezdyConnect URLs

Chose the availability mode and related settings and the booking strategy and the supported format. Based on the setting your will need to specify necessary endpoints URLs. After you Save the product, Rezdy will request one month availability, to ensure the availability endpoint is working fine and validates URLs for other endpoints.

You can either use UI or API to do the configuration. See the screenshot below for the configuration via UI.


productRezdyConnectSettings.PNG

With the API use the following services:

To enable and update RezdyConnect settings for a product:

PUT: https://api.rezdy.com/latest/products/[PRODUCT CODE]/rezdyConnect?apiKey=[API KEY]

{
  "productCode": "PHJGAG",
  "externalApiFormat": "JSON",
  "externalAvailabilityApi": "https://n3sf1z2wfc.execute-api.us-west-2.amazonaws.com/prod/supplierapi/checkavailability?apiKey=ABC123456789&externalProductCode=ABCDEF",
  "externalReservationApi": "https://n3sf1z2wfc.execute-api.us-west-2.amazonaws.com/prod/supplierapi/booking/book?apiKey=ABC123456789",
  "externalBookingApi": "https://n3sf1z2wfc.execute-api.us-west-2.amazonaws.com/prod/supplierapi/booking/confirm?apiKey=ABC123456789&externalProductCode=ABCDEF",
  "externalCancellationApi": "https://n3sf1z2wfc.execute-api.us-west-2.amazonaws.com/prod/supplierapi/booking/cancel?apiKey=ABC123456789&externalProductCode=ABCDEF",
  "externalBookingStrategy": "ONE_STEP_BOOKING"
}

To disable RezdyConnect settings for a product:

DELETE: https://api.rezdy.com/latest/products/[PRODUCT CODE]/rezdyConnect?apiKey=[API KEY]

To get a product's current RezdyConnect settings:

GET: https://api.rezdy.com/latest/products/[PRODUCT CODE]/rezdyConnect?apiKey=[API KEY]

6- (Optional) Using Webhooks and Rezdy API

This section will be available soon

Have more questions? Submit a request
Return to top
Was this article helpful?
0 out of 0 found this helpful

Related articles

© 2020 Copyright Rezdy