Booking Guide

The JSON APIs booking workflow uses a workflow of multiple calls to create a held reservation for later fulfillment.

This guide summarizes the steps in the workflow. Endpoints, requests, responses, and examples are in the API Reference for each step, linked below.

Related Content: JSON APIs Guide, Reservation Retrieve Guide, Booking Guide for Failed/Shell Bookings, Booking Guide for Air, Hotel, & Car, Ticketing Guide

In this topic:

• Basic Concepts
• Workbench Actions
• Booking Workflow Summary
• Booking Workflow Diagram
• Other Booking Workflows
  • Expired Booking Workflow
  • Add Product Booking Workflow (without Search and Price)
  • NDC Instant Pay Workflow
• Book Commit Response Layout Diagram
• Optional Actions at Workbench Commit
  • Create Retention Segments
  • Set up Reservation Shell in Case of Booking Failure
  • Confirm Involuntary Schedule Change
  • Update or Delete Ticketing Time Limit Date
  • Add ReceivedFrom

Basic Concepts

The AirReservation API uses a workflow of multiple calls to create a workbench session, add a flight offer to the workbench, add each traveler to the workbench, and commit the workbench. Several optional steps are supported prior to the workbench commit, such as adding remarks and special service requests, selecting seats, or adding paid ancillaries. Once the workbench is successfully committed and the flights confirmed by the carrier, the entire record of all details added during the booking workflow is collectively referred to as the reservation. The terms booking and reservation are interchangeable.

Some agents and airlines may use the term PNR for a reservation . Because PNR is specific to GDS only, this online help uses the more generic terms reservation or booking instead.

Committing the workbench at the end of the booking workflow creates a held booking: The booking is confirmed by the airline but not yet ticketed. The booking must still be ticketed in an additional workbench session, and will expire if ticketing doesn't take place within a certain time, usually within 24 hours of booking. Expiration and ticketing time limits are returned in the commit response in TermsAndConditionsFull/ExpiryDate and PaymentTimeLimit.

The commit response returns all details added to date about the booking, which generally include the offer (actual air segments booked), traveler details, and reservation confirmation information. A successful booking returns a unique six-digit alphanumeric number called the reservation locator in Receipt/Confirmation/Locator.

After booking you can retrieve booking details with a Reservation Retrieve.

While the above is the standard booking workflow, the JSON APIs also support these alternate booking workflows (see below):

• Expired Booking workflow: Renew an expired booking, meaning that the offer on a held reservation has expired and can no longer be ticketed at the held price.

• Add Product booking flow: Start with booking and skip the Search and AirPrice steps; however, you must already have full details for the itinerary to book. GDS only.

• Instant Pay workflow: Create the reservation and issue the ticket/s in the same workbench session. NDC only; not supported for GDS.

• Ticketless carriers workflow: For ticketless carriers, the booking is issued and completed in the commit step; there is no separate ticketing step.

Workbench Actions

All steps in the booking workflow take place in a workbench session, which is like a container that holds all details as they are added before sending them to the carrier all at once.

To start a new booking, create a new workbench. The response returns a workbench identifier that is sent in the HTTP request of all subsequent transactions in that workbench. When the workbench is committed, the booking details become part of the reservation record and the workbench is discarded.

Once a booking is made and a reservation issued, any further updates or changes to that reservation, including ticketing, generally also take place in a workbench. Because the initial booking has already been committed, this is called a post-commit workbench and is created using the reservation locator of the booking to modify.

Workbench Requests List

The table below lists all available actions and links to the API reference for each request, which provides endpoints and examples. These workbench actions are not sequential and would not all take place in the same session.

Workbench Action	Description and Notes	API Reference
Create an initial booking workbench	Create new workbench when no booking exists. Returns an identifier for the workbench that must be sent in all subsequent calls in that session. First step in the initial booking workflow.	Create New Workbench API Reference
Create post-commit workbench	Initiate a workbench for an existing booking by sending the reservation locator code in the POST request. First step for any workbench session to modify, update, or ticket an existing reservation.	Create Post-Commit Workbench API Reference
Retrieve workbench	Returns all workbench details added up to the time of the retrieve.	Retrieve Workbench API Reference
Delete data from the workbench	Deletes selected data from the workbench, such as a remark. Only specific information can be deleted.	Several add/delete requests are supported in both initial and post-commit workbench. See Traveler Modify Guide and Remarks and Service Requests Guide.
Commit the workbench	Closes the workbench session and finalizes all transactions in workbench. Depending on the workbench, the commit may create a held booking, issue a ticket, update a reservation, or exchange a ticket. Final step in all workbench sessions.	Commit Workbench API Reference
Discard workbench	Discards the workbench and deletes all data in it.	Workbench Discard API Reference

Initial Booking Workflow

To create a booking, at a minimum, you must create a workbench session, add an air offer, add at least one traveler, and commit the workbench. Certain optional steps are also supported.

