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:
{ "error": { "code": "string", "data": { "string": "string" }, "message": "string" }}| Field | Type | Description |
|---|---|---|
| code | String | A brief description of the error; must be one of BAD_REQUEST, CONFLICT, ENTITY_TOO_LARGE, FAILED_DEPENDENCY, FORBIDDEN, GONE, INTERNAL_SERVER, or NOT_FOUND. |
| data | Map[string]string | An optional collection of textual key-value data relevant to the error. |
| message | String | A human-readable description of the error event. |
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.
{ "id": "<UUID>", "start": "2020-06-11T10:00:00-05:00", "end": "2020-06-11T11:00:00-05:00", "capacity": 1, "maxCapacity": 1}| Field | Type | Description |
|---|---|---|
| id | UUID | A universally-unique identifier unique to this Availability.
Note: Future versions of the Partner API will allow unique, arbitrary strings as a valid id, nullifying the UUID requirement. |
| start | String (RFC-3339 timestamp) | The beginning of the availability window. |
| end | String (RFC-3339 timestamp) | The end of the availability window. |
| capacity | Integer | The number of traveler slots remaining for this Product/Rate between start and end. |
| maxCapacity | Integer | (Optional) The maximum capacity of this Availability. capacity must not exceed this value. A value of -1 indicates the maximum capacity is not set / unlimited. |
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.
{ "availabilities": { "byProduct": { "availability": [ <Availability> ] }, "byRate": { "5e12158e-ac17-11ea-9b25-67102a1299cc": { "availability": [ <Availability> ] } }, "expires": "2020-06-11T12:34:56-00:00", "productId": "5afbd2ae-ac17-11ea-9ddd-4fc2a6ad8f62", "retrieved": "2020-06-11T11:34:56-00:00" }}| Field | Type | Description |
|---|---|---|
| byProduct | Object | A list of a Product's availabilities across all of its Rates. |
| byRate | Object | A list of a Product's availabilities grouped by Rate ID |
| expires | String (RFC-3339 timestamp) | Advises the Booking API client to discard this availability after the specified timestamp. |
| productId | UUID | The productId associated with all Availabilities in the response. |
| retrieved | String (RFC-3339 timestamp) | Time at which the response was issued. |
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.
{ "availability": {}, "bookable": true}| Field | Type | Description |
|---|---|---|
| availability | Object | Contains an availability within the request parameters. |
| bookable | Boolean | Indicates whether the returned availability is bookable with the parameters provided. |
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 responsebooking.idto a random UUID value. - The top-level
Barcodeobject is for internal use.
{ "booking": { "barcode": {<Barcode>}, "channelId": "<UUID>", "customer": {<Customer>}, "ext": { "string": "string" }, "holdExt": { "string": "string" }, "holdId": "<UUID>", "id": "<UUID>", "items": [<BookingItem>], "partnerId": "string", "resellerBookingRef": "string" }}| Field | Type | Description |
|---|---|---|
| barcode | Object | (Optional) Represents a reseller's internal booking identifier. |
| channelId | UUID | The ID of the channel that placed the booking request. |
| customer | Object | Information on the primary traveler. |
| ext | Map[string]string | A map of reseller-defined data. |
| holdExt | Map[string]string | A map of reseller-defined hold data. |
| holdId | UUID | A holdId, if a hold was acquired for this Booking. |
| id | UUID | Optional identifier to assign the Booking. |
| items | Object Array | The list of Items requested by the Channel on behalf of a traveler. |
| partnerId | UUID | An alternative identifier for the Booking provided by the reseller. |
| resellerBookingRef | string | Used to pass additional data from certain Redeam Channel Gateways. |
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.
{ "booking": { "tickets": [ { "barcode": { "format": "", "value": "" }, "bookingItemIds": [""], "extensions": { "key": "value" }, "guests": [ { "count": 1, "typeCode": "", "typeModifier": "", "typeName": "" } ], "leadTraveler": {}, "status": "" } ] }}| Field | Type | Description |
|---|---|---|
| barcode | Object | The value to be consumed by the operator as proof of purchase. A supported barcode encoding must be present in barcode.format, or otherwise be set to TEXT to display the value in a human-readable format. |
| bookingItemIds | Array[String] | The booking.item.id values associated with this ticket. |
| extensions | Map[String]String | Extra, customized information to provide the Booking API Client. |
| guests | Array[Object] | The guest object defines a type & count of traveler on the ticket. |
| guest.count | Int | The number of guests matching this type |
| guest.typeCode | String | The Rate.Prices[].Traveler.AgeBand from the Price referenced by the Booking Item that corresponds to this ticket. |
| guest.typeModifier | String | The Rate.Prices[].Traveler.Modifier from the Price referenced by the Booking Item that corresponds to this ticket. |
| guest.typeName | String | The Rate.Prices[].Traveler.Name from the Price referenced by the Booking Item that corresponds to this ticket. |
| leadTraveler | Object | Copy of the booking.items[].traveler who leads this ticket. |
| status | String |
The timeline list (below) reflects the history of status changes on the booking.
{ "booking": { "timeline": [ { "timestamp": "2020-08-04T10:46T38-06:00", "typeOf": "OPEN" } ] }}| Field | Type | Description |
|---|---|---|
| timestamp | String | Timestamp (RFC3339) of when the booking entered status typeOf. |
| typeOf | String | Status of the booking at timestamp; see table below. |
| Status | Description |
|---|---|
| CANCELLED | A previously OPEN booking can no longer be exchanged for goods or services. |
| DELETED | Internal status; booking is not publicly available. |
| OPEN | Booking is available for redemption, and can be exchanged for goods or services. |
| PENDING | A new booking is transitioning into OPEN or CANCELLED, pending an external or long-running process. Indicates to the Booking API client that they may need to check back later for the status of their booking. |
| REDEEMED | One or more tickets on the booking have already been exchanged for goods or services. |
| RELEASED | Used on holds only (not bookings). |
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.
{ "hold": { "expires": "<Timestamp>", "ext": { "string": "string" }, "id": "<UUID>", "items": [<HoldItem>], "partnerId": "string", "retrieved": "<Timestamp>", "status": "string", "timeline": [<TimelineEvent>] }}| Field | Type | Description |
|---|---|---|
| expires | String (RFC-3339 timestamp) | Time at which Hold transitions from ACTIVE to EXPIRED. |
| ext | Map[string]string | A map of reseller-defined data. |
| id | UUID | A unique identifier for the Hold. |
| items | Array | A list of items to be reserved by this Hold. |
| partnerId | string | An alternative identifier for the Hold provided by the reseller. |
| retrieved | String (RFC-3339 timestamp) | Time at which the response was issued. |
| status | string | Reflects the Hold's state, one of ACTIVE, EXPIRED, FAILED, PENDING, or RELEASED. |
| timeline | Object | Contains a history of the Hold's status transitions. |
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.