Bookings
Booking objects describe a reseller's intent to reserve one or more units of a single product option.
Reference can be found here
Pending Booking Request
The first step of every booking made through the Operator Booking System (OBS), the Pending Booking request contains all the details necessary for a reseller to reserve one or more items a customer is interested in booking.
All booking requests include a supplierId provided in the request URL path, and a JSON body detailing the contents of the booking.
The following table lists the fields of the Pending Booking request which will be sent to the Operator Booking System.
Fields that are marked as Required will always be provided in the request from Redeam to the OBS API.
| Field Name | Type | Required | Description |
|---|---|---|---|
uuid | string(uuid) | Yes | Randomly-generated UUID that MUST be provided by the Reseller and tracked by both the Reseller and Operator Booking System. |
resellerReference | string | No | An OPTIONAL tracking reference for the Reseller that SHOULD be tracked by the Operator Booking System. |
channelName | string | Yes | The originating channel's human-readable name. |
channelId | string(uuid) | Yes | The unique identifier of the originating channel. |
productId | string | Yes | Identifies the product being requested in the booking. Matches against the id of a product fetched from the GET products endpoint for the same supplier. |
optionId | string | Yes | Identifies the option being requested in the booking. The option must be present underneath the provided productId. |
availabilityId | string | Yes | Identifies the time (via association with an Availability) a traveler intends to consume this booking. |
unitItems | array[UnitItem] | Yes | A list of one or more units the traveler intends to book. Each unit must be present under the provided optionId. |
holdExpirationMinutes | integer | Yes | The length of time a reseller would like the requested products to be held for a customer. |
Handling Ticket Quantities in OBS Booking Requests
- The OBS must accept both grouped and ungrouped unit items while ensuring accurate order processing and inventory tracking.
- Mixing different unit types (e.g., adults and children) is supported in both approaches.
- If unit-specific details are required (see below for examples), they should be correctly linked to each unit when using the ungrouped approach.
- The system should handle both structures interchangeably, ensuring flexibility for partner systems.
Grouped Quantities Approach
Each unitId (ticket type) appears once with a quantity greater than 1.
In this approach, quantity: 2 under "unitId": "adult" means two adult tickets are booked under a single entry, as per example below.
"unitItems": [ { "uuid": "6be0409f-181e-4520-acc1-cc6791896859", "unitId": "adult", "resellerReference": "001-002", "quantity": 2 }, { "uuid": "9cfa8a3d-4b2e-4c4b-983a-2d3f6f4e7a89", "unitId": "child", "resellerReference": "001-002", "quantity": 1 }]Ungrouped Quantities Approach
Each unitId (ticket type) is represented as a separate entry in the unitItems array, even if they share the same unitId. The purpose of using ungrouped items is to allow unit details to be provided individually for each traveler, for example a redemption code for each unit.
In this approach, each unit, even if of the same type (unitId), is listed separately with a quantity of 1.
"unitItems": [ { "uuid": "a1234567-89ab-cdef-0123-456789abcdef", "unitId": "adult", "resellerReference": "001-002", "quantity": 1, "extension": { "redemptionCode": "RDM-JS-001" } }, { "uuid": "b2345678-90ab-cdef-1234-567890abcdef", "unitId": "adult", "resellerReference": "001-002", "quantity": 1, "extension": { "redemptionCode": "RDM-JS-002" } }, { "uuid": "c3456789-01ab-cdef-2345-678901abcdef", "unitId": "child", "resellerReference": "001-002", "quantity": 1, "extension": { "redemptionCode": "RDM-ES-003" } }]Confirmed Booking Response
When a request is received by the Operator Booking System to confirm a pending booking, a successful response must include all of the contents of the booking, in addition to one or more values ('delivery options') that must be used to redeem the booking.
The deliveryMethod field indicates to the Reseller whether this confirmed booking contains one ticket per-unit, (TICKET) or one ticket per-booking (VOUCHER). These two options are mutually exclusive - the voucher field MUST not be used along side the unitItems[].ticket field.
TICKET Delivery Method
When the TICKET delivery method is used in the confirmed booking response, each Unit Item in the response must contain a Ticket object. Each ticket object MUST contain a number of delivery options equal to the quantity on the unit item.
VOUCHER Delivery Method
When the VOUCHER delivery method is used in the confirmed booking response, a single deliveryValue is returned for the entire booking. This will include the total number of UnitItems (travelers) under one voucher.
{ "deliveryMethod": "TICKET", "unitItems": [ { "uuid": "eb0586b7-0ad0-45f1-9622-d90e428d80f9", "unitId": "adult", "resellerReference": "001", "quantity": 2, "ticket": { "deliveryOptions": [ { "deliveryFormat": "QR_CODE", "deliveryValue": "01234" }, { "deliveryFormat": "QR_CODE", "deliveryValue": "56789" } ], "redemptionMethod": "DIGITAL", } }, { "uuid": "ac4827cd-6abf-4772-b28e-b0e5449379dc", "unitId": "child", "resellerReference": "002", "quantity": 1, "ticket": { "deliveryOptions": [ { "deliveryFormat": "QR_CODE", "deliveryValue": "abcde" } ], "redemptionMethod": "DIGITAL", } } ]}Cancellations
By default, pending and confirmed bookings are cancellable through the OBS API's cancel booking endpoint.
Products or options can be made un-cancellable via the redeam/policy capability. These settings only impact confirmed__booking cancellations; pending bookings may always be cancelled.
Cancellation requests are all-or-nothing, meaning it is not possible to partially cancel a pending or confirmed booking.
Pending Booking Cancellation
If a reseller does not intend to confirm a pending booking, they may opt to cancel it. Cancelling a pending booking effectively expires it immediately:
- The status on the booking changes from
ON_HOLDtoEXPIRED. - Any capacity that was held for this booking is released.
If a cancellation request is received for a booking that is already in the EXPIRED status, the server MUST return an HTTP 200 OK status code with the expired pending booking in the response body. This idempotent behavior ensures that repeated attempts to cancel the same pending booking will succeed.
Confirmed Booking Cancellation
If a traveler's plans change, they may wish to cancel a confirmed booking through the reseller they purchased their tickets through.
If the cancellation request is accepted by the OBS API, or if the booking is already in the CANCELLED status, the server MUST respond with an HTTP 200 OK status code with the cancelled booking in the response body.
Operators may use the cancellable field of the Policy capability to indicate whether a product or option can be cancelled after confirming a booking.
Process
All bookings go through a standard two-step process of reservation and confirmation.
When a new booking is created (and not REJECTEDby the server), it is placed into the ON_HOLD status. A held booking indicates that the requested units are being reserved for the client, and will remain available to the client until the booking expires (utcHoldExpiration) or the client confirms the booking.
When a booking is confirmed, the client includes contact information about the person creating the booking in the confirmation request, including their name, email address, and locales (spoken languages). If the product being booked has instantConfirmation set to true, the server will respond promptly with a booking in status CONFIRMED . The booking response will also contain the information necessary for the customer to redeem the product (ticket and barcode values).
If instantConfirmation is false, the operator is unable to immediately confirm the booking. The server will return a booking response with status PENDING. This indicates that the operator is reviewing the booking confirmation, and will accept (CONFIRM) or reject (REJECTED) the booking at a later time. The client may query the GET BOOKINGS endpoint of the API for up-to-date information on the booking's status.
