Reservation Retrieve Guide

A reservation is a general term for a booking and all associated details about that booking. This guide details the reservation retrieve, which is used to verify booking details after the reservation is created. The reservation retrieve response is also returned at the end of any workbench commit. Frequently, information returned in the reservation retrieve must be sent in subsequent transactions, including ticketing and exchanges.

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

In this topic:

Multi-Content Bookings

The Reservation Retrieve and Create Post-Commit Workbench responses return air, hotel, and/or car segments for any reservation that includes that content, called a multi-content booking. All segments must have been booked with the JSON Air APIs, JSON Hotel APIs, JSON Car APIs (full release pending), or a terminal program. You can also add either GDS or NDC air offers to a hotel and/or car booking. See the Booking Guide for Air, Hotel, & Car for workflows.

Basic Concepts

A reservation is generated when the workbench is committed as the last step of the booking workflow. From that point on, the entire record of all details added during the booking workflow is collectively referred to as the reservation. A reservation is also called a booking.

Many agents and customers use the term PNR for a reservation. Because PNR is specific to GDS only and is not used for NDC bookings, this online help uses the more generic terms reservation or booking instead.

A reservation must still be ticketed for fulfillment, and will expire if it isn't ticketed within a limited time. In this documentation, the terms reservation and booking are generally used when the ticket has not yet been issued.

The booking process uses a workflow of multiple calls to create a workbench, add details about the traveler/s and the offer, and commit the workbench to ticket the reservation. Optional steps include sending comments, and adding seats and/or a paid ancillary. Committing the workbench creates a booking and a unique alphanumeric reservation locator code to identify that booking.

Select information on the reservation can be added, deleted, or updated prior to ticketing. See the Traveler Modify Guide
To cancel a reservation, see the GDS Reservation Cancel and NDC Reservation Cancel API references.
Group bookings are not supported in the JSON APIs and are not returned in the Reservation Retrieve response.

Reservation Retrieve

See the Reservation Retrieve API Reference.

While retrieving a reservation is not a required step, you should retrieve the reservation after booking to verify details. You may also need to retrieve a reservation before other actions such as ticketing, or after a booking has been ticketed to verify book and ticket details.

The information returned in the Reservation Retrieve response varies depending on what data is in the reservation at the time of retrieve, whether the reservation has been ticketed, and whether the reservation was created by or outside of the Travelport JSON APIs.

Reservation Retrieve Response

The information returned in the Reservation Retrieve response varies depending on what details have been added to the reservation at the time of retrieve, whether the reservation has been ticketed, and whether the reservation was created outside of the Travelport JSON APIs.

Generally, the Reservation Retrieve returns:

  • Offer: One instance with details for the itinerary, such as flight details, number of passengers in each PTC, plus class of service, fare basis, and brand attributes. Depending on what the booking includes, additional instances of offer may be returned for:
  • Traveler: Instance for each traveler on the reservation. Returns all traveler details in reservation.
  • FormOfPayment: All FOPs that have been added to the reservation.
  • Payment: Payment amounts with references to the offer paid for and FOP used for that payment. Returned only for ticketed itineraries.
    • FOP and Payment are returned only for air and air-related offers, not car or hotel if applicable.
  • ReservationComment: Notepad, vendor, itinerary, and OSI remarks on the reservation.
  • PrimaryContact: The primary contact for the reservation, if primary contact details were added with a traveler.
  • Receipt: A confirmation with the reservation Locator code. If the itinerary has been ticketed, an additional instance of Receipt with the ticket number is returned.
  • ReferenceList: Any details consolidated across common objects, such as terms and conditions that apply to multiple segments. Not always returned.

Reservation Retrieve Layout Diagram

The following diagram illustrates the general structure of the Reservation Retrieve request and response, including most high-level objects. Note this diagram includes the Payment object, which is returned only after ticketing.

 

Requesting Fare Rules

Optionally, to request long fare rules, add the following to the header of your retrieve request:

“fareRuleRetrievalType”:”long”,

The response returns fare rules in the existing TermsAndConditionsFull object in a TextBlock object with the following key value pairs:

  • description: For fare rules this value is FARE RULES.
  • title: Key for numbered ATPCO fare rule category/paragraph, e.g., 16. PENALTIES.
  • id: The Terms and Conditions object section number (not the ATPCo fare rule category number).
  • TextFormatted: Array. Each may contain several instances of value, which provides the text string description from the fare rules.

Complex international itineraries may not provide a complete fare rule description.

Fare rules may not be returned for offers with multiple passengers and/or multiple fare rule types.

Requesting Detail View (Remarks and Custom Rules)

Sending the detailViewInd query parameter set to true requests the following additional details in the retrieve:

  • Any cocument override, accounting, historical, and/or DOCI remarks added to a reservation.

  • Any custom rules added to a reservation.

If not sent the default is false.

https://api.pp.travelport.com/11/air/book/reservation/reservations/{LocatorCode}?detailViewInd=true

For {LocatorCode} send the locator code of the reservation to retrieve (returned in the workbench commit in Confirmation/Locator/value).

Ticketless Carriers

The following are returned in the reservation retrieve for ticketless carriers Frontier (F9), Spirit (NK), and Sun Country Airlines (SY):

  • Fare details including total fare, fare remarks, and OSI OTHS remarks.
  • The single ticket number for all travelers.
The reservation includes this information only after it is returned from the airline, which may be delayed for several hours after booking.

Bookings with Air, Hotel, and Car Content

The Reservation Retrieve and Create Post-Commit Workbench responses return air, hotel, and/or car segments for any reservation that includes that content, called a multi-content booking. All segments must have been booked with the JSON Air APIs, JSON Hotel APIs, JSON Car APIs (full release pending), or a terminal program. You can also add either GDS or NDC air offers to a hotel and/or car booking. See the Booking Guide for Air, Hotel, & Car for workflows.

With this release, all reservations - regardless of their content - return the ReservationDisplaySequence object. This object helps you to accurately represent a traveler itinerary by returning details of the sequence of each offer in the response. For each product, ReservationDisplaySequence returns an instance of DisplaySequence with the following details:

  • displaySequence: The segment number in the system.

  • OfferRef: The offer id assigned to that segment.

  • ProductRef: The product number. Note that each leg of an air itinerary is returned as a separate product under the same offer while car and hotel segments are each returned as a single product.

  • In addition, air segments return Sequence, which is the flight sequence number in the itinerary.

In the following example excerpt, the instances of DisplaySequence with displaySequence values 1 and 3 are the air segments, displaySequence 2 is the hotel segment, and displaySequence 4 is the car segment. See the examples in the Booking Guide for Air, Hotel, & Car for the full response. 

 ...
 "ReservationDisplaySequence": {
    "@type": "ReservationDisplaySequence",
    "DisplaySequence": [
     {
      "@type": "DisplaySequence",
      "displaySequence": 1,
      "OfferRef": "Offer_1",
      "ProductRef": "product_1",
      "Sequence": 1
     },
     {
      "@type": "DisplaySequence",
      "displaySequence": 2,
      "OfferRef": "offer_2",
      "ProductRef": "product_1"
     },
     {
      "@type": "DisplaySequence",
      "displaySequence": 3,
      "OfferRef": "Offer_1",
      "ProductRef": "product_2",
      "Sequence": 3
     },
     {
      "@type": "DisplaySequence",
      "displaySequence": 4,
      "OfferRef": "offer_3",
      "ProductRef": "product_1"
     }
    ]
   }...