The following table summarizes the required and optional steps. The API reference for each request provides endpoints, payloads, and examples.

Step #	Booking Workflow Step	Description and Notes	API Reference
1	Create the workbench	First step in the workflow. Returns a system-generated identifier for the workbench that must be sent in subsequent requests for that workbench.	Create New Workbench API Reference
2	Add offer	Add the offer (flight details) to the workbench. Supports either a full payload request that sends all required itinerary details, or a reference payload request that references flights returned in a preceding Search response. You can add either the offer or traveler/s first. Returns a system-generated identifier for the offer that is part of the booking record and must be sent in subsequent transactions about that offer. Add multiple offers You can repeat the Add Offer step, with either the full or reference payload, as needed to combine multiple offers into one reservation. While there is no specific limit on the number of offers that can be combined, a reservation cannot have more than 16 flight segments. Booking seats and ancillaries is supported for multi-offers only after the reservation is created, not in the initial booking workflow.	Add Offer Reference Payload API Reference   Add Offer Full Payload API Reference
3	Add traveler	Send traveler details such as name and contact information, and optional comments and service requests. You can add either the offer or traveler/s first. Returns a system-generated identifier for the traveler that is part of the reservation record and sent in subsequent transactions about that traveler, such as seat selection. Optionally, if the traveler has a personal and/or business profile in the Travelport host system, you can send the Host Profile Move request to copy traveler details into the JSON API booking workflow instead of sending Add Traveler. GDS only; not supported for NDC. Travelers must be added one at a time. Send each traveler in a separate request. Add travelers in the same order as their PTC was sent in preceding Search and/or Price requests. For example, if you searched for two ADT and one CHD, send an Add Traveler request for each of the two ADT passengers and then send a third Add Traveler request for the CHD passenger. Any traveler sent without a PTC (passenger type code) value is defaulted to ADT. PTC can be sent or omitted for ADT travelers. An INF (infant) cannot be added without an ADT (adult) PTC already on the itinerary. Only select traveler information can be modified after a traveler is added. See Traveler Modify Guide.	Add Traveler API Reference Remarks & Service Requests Guide
optional	Shop and book seats	Requesting seat availability and adding seats is supported in the initial booking workflow as per the Seats Guide after adding an offer and traveler. Seats and ancillaries are not supported for multi-offers (see step 2 above) in this initial booking workflow, only after the booking is created.	Seats Guide
optional	Shop and book ancillaries	Certain paid ancillaries are supported in the initial booking workflow as per the Ancillaries Guide after adding an offer and traveler.	Ancillaries Guide
optional	Add comments and service requests	Certain comments/service requests can be added separately from the Add Traveler payload.	Remarks & Service Requests Guide
optional Supported only for GDS in initial booking flow	Add form of payment	Store form of payment (FOP) information with the reservation to be used subsequently in ticketing. The response returns a system-generated identifier for the FOP that is part of the reservation record and sent in subsequent Add Payment request. Adding FOP for GDS in booking is optional. If sent, FOP is stored and retrieved later during the ticketing. If not sent in booking, FOP is required at ticketing. Adding FOP for NDC is not supported in booking, only at ticketing or in the Instant Pay workflow. If FOP is added but payment and ticketing are not completed, the FOP is not stored and is not available for retrieval during ticketing. Ticketless carriers require FOP. The booking is issued and completed in the commit step; there is no ticketing step. Add Multiple Forms of Payment (GDS only) For GDS only, you can send up to two FOP in either the booking or ticketing workflow by repeating the Add Form of Payment step for each FOP. Note that at ticketing you must send a separate Add Payment request for each FOP. Multiple FOP are currently supported only for bookings with a single passenger. The additional FOP can be credit card, non-standard credit card, or cash.	Add Form of Payment API Reference
4	Commit the workbench and create held booking	Final step in the booking workflow. Creates a held booking for later ticketing. A successful workbench commit returns a reservation confirmation from the supplier, creates a held booking, and returns a unique alphanumeric code for that booking, called a reservation locator code. The response is largely the same as but not identical to a Reservation Retrieve response. The workbench commit does not return any document override or accounting comments added; these can be requested in a subsequent Reservation Retrieve. Commit for ticketless carriers creates a booking with the carrier. There is no ticketing step. Notes on workbench commit at end of the initial booking workflow If any pricing modifier sent in the Add Offer full payload or reference payload request does not have any fares associated with it, the commit will fail and return the error message No Fare Found. Pricing happens at the commit, not the Add Offer step. Shell Reservations for Failed Bookings Optionally, you can choose to create a shell booking in the event of a booking failure either because the offer cannot be added or the fare cannot be quoted. This reservation shell retains the traveler details and allows the booking to be completed later. To do so, in the initial booking workflow, send the autoDeleteDate query parameter at the workbench commit. See Booking Guide for Failed/Shell Bookings. Retention Segments By default, reservation details are stored for one month after all travel on the itinerary is completed. You can extend this time by setting a purge date in the autoDeleteDate query parameter at the workbench commit in the initial booking workflow. See Retention Segments in the Booking Guide. CarrierLocator Code Delay at Booking In some instances, the carrier requires additional time to return the carrier locator code, which can be an issue for agencies that require this code at the time of booking. So, if the carrier locator code is not immediately available, AirReservation makes one attempt to retrieve the reservation from the carrier. If the carrier locator code cannot be retrieved, AirReservation returns the warning: Carrier locator code not returned by carrier/provider. Please try to retrieve later and agencies must retrieve the reservation later. This can happen in any booking scenario upon commit but is most common when the booking contains an ancillary such as a wheelchair.	Commit Workbench API Reference

