Booking Hold and Resume

Rapid API's Hold and Resume functionality gives you the ability to support a 2-step booking model.

As part of a 2-step booking model, a partner or traveler can put a single room on hold without an immediate charge and without incurring any cancellation penalties should they cancel or abandon the room without completing the booking.

If the traveler or partner would like to confirm the room within a given time window, they can complete the booking as a second step. If the booking is abandoned, it is automatically rolled back and the selected inventory is released.

Overview

What changes are required?

Hold and Resume uses existing APIs with new request flags and new tokenized links in responses. No new discrete API methods are required to integrate. To integrate Hold and Resume, you will need to update request and/or response handling for:

1. Booking Creation handling.
2. Booking Retrieval handling.
3. Resume - New token link handling from Retrieve response.
4. Cancel - New token link handling from Create response.

So you may best understand the full Hold and Resume process, please review this page thoroughly before referring to our individual API documentation for integration. The specific options documented on this page are also available in the respective dedicated documentation pages for our existing Booking and Booking Management APIs.

Creating an on-hold booking

The Book request now has a new boolean field called hold. Sending a value of true will put the property into a hold state.

On-hold bookings should only be left in the hold state for the minimum amount of time required for your specific application. The booking will automatically be rolled back if left in the hold state without confirmation.

A successful on-hold Book response returns an additional tokenized link that is used to resume, confirm, and pay for the on-hold booking. It also omits the rooms array normally used to provide cancellation links, since there are not yet any rooms to cancel.

Example Book response for an on-hold booking

{
    "itinerary_id": "2667552437552",
    "links": [
        {
            "rel": "retrieve",
            "method": "GET",
            "href": "/v3/itinerary/{itinerary_id}?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
        },
        {
            "rel": "resume",
            "method": "PUT",
            "href": "/v3/itinerary/{itinerary_id}?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
        },
        {
            "rel": "cancel",
            "method": "DELETE",
            "href": "/v3/itinerary/{itinerary_id}?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
        }
    ]
}

If the hold flag is used to book, no payment will be charged for the booking. The booking is completed and payment is charged only when the PUT method link in the on-hold booking response is used within the hold window.

Retrieving an on-hold booking

Retrieve an on-hold booking by using the retrieve link provided in the on-hold booking response. The method for retrieving a booking for Hold and Resume is no different than a regular retrieval for a 1-step booking and does not require a request body.

Response scenarios:

• Retrieving an on-hold booking that is still on hold will return a response with limited data, including links to immediately resume and complete or cancel the booking.
• Retrieving an on-hold booking that has been cancelled (rolled back by request) or has timed out (automatically rolled back) will return an 'itinerary not found' error.
• Retrieving an on-hold booking that has been previously resumed and confirmed will behave the same as a standard itinerary retrieval and will return the full booking details.

Example Retrieval response for an on-hold booking

{
    "itinerary_id": "8701934321257",
    "creation_date_time": "2018-03-09T14:42:58.159Z",
    "links": {
        "resume": {
            "method": "PUT",
            "href": "/v3/itineraries/8701934321257?token=QldfCGlcUA…{example trimmed for length}="
        },
        "cancel": {
            "method": "DELETE",
            "href": "/v3/itineraries/9700934721257?token=QldfCGlcUA…{example trimmed for length}="
        }
    }
}

Example Retrieval response for an on-hold booking that has been cancelled/timed out

{
    "type": "resource_not_found",
    "message": "Itinerary was not found with provided request."
}

Resuming an on-hold booking

To confirm a booking that has been placed on hold and to finalize payment, the booking must be resumed.

Resuming an on-hold booking is performed by using the resume link provided in the original on-hold book response and does not require a request body.

Response scenarios:

• Resuming an on-hold booking that is still on hold will complete the booking and return an HTTP 204 - no content response to indicate a successful completion. Use the GET link from the initial on-hold book response to retrieve the full itinerary.
• Resuming an on-hold booking that has been cancelled (rolled back by request) or has timed out (automatically rolled back) will return the same 'itinerary not found' error detailed in the previous retrieval section.
• Resuming an on-hold booking that has already been successfully resumed will return an error stating the booking is already committed.

Example Resume response for a booking that has already been resumed

{
    "type": "resume.already_resumed",
    "message": "Booking has already been resumed."
}

Cancelling an on-hold booking (roll back)

The cancel tokenized link provided in the Booking Creation and Retrieval responses acts at the itinerary level. When used, it will release the requested property from hold and roll back the held itinerary. Room-level cancellation links are only provided in the Retrieve response after a booking has been successfully resumed.

Performing a cancel operation will also return an HTTP 204 status code, the same as a successful Resume response. HTTP 204 is used in both states to indicate the server has successfully fulfilled the request and that there is no additional content to send in the response payload body.

Requesting the cancellation of a booking on hold results in the same final scenario as if the booking was allowed to automatically roll back.

Response scenarios:

• Cancelling a held booking that is still on hold will release the inventory from hold and return an HTTP 204 status.
• Cancelling a held booking that has already been cancelled (rolled back by request) or has timed out (automatically rolled back) will return the 'itinerary not found' error documented earlier on this page.
• Cancelling a held booking that has already been successfully resumed will return an 'itinerary level cancel not supported' error message. Make a Retrieve call and use the room-level links provided in the response to cancel individual rooms.

Example Cancel response for a booking that has already been resumed

{
    "type": "resume.itinerary_level_cancel_not_supported",
    "message": "Itinerary level cancel on confirmed booking is not supported."
}