Exchange Ticketing Guide / API Reference
Exchange Ticketing is the last step in the GDS exchange workflow. Exchange Ticketing supports modifying a ticketed air itinerary and processing add collects, change fees, or refunds as applicable.
This combined guide and API reference provides the POST requests and examples for all requests in the workflow.
Related Content: GDS Exchange Workflow Guide, Cancel, Exchange, and Refund Options
In this guide:
- Add/Modify Offer
- Document Overrides (optional)
- Form of Payment
- Add Payment
- Commit Workbench (Ticket Now or Hold Booking)
Add/Modify Offer
Exchanges are made after using the JSON Exchange Eligibility and Exchange Search APIs to confirm eligibility and search for a new itinerary. All steps are completed using the Travelport JSON APIs.
Use the endpoint and request format below to send a reference payload Add/Modify Offer request with the identifier for the new offering from the Exchange Search response. The system compares the existing itinerary with the new itinerary, deletes any flight segments no longer needed, and adds the new flight segments. Any unmodified segments remain as they are.
POST |
book/offer/reservationworkbench/{workbenchID}/offers/buildfromcatalogofferings For {workbenchID} send the workbench identifier returned in ReservationResponse/Identifer/value in the workbench create response. Base path: Pre-production https://api.pp.travelport.com/11/air/ Production https://api.travelport.com/11/air/ |
Request Body
Object |
Description |
Required/Optional |
---|---|---|
OfferQueryBuildFromCatalogOfferings |
Top level object. |
Required |
BuildFromCatalogOfferingsRequest |
Top level object. |
Required |
CatalogOfferingsIdentifier |
Top level object for transaction identifier from the Exchange Search response. |
Required |
CatalogOfferingsIdentifier/Identifier |
Transaction identifier from the Exchange Search response. |
Required |
|
Send value from CatalogOfferings/Identifier/value |
Required |
CatalogOfferingIdentifier |
Top level object for offer identifier from the Exchange Search response for the offer you want to exchange for. |
Required |
CatalogOfferingIdentifier/Identifier |
Offer identifier from the Exchange Search response. |
Required |
|
Send value from CatalogOffering/id |
Required |
Examples
{
"OfferQueryBuildFromCatalogOfferings": {
"BuildFromCatalogOfferingsRequest": {
"@type": "BuildFromCatalogOfferingsRequestAir",
"CatalogOfferingsIdentifier": {
"Identifier": {
"value": "e03cb188-b221-42a1-80ef-5d42792d907c"
}
},
"CatalogOfferingIdentifier": {
"Identifier": {
"value": "o0.0"
}
}
}
}
}
The response returns a confirmation identifier per below.
{
"OfferListResponse": {
"OfferID": [
{
"@type": "OfferIdentifier",
"Identifier": {
"authority": "Travelport",
"value": "0995bea0-602d-4572-b1ef-bbe1c6e44807"
}
}
]
}
}
Document Overrides (optional)
As an optional step, you can send a document override request. You must send the request after adding the offer and before adding FOP or payment.
Exchange Ticketing supports the following document overrides, per Document Override Remarks in the Remarks & Service Requests Guide:
- Commission
- Tour Code
- Endorsements
- Adding or modifying a ticket designator
Additional document overrides specific to the exchange process are noted in Document Override Remarks in GDS Exchanges in the Remarks & Service Requests Guide.
Form of Payment
The Form of Payment (FOP) step is required anytime there is an add collect (additional payment is due for the new itinerary). You cannot use the FOP on the existing reservation. In addition, you can send an FOP request for any of these optional steps per below: use multiple forms of payment, forfeit residual amounts, or waive a change fee.
FOP is not necessary if the modified itinerary costs less than the original itinerary, or in the case of an even exchange.
All steps in this section use the following endpoint with the payload detailed below for each. This is the same endpoint used to add FOP in initial ticketing.
The response returns a confirmation identifier.
POST |
payment/reservationworkbench/{workbenchID}/formofpayment For {workbenchID} send the workbench identifier returned in ReservationResponse/Identifer/value in the workbench create response. Base path: Pre-production https://api.pp.travelport.com/11/air/ Production https://api.travelport.com/11/air/ |
Add Form of Payment
To add FOP:
-
Send a request to the FOP endpoint above with one of the payloads (cash, credit, agent invoice) in the Add Form Of Payment API Reference.
Add Multiple Forms of Payment (optional)
Adding multiple FOP is supported only if you are ticketing at workbench commit by sending payLaterInd=false, as this information is not cached for later ticketing.
When an add collect is due (which may include a change fee), you can choose to use different/multiple forms of payment for a single traveler (for BSP only), or use different/multiple forms of payment for each traveler on the same itinerary.
To add multiple FOP:
-
Send a request to the FOP endpoint above with the cash or credit payload in the Add Form Of Payment API Reference.
-
Repeat as needed for additional FOP.
Note the following:
Change Fee to EMD:
A change fee cannot be split across multiple FOPs.
The first payment referenced will be used for the change fee and will not be used for the add collect.
If a change fee to EMD is being collected during an exchange, then the first FOP referenced in the Payment service will be used for the change fee and any other FOPs referenced will be used for the add collect (if applicable).
Add Collect:
A maximum of 3 FOPs can be used for one ticket – for BSP only.
ARC does not allow multiple FOPs for an add collect.
When adding FOP:
Do not add FOPs that already exist in the workbench – unless it’s a credit card for which only the expiration date has changed.
Supported FOPs are cash, invoice, and credit card.
When adding payment below:
Always include a traveler reference.
When splitting payments across one ticket, ensure the amounts in Add Payment request add up to the total add collect and/or change fee.
Always send the Amount object in the Add Payment step even if the value = zero (e.g., forfeit scenario).
Forfeit Residual Amounts (optional)
Forfeiting residual amounts is supported only when issuing tickets at workbench commit, as this information is not cached for later ticketing.
Optionally, agencies can forfeit residual amounts during the exchange/reissue of a ticket. An agency can forfeit the total residual amount, the base amount, the total taxes, or individual taxes with a tax code.
To send FOP to forfeit residual amount:
-
Send an FOP request to the FOP endpoint above with the Add FOP Forfeit Request payload below.
-
When you send the add payment request in the next step per below, reference the FOP identifier for the Forfeit and send one of the following objects as appropriate to identify the amount to forfeit:
-
Total residual amount: Amount object, example: "Amount": { "code": "USD", "value": 863.40 }
-
Base amount: BaseAmount object, example: "BaseAmount": { "code": "USD", "value": 123.45 } }
-
Total taxes: Taxes object with TotalTaxes, example: "Taxes": { "@type": "TaxesDetail", "TotalTaxes": 23.0 }
-
Individual tax: Taxes object with individual Tax object, example: "Taxes": { "@type": "TaxesDetail", "Tax": [ { "currencyCode": "USD", "taxCode": "YQ", "value": 34 } ] }
-
Object |
Description |
Required/Optional |
---|---|---|
FormOfPaymentForfeit |
Top level object. Key value pair:
|
Required |
{
"FormOfPaymentForfeit": {
"@type": "FormOfPaymentForfeit",
"id": "formOfPayment_1",
}
}
The following example shows the corresponding Add Payment step when forfeiting a total residual amount.
{
"Payment": {
"id": "payment_3",
"Identifier": {
"authority": "Travelport",
"value": "A0656EFF-FAF4-456F-B061-0161008D6A5E"
},
"FormOfPaymentIdentifier": {
"id": "formOfPayment_1",
"FormOfPaymentRef": "formOfPayment_1",
"Identifier": {
"authority": "Travelport",
"value": "a26164ec-02b8-41ef-af61-a837a76d5adb"
}
},
"OfferIdentifier": [
{
"id": "offer_1",
"offerRef": "offer_1",
"Identifier": {
"authority": "Travelport",
"value": "58100d86-b984-432b-82eb-c7286c061193"
}
}
],
"Amount": {
"code": "USD",
"value": 863.4
}
}
}
Waive a Change Fee (optional)
Waiving a change fee is supported both for ticketing at workbench commit and ticketing later.
You can waive a change fee with or without a waiver code. Waiver forms of payment are automatically applied to all travelers in a reservation. A future enhancement will allow waiving a change fee for individual travelers.
The WaiverCode/Value is optional and if sent is added to the Endorsement Box in the reservation.
To send FOP to waive a change fee:
-
Send a request to the FOP endpoint above with the Add FOP Waiver request payload below.
-
When you send the add payment request in the next step, reference the FOP identifier for the waiver code.
Object |
Description |
Required/Optional |
---|---|---|
FormOfPaymentWaiverCode |
Top level object. Key value pair:
|
Required |
FormOfPaymentRef |
Send the same custom identifier sent in FormOfPaymentWaiverCode/id. |
Required |
WaiverCode |
Optional waiver code. Key value pair:
|
Optional |
{
"FormOfPaymentWaiverCode": {
"id": "formOfPayment_3",
"FormOfPaymentRef": "formOfPayment_3",
},
"WaiverCode": {
"value": "ABC123"
}
}
}
Add Payment
Add Payment is required in the exchange workflow even if you will not ticket the reservation at commit:
-
To issue the ticket at commit, send Add Payment and then commit without sending the payLaterInd query parameter, or with payLaterInd set to false.
-
To hold the booking at commit without issuing tickets yet, send Add Payment and then commit with payLaterInd set to true.
Send the Add Payment request to the endpoint below, which is the same endpoint used to add payment in initial ticketing.
POST |
paymentoffer/reservationworkbench/{workbenchID}/payments For {workbenchID} send the workbench identifier returned in ReservationResponse/Identifer/value in the workbench create response. Base path: Pre-production https://api.pp.travelport.com/11/air/ Production https://api.travelport.com/11/air/ |
The following example request charges payment to formOfPayment_2. Payment/id is a custom value of your choice to identify the payment. The FOP identifiers are in the reservation, or were sent in the FOP options in the previous step.
{
"Payment": {
"id": "payment_2",
"Identifier": {
"authority": "Travelport",
"value": "A0656EFF-FAF4-456F-B061-0161008D6A5E"
},
"Amount": {
"code": "AUD",
"value": 14.55
},
"FormOfPaymentIdentifier": {
"id": "formOfPayment_2",
"FormOfPaymentRef": "formOfPayment_2",
"Identifier": {
"authority": "Travelport",
"value": "a26164ec-02b8-41ef-af61-a837a76d5adb"
}
},
"OfferIdentifier": [
{
"id": "offer_1",
"offerRef": "offer_1",
"Identifier": {
"authority": "Travelport",
"value": "58100d86-b984-432b-82eb-c7286c061193"
}
}
],
"TravelerIdentifierRef": [
{
"passengerTypeCode": "ADT",
"id": "travelerRefId_1"
}
]
}
}
By including the Fees object, the following example request charges payment for any change or other fees to formOfPayment_2. This FOP identifier could be already in the reservation, or could be a FOP added via the Add FOP request in the previous step.
{
"Payment": {
"id": "payment_2",
"Amount": {
"code": "EUR",
"value": 22
},
"FormOfPaymentIdentifier": {
"id": "formOfPayment_2",
"FormOfPaymentRef": "formOfPayment_2",
"Identifier": {
"authority": "Travelport",
"value": "a26164ec-02b8-41ef-af61-a837a76d5adb"
}
},
"OfferIdentifier": [
{
"id": "offer_1",
"offerRef": "offer_1",
"Identifier": {
"authority": "Travelport",
"value": "58100d86-b984-432b-82eb-c7286c061193"
}
}
],
"TravelerIdentifierRef": [
{
"passengerTypeCode": "ADT",
"id": "travelerRefId_1"
}
],
"Fees": {
"@type": "Fees",
"TotalFees": 60
}
}
}
The following example sends an Add Payment request to forfeit an individual tax.
{
"Payment": {
"id": "payment_2",
"Identifier": {
"authority": "Travelport",
"value": "A0656EFF-FAF4-456F-B061-0161008D6A5E"
},
"FormOfPaymentIdentifier": {
"id": "formOfPayment_1",
"FormOfPaymentRef": "formOfPayment_1",
"Identifier": {
"authority": "Travelport",
"value": "a26164ec-02b8-41ef-af61-a837a76d5adb"
}
},
"OfferIdentifier": [
{
"id": "offerModify_1",
"offerRef": "offerModify_1",
"Identifier": {
"authority": "Travelport",
"value": "58100d86-b984-432b-82eb-c7286c061193"
}
}
],
"Taxes": {
"@type": "TaxesDetail",
"Tax": [
{
"currencyCode": "USD",
"taxCode": "YQ",
"value": 34
}
]
}
}
}
The response returns a confirmation identifier.
{
{
"PaymentResponse": {
"Payment": {
"@type": "PaymentIdentifier",
"Identifier": {
"authority": "Travelport",
"value": "d163f544-0f93-453d-9b7b-a1880d807401"
}
}
}
}
Commit Workbench (Ticket Now or Hold Booking)
Last, commit the workbench to commit the changes, setting the payLaterInd query parameter to either issue the new ticket/s now, or create a held booking for later fulfillment.
Send the request to the following resource. This is the same endpoint used to commit any workbench. The only difference is that the payLaterInd and DocumentValue parameters below are supported only for exchanges.
There is no message payload.
POST |
book/reservation/reservations/{workbenchID} For {workbenchID} send the workbench identifier returned in ReservationResponse/Identifer/value in the workbench create response. Base path: Pre-production https://api.pp.travelport.com/11/air/ Production https://api.travelport.com/11/air/ |
Query parameter | Description | Require |
---|---|---|
payLaterInd |
Required in Exchange Ticketing 23.11.13 and later.
Sets whether to issue the new ticket/s now, or create a held booking for later fulfillment. Supported values:
|
Required |
DocumentValue |
Supported value:
Refunds are indicated in the Exchange Search response by a negative amount in ModifyPrice/TotalPrice, and a value of either EMD or MCO in TermsAndConditions/FulfillmentMethod/RefundMethod. Alternately, you can refund or forfeit any EMD value using the EMD Void request.
Exchange Ticketing 23.11.15 and later. If the new itinerary is ticketed at the time of reservation (pay now flow), and there is a residual balance to an MCO (miscellaneous change order), the MCO is issued along with the ticket at workbench commit. If the new itinerary is booked but not ticketed (pay later flow), any MCO is created but not issued yet. This allows customers to display, modify, and issue their own MCO outside of the JSON APIs if desired. If the reservation is subsequently ticketed using Exchange Ticketing, the MCO is issued as usual at commit.
|
Optional If not sent any value remains on the EMD. |
The Commit response returns all details of the new reservation, including price modifications in the ModifyPrice object. Any refund issued is indicated in FulfillmentMethod/RefundMethod/value. The reissued ticket numbers are returned in an instance of Receipt of type ReceiptPayment as shown below. The response does not include any itinerary data from the previous booking.
The commit response returns the following Document @type values:
-
The previous (exchanged) ticket details are returned with Document @type DocumentTicketExchange.
-
The newly issued ticket details are returned with Document @type DocumentTicket.
-
If an EMD is issued during the exchange, such as for a change fee or a residual balance, the commit response returns Document @type DocumentEMD with the EMD number and the amount.
This example excerpt shows the reissued ticket numbers for each of the four passengers on the modified itinerary. For a full response see the Exchange Ticketing developer toolkit available from the Tools and Downloads page.
{
...
{
"@type": "ReceiptPayment",
"Document": [
{
"@type": "DocumentTicket",
"Number": "1253768045730",
"TravelerIdentifierRef": {
"name": "SRNMONEADT PX ADTONEMDNM MR",
"passengerTypeCode": "ADT",
"id": "travelerRefId_1",
"value": ""
}
},
{
"@type": "DocumentTicket",
"Number": "1253768045731",
"TravelerIdentifierRef": {
"name": "SRNMONEINF PX INFONE",
"passengerTypeCode": "INF",
"id": "travelerRefId_2",
"value": ""
}
},
{
"@type": "DocumentTicket",
"Number": "1253768045732",
"TravelerIdentifierRef": {
"name": "SRNMONESRC PX SRCONEMDNM MR",
"passengerTypeCode": "SRC",
"id": "travelerRefId_3",
"value": ""
}
},
{
"@type": "DocumentTicket",
"Number": "1253768045733",
"TravelerIdentifierRef": {
"name": "SRNMONEMIL PX MILONEMDNM MR",
"passengerTypeCode": "MIL",
"id": "travelerRefId_4",
"value": ""
}
}
]
}
],
...