Booking Workflow Diagram

Other Booking Workflows

Expired Booking Workflow

The JSON APIs support renewing an expired booking, meaning that the offer on a held reservation has expired and can no longer be booked.

For GDS, use the Add Offer request, either full payload or reference payload, to add an offer to an existing reservation when the current offer has expired. Start with a workbench create request, add the new offer, and commit the workbench.

For NDC, use Standalone Reprice to reprice the itinerary on a held booking either before or after the price guarantee expires. You can then add the repriced itinerary to the workbench and either hold or ticket. See the NDC Modify, Cancel, and Exchange Guide for supported options and workflows.

Add Product Booking Workflow (without Search and Price)

As an alternative to not only the above booking workflow but also the entire JSON API minimum required workflow, you can send Add Product instead of Add Offer. Add Product allows you to start with booking and skip the Search and AirPrice steps; however, you must already have full details for the itinerary to book. This full payload request is best suited for corporate customers who frequently travel the same itinerary and do not need or want to check price or alternative options. The request sends flight and class of service data as sourced from outside the JSON APIs.

As part of this flow, you have the option to check pricing with a Standalone Price request (AirReservation 23.11.26 and later). You can send Standalone Price in either the initial booking workbench, the ticketing workbench, or in a post-commit workbench session without ticketing.

Although not shown below, you can send the optional Fare Display request in this flow to retrieve fare rule text for an itinerary.

The NDC Instant Pay workflow (book and issue ticket in the same session) and the Add Product workflow do not support ancillaries or seats. These can be added after the reservation is created.

NDC Instant Pay Workflow

The Instant Pay workflow, supported only for NDC, allows you to book and ticket in the same workbench session.

The NDC Instant Pay workflow (book and issue ticket in the same session) and the Add Product workflow do not support ancillaries or seats. These can be added after the reservation is created.

 

Book Commit Response Layout Diagram

The following diagram illustrates the general structure of the Book Commit response, including most high-level objects. Objects returned depend on the data added in the booking workflow.

Optional Actions at Commit

Create Retention Segments

By default, reservation details are stored for one month after all travel on the itinerary is completed. This means you can continue to retrieve the reservation for one month after travel, at which time the reservation is purged and no longer available. You can extend this time by setting a purge date that is up to 331 days from the date the reservation was created. To do so, send the autoDeleteDate query parameter in the workbench commit for the initial booking workflow. Adding a purge date creates a retention segment on the reservation.

The autoDeleteDate value is returned in the Reservation Retrieve, Workbench Commit, and Create Post-Commit Workbench responses, as shown in the example excerpt below. To update or delete the autoDeleteDate on an existing booking, send the autoDeleteDate query parameter at the end of a post-commit workbench session.

Create Reservation Shell in Case of Booking Failure

In the case of bookings that fail due to inability to either add the offer or quote a fare, AirReservation creates a reservation shell that retains traveler details if the autoDeleteDate query parameter is sent at commit. This allows an agency to contact the customer offline through their call center and complete the booking as necessary, or for the booking to be completed with the JSON API booking workflow.

See the Booking Guide for Failed/Shell Bookings for details and supported scenarios.

Confirm Involuntary Schedule Change

AirReservation supports an optional workbench commit request payload that confirms a carrier-initiated schedule change. When the flight schedule on an existing reservation has changed, a Reservation Retrieve returns a value of either TK or UN in OfferStatus/StatusAir/code to indicate the change. To accept the schedule change, send the workbench commit with a payload including the indicator scheduleChangeAcceptedInd set to true. You do not need to create a workbench session first.

Update or Delete Ticketing Time Limit Date

AirReservation supports an optional workbench commit request payload that adds or deletes the ticketing time limit for a booking. This is the last day to ticket the booking before the offer expires.

Add ReceivedFrom

AirReservation supports an optional workbench commit request payload that sends a ReceivedFrom object. This allows online travel agencies (OTAs) and agents using the Deem platform to include an optional receive field at reservation creation or update.