--- title: "Travelport Air API Integration Guide" description: "Design a production Travelport JSON Air v11 integration across OAuth, GDS/NDC offer lineage, AirPrice, workbenches, commit recovery, ticketing, reconciliation and monitoring." slug: "travelport-air-api" translationKey: "integration-travelport-air-api" locale: "en" type: "guide" category: "integration" tags: ["travelport","flight-api","gds","ndc","oauth","booking"] vertical: ["flight"] platform: "Travelport APIs" domain: "support.travelport.com" publishedAt: "2026-09-20" updatedAt: "2026-09-26" reviewedAt: "2026-09-26" technicalVerifiedAt: "2026-09-26" sourceVersion: "Travelport JSON Air v11 public docs reviewed 2026-09-26" testedAgainst: "Official public documentation; not a provisioned production PCC" codeExampleStatus: "illustrative" changelog: - "2026-09-26 — Provider companion standard applied; access, lifecycle, quota/polling and evidence boundaries clarified." sources: - title: "Travelport Flights APIs Guide" url: "https://support.travelport.com/webhelp/JSONAPIs/Airv11/Content/Air11/General/AirAPIsGuide.htm" - title: "TripServices APIs Getting Started Guide" url: "https://support.travelport.com/webhelp/JSONAPIs/Airv11/Content/GeneralProject/GettingStartedGuide.htm" - title: "Flights Booking Guide" url: "https://support.travelport.com/webhelp/JSONAPIs/Airv11/Content/Air11/Book/BookingGuide.htm" - title: "AirPrice Full Payload API Reference" url: "https://support.travelport.com/webhelp/JSONAPIs/Airv11/Content/Air11/Price/APIRef_AirPriceFullPayload.htm" - title: "Workbench Commit API Reference" url: "https://support.travelport.com/webhelp/JSONAPIs/Airv11/Content/Air11/Workbench/APIRef_WorkbenchCommit.htm" - title: "Reservation Retrieve API Reference" url: "https://support.travelport.com/webhelp/JSONAPIs/Airv11/Content/Air11/Book/APIRef_ReservationRetrieve.htm" - title: "Travelport NDC Guide" url: "https://support.travelport.com/webhelp/jsonapis/airv11/content/air11/NDC/NDCGuide.htm" --- A Travelport JSON Air v11 integration is not simply “search, display a fare, send a booking.” Search results, AirPrice validation, mutable workbench state, committed reservations and ticket or servicing lifecycle all have different identity and durability boundaries. Travelport exposes GDS and NDC content through the same API family, but similar itinerary presentation does not imply equal capabilities. A production model normalizes fields required for comparison while retaining source, carrier, offer lineage and servicing capabilities. ## Production scenario Consider a production scenario where a traveler selects an NDC offer, waits on the payment form until its reference or workbench expires, and the later commit response is lost to a network timeout. Treating this as a simple failure can produce either a duplicate reservation or an unresolved charge without a visible confirmation. ## What does the integration own? Depending on provisioned access and content, the Flights APIs can provide: - flight search and availability, - selected-offer pricing, - fare rules, seats and ancillaries, - workbench-based booking, - payment and ticketing, - reservation retrieval, - cancel, void, refund and exchange flows that vary by GDS/NDC source. Not every function is available for every carrier or source. Build a capability matrix from the provisioned PCC and credentials, carrier, and GDS/NDC source. Your system remains responsible for: - canonical airport, carrier and traveler identity, - the normalized itinerary and offer model, - search deadlines and supplier fan-out, - internal booking attempts and idempotency, - traveler reconfirmation policy, - payment and security boundaries, - reservation and ticket reconciliation, - source-aware servicing UX. ## How should access and OAuth work? Travelport provisions TripServices credentials. The APIs use OAuth 2.0 tokens; the current getting-started guide says a new authorization token is required every 24 hours. Token management belongs in shared backend infrastructure: ```text Provisioned credentials | v OAuth token manager ---> encrypted shared cache | v Travelport adapter pool ``` - never expose credentials to browser or mobile code, - reuse tokens with an expiry margin, - make concurrent refresh single-flight, - separate pre-production and production credentials and base URLs, - measure authentication separately from shopping or booking failure. Record PCC, agency, market and content-entitlement context with a configuration version. The same normalized request may return different content under another credential scope. ## What should the end-to-end flow look like? ```text Traveler Search | v Normalized Air Request | v Travelport Search (GDS / NDC) | v Normalized Offer + Source References | v AirPrice / selected-offer validation | +---+----------------+ | | valid changed/unavailable | | v v Create Workbench user reconfirm / re-search | +--> add offer +--> add traveler/contact +--> add seat/ancillary/payment where applicable | v Commit Workbench | v Reservation Locator(s) | +--> retrieve +--> ticket/fulfill +--> cancel/modify/exchange where supported +--> reconciliation ``` AirPrice can be optional but recommended for many carriers; official documentation requires it for low-cost and some NDC carriers. A product may choose a stronger rule: always price the selected offer before commit so change handling remains consistent. ## What must the normalized request preserve? ```ts interface AirSearchRequest { origin: string; destination: string; departureDate: string; returnDate?: string; travelers: Array<{ type: "ADT" | "CHD" | "INF"; count: number; }>; cabin?: string; directOnly?: boolean; currency: string; market: string; agencyContextRef: string; } ``` Airport or city semantics, passenger types and ages, point of sale, currency and agency context belong in both the cache key and source request. A fare cannot be reconstructed from origin, destination and date alone. ## How should offers be normalized? ```ts interface AirOffer { provider: "travelport"; contentSource: "GDS" | "NDC"; source?: string; sourceOfferRef: string; itinerary: Array<{ origin: string; destination: string; departureAt: string; arrivalAt: string; marketingCarrier: string; operatingCarrier?: string; flightNumber: string; bookingClass?: string; }>; passengerPrices: unknown[]; fareBrand?: string; baggage?: unknown; ancillariesSupported: boolean; baseAmount: number; taxAmount: number; totalAmount: number; currency: string; observedAt: string; sourcePayloadRef: string; } ``` Two offers with the same flight number and times may come from different sources, validating carriers, fare products or servicing capabilities. An offer fingerprint can support deduplication; it cannot replace the provider's source reference. ## What is the reference-payload boundary? Follow-on Travelport calls can use references from a prior Search or AirPrice response, or a full payload carrying required itinerary details. References are smaller but depend on provider cache lifetime. The current v11 Booking Guide documents search retention of 12 minutes for GDS content and 34 minutes for NDC content. Reference requests to price or add an offer to a workbench must complete within that window. Do not treat those windows as a price-validity guarantee; availability or amount can change earlier. When a reference expires: 1. do not put the same reference into a retry loop, 2. re-search or evaluate a supported full-payload path, 3. compare the new offer with the original selection, 4. require reconfirmation if amount or rules changed. ## What boundary does AirPrice create? AirPrice confirms pricing for the selected search result. Retain at least: - displayed and priced amounts, - base, tax and fee breakdown, - pricing timestamp, - source and offer reference, - fare brand and booking class, - baggage and fare-rule snapshot, - price-updated status. ```text SELECTED | AIR_PRICE | +--> MATCHED -----> READY_FOR_WORKBENCH +--> CHANGED -----> USER_RECONFIRM_REQUIRED +--> FAILED ------> RE_SEARCH_REQUIRED ``` A baggage or fare-rule change can be material even if the total price is unchanged. Reconfirmation policy should not inspect only numeric delta. ## Why is a workbench ephemeral transaction state? A workbench is a mutable container for offer, traveler, contact, payment, seat and ancillary data before commit. Current v11 documentation says a workbench is valid for 30 minutes and expires if it is not committed. A workbench identifier: - is not a durable reservation ID, - must not live in an anonymous search cache, - must never be shared across user sessions, - needs expiry-aware state, - should not be reused automatically after a failed attempt. ```text booking_attempt - internal_attempt_id - source_offer_ref - priced_amount - workbench_id - workbench_expires_at - status - reservation_locator - carrier_locator - created_at ``` Commit turns workbench state into a reservation and ends that workbench lifecycle. The GDS two-step commit option can return price or schedule-change warnings without creating the booking in selected scenarios; the same capability does not apply to NDC. ## Which data is durable and which is ephemeral? ### Persist durably - canonical airport and carrier mappings, - normalized search context, - offer observations and price breakdowns, - a secure reference to the original payload, - internal booking attempt, - reservation and carrier locators, - ticket and document identifiers, - lifecycle and status events, - servicing-capability snapshot, - reconciliation outcomes. ### Treat as ephemeral - OAuth tokens, - search and catalog references, - workbench ID and content, - seat and ancillary quote references, - temporary payment and session context. NDC bookings can return a Travelport locator and a carrier locator. Store both as typed identities; never merge unqualified locator strings. ## How should GDS and NDC capabilities be modeled? Prefer a booking-time capability snapshot over scattered `isNdc` branches: ```ts interface AirServicingCapabilities { source: "GDS" | "NDC"; seatMap: boolean; paidAncillaries: boolean; hold: boolean; instantPay: boolean; void: boolean; cancel: boolean; refund: boolean; exchange: boolean; } ``` GDS and NDC may differ in fare rules, seats and ancillaries, locators, held bookings, ticketing, modification, exchanges and refunds. Revalidate current carrier and source support during go-live and periodic review. ## How should commit idempotency and unknown state work? Consider this failure: 1. the service sends commit, 2. Travelport or the carrier creates the reservation, 3. the response is lost, 4. the client assumes failure. Blindly sending commit again can create a second reservation or ambiguous workbench behavior. Mark the internal attempt `SUBMITTING` and persist correlation data before commit. A timeout becomes `BOOKING_STATE_UNKNOWN`. Recovery order: 1. if a locator was returned, use Reservation Retrieve, 2. investigate the original outcome through provider correlation and support data, 3. reconcile workbench and attempt state, 4. block a new booking until duplicate risk is resolved, 5. route to manual review if automatic recovery is impossible. Separate transport success from business success. A commit response can carry warnings, updated price, a pending carrier locator or incomplete ticketing state. ## What becomes the post-commit source of truth? After commit, the durable operational identity is the reservation locator. Use Reservation Retrieve to verify itinerary, offers, travelers, documents and schedule-change state, and to detect drift between the local lifecycle and provider state. Booking confirmation is not ticket issuance. Read the held booking's ticketing deadline from expiry or payment-time-limit data in the response rather than assuming a default such as 24 hours. Ticket numbers and document state have their own lifecycle. ```text RESERVATION_CONFIRMED | +--> TICKETING_PENDING +--> TICKETED +--> TICKETING_FAILED +--> EXPIRED / CANCELLED ``` ## What should the error and retry policy look like? ```text AUTH_FAILED ENTITLEMENT_OR_SCOPE_DENIED INVALID_SEARCH_CONTEXT NO_AVAILABILITY REFERENCE_EXPIRED PRICE_CHANGED OFFER_UNAVAILABLE WORKBENCH_EXPIRED WORKBENCH_REJECTED PAYMENT_REJECTED COMMIT_WARNING COMMIT_REJECTED BOOKING_STATE_UNKNOWN CARRIER_LOCATOR_PENDING TICKETING_FAILED RETRIEVE_FAILED SERVICING_UNSUPPORTED RATE_LIMITED PROVIDER_TIMEOUT PROVIDER_5XX ``` Search and read operations can retry transient network failures and selected 5xx responses with bounded backoff. Expired references, validation failures, unsupported servicing, payment rejection and price changes should not be retried blindly. Respect server guidance, jitter and shared concurrency budgets for rate limits. Separate stage-level timeout budgets: ```text Search -> part of the interactive deadline AirPrice -> strict selection-time budget Workbench steps -> bounded transaction budget Commit -> longer, with unknown-state recovery Retrieve/ticketing -> asynchronous retry and reconciliation ``` ## Which failure modes matter? ### Expired reference The search cache window has passed; repeated price or add-offer calls remain invalid. Search again. ### Workbench expiry The traveler waits on a payment form until the 30-minute state expires. Track backend expiry and implement a safe restart path. ### Price or fare-rule drift The total remains stable while baggage or refund terms change. Use a material-change evaluator. ### GDS/NDC capability leakage A refund or exchange supported for one source is offered for another. Persist reservation-time capabilities. ### Missing carrier locator Commit succeeds but the carrier locator is delayed. Queue retrieval and reconciliation instead of marking booking failed. ### Lost commit response The reservation exists but the client times out. Recover unknown state instead of retrying blindly. ### Ticketing deadline breach The reservation exists but expires before ticketing. Monitor order-to-ticket SLO and deadline alarms. ## What should be monitored? ### Authentication and access - token-generation success/failure, - token age and refresh margin, - entitlement rejection by PCC/source, - traffic blocked by authentication. ### Search and pricing - search success/no-availability rate, - GDS/NDC offer share, - p50/p95 latency, - expired-reference rate, - offer-to-AirPrice conversion, - price and rule change rate, - route/carrier coverage by source. ### Booking - workbench create, add-offer and commit success, - workbench expiry rate, - traveler reconfirmation rate, - booking unknown-state rate, - missing-carrier-locator age, - duplicate-prevented count. ### Fulfillment and servicing - reservation-retrieve success, - held-to-ticketed conversion, - pending-ticket age, - ticketing deadline breaches, - cancel, void, refund and exchange success by source, - reconciliation-gap count and age. Provider health must show semantic success and lifecycle completion by GDS/NDC source, not only HTTP uptime. ## Where is the security boundary? - store credentials and OAuth tokens in backend secret infrastructure, - mask PII and payment data in logs, - encrypt raw source payloads and limit retention, - bind workbench ownership to the internal user/session, - authorize and audit payment operations, - redact traveler and document data from support exports. ## Go-live checklist - Are provisioning, PCC, credentials and content entitlement verified? - Are pre-production and production completely separate? - Are OAuth reuse and refresh single-flight? - Are canonical airport/carrier IDs independent of provider identity? - Are full search context and original offer lineage retained? - Are GDS/NDC source and capability snapshots stored? - Is reference-cache expiry handled? - Is the selected offer priced before commit? - Do price or rule changes require reconfirmation? - Is the workbench ephemeral and expiry-aware? - Is the internal booking attempt durable before commit? - Does commit timeout trigger unknown-state recovery? - Are reservation and carrier locators typed identities? - Are booking and ticketing separate lifecycle states? - Is the ticketing deadline read from the response? - Is retry behavior specific to operation and error class? - Have retrieve, ticket and servicing reconciliation been tested? - Is the GDS/NDC capability matrix verified against current carrier support? - Are PII/payment masking and access controls complete? ## Meta Search takeaway The valuable asset in a Travelport integration is not only the normalized fare; it is the fare's source, offer lineage and transaction or servicing capabilities. Treating search references as ephemeral, validating selection through AirPrice, isolating workbench state and reconciling locator and ticket lifecycle keeps Travelport-specific behavior inside the adapter without sacrificing product reliability. ## Provider companion snapshot | Area | Status | |---|---| | Access | Provisioned Travelport credentials/PCC and relevant content entitlement | | Auth | OAuth 2.0; documentation describes a 24-hour token renewal cycle | | Primary contracts | Search, AirPrice, workbench, commit, reservation retrieve, ticket/servicing | | Content | GDS and NDC through the same API family; capability varies by source/carrier | | Pagination | Endpoint-specific; shopping/booking lifecycle is not generic pagination | | Polling | Core Air booking is not a poll-session model | | Rate limit | No single universal public quota verified; provisioned agreement/endpoint contract is source of truth | | Search cache | GDS references around 12 min, NDC around 34 min | | Workbench | Mutable workbench lifetime is about 30 min | | Evidence | Official docs reviewed; no claim of a live provisioned PCC test | | Code | Illustrative | ### Capability boundary Search → offer/reference → AirPrice → workbench → commit → reservation → ticket/service/cancel/exchange. GDS and NDC can normalize into a common UI model but must not be assumed to have identical fulfillment and servicing capabilities. ### Freshness, idempotency and ordering Search-reference expiry, AirPrice state and workbench lifetime are separate freshness clocks. A commit timeout creates UNKNOWN, not proven failure; retrieve/reconcile before another create/commit attempt. ### Polling / pagination / rate-limit boundary The core booking lifecycle is not a paginated or poll-session workflow. Paginate only collection endpoints that explicitly support it. Provisioned agreement/endpoint limits remain the operational source of truth. ## Observability Track authentication/entitlement failures, shopping and AirPrice latency, source-reference age, workbench expiry, commit unknown-state age, reservation-retrieve recovery, ticketing/servicing failures and reconciliation drift separately for GDS and NDC content.