Overview

This document provides detailed guidance on Redeam's Partner API specification.

General

Request ID

The reqId helps trace a single request between discrete systems (the Booking API client, Redeam, and the Reservation system).

In every Partner API response, the value of (meta.reqId) must mirror the meta.reqId in the original request.

Extension and Hold Extension maps

The Extension map (ext) must be a JSON mapping of string to string ({"ext": {"key": "value"}}). If no extensions are specified, this field may be omitted from the response, or set to null.

Error Response

If a request to the Partner API is invalid, malformed, or cannot be satisfied for whatever reason, an error response must be returned.

The Partner API reference provides a high-level overview of the response codes that are acceptable for a given endpoint.

All error response bodies must be in the specified format, copied below:

Availabilities

An Availability represents a Product's traveler capacity for a given time period. To ensure that capacity is available for a reserved-capacity product, Booking Items with RESERVED-type Rates require an Availability ID, with enough capacity to satisfy all Booking Items.

Though an Availability represents a Product's capacity, every Availability must be associated with a Rate. Different Rates underneath the same Product may be available at different times. It is not possible to associate a single Availability with all Rates underneath a Product.

Availabilities may be inserted into Redeam's Availability Cache via the Channel API. If an Availability in the cache is older than 5 minutes, Redeam will forward the availability request to the Partner API, and refresh its cache with the Partner API's response.

List Availabilities

(GET) /suppliers/:supplier_id/products/:product_id/availabilities

The list availabilities endpoint provides a mechanism for reviewing a Product's availabilities between two points in time. This endpoint is often used by resellers to display a list of available times to the traveler.

This endpoint should return an HTTP 400 BAD REQUEST error if a required parameter is missing (supplier_id, product_id, start, end), or if the start / end time is invalid.

byProduct vs byRate

Availabilities may be returned in one or both aggregation arrays. However, we recommend returning Availabilities by Rate, as this aids Booking API partners in understanding which Availabilities belong to which Rates.

Fetch a Single Availability

(GET) /suppliers/:supplier_id/products/:product_id/availability

The fetch availability endpoint retrieves a single availability based upon the provided parameters. If no availability exists to satisfy the request parameters, this endpoint should return an HTTP 404 NOT FOUND response.

If an availability can be returned that matches the requested time (at), but does not satisfy the requested capacity (qty), the bookable boolean should return False.

Bookings

Create a Booking

The Create Booking endpoint /bookings accepts Booking requests from Booking API partners, and returns a fulfillable Booking response back.

Request

(POST) /bookings

The ext and holdExt mapping objects are optional fields that may contain additional data from the reseller.

• It is possible to create a Booking without specifying an id. In this case, the Partner API sets the response booking.id to a random UUID value.

• The top-level Barcode object is for internal use.

Response

In addition to the data provided by the reservation system, the Booking response must reflect back to the client all of the information passed in the request.

Most of the information provided by the reservation system is contained within the timeline and tickets arrays within the Booking response.

The tickets list (below) contains information from the reservation system for the reseller on vouchers that may be redeemed at the operator.

The timeline list (below) reflects the history of status changes on the booking.

Cancel a Booking

(PUT) /bookings/cancel/:booking_id

Upon successfully cancelling a Booking, the response body must be empty, with a status code of HTTP 204 NO CONTENT.

Retrieve a Booking

(GET) /bookings/:booking_id

This endpoint may be used by resellers to obtain up-to-date information on a customer's Booking.

If a Booking cannot be found matching the booking_id parameter, the endpoint must return an error object with an HTTP 404 NOT FOUND response code.

Holds

Acquire a Hold

(POST) /holds

The Hold request is a subset of the Hold response, which includes a retrieved timestamp, status, and timeline.

Release a Hold

(DELETE) /holds/:hold_id

A request to this endpoint transitions the Hold identified by :hold_id from ACTIVE to RELEASED.

If a Hold cannot be found matching the hold_id parameter, the endpoint must return an error object with an HTTP 404 NOT FOUND response code.

Retrieve a Hold

(GET) /holds/:hold_id

This endpoint allows resellers to check on the status of a previously acquired Hold.

If a Hold cannot be found matching the hold_id parameter, the endpoint must return an error object with an HTTP 404 NOT FOUND response code.