Add seats (JSON)
Seats can be bought at two moments, with the same mechanics — get a seat map with priced offer items, then reference the chosen item:
- On an existing order — seat map for the order, then a change-order accept (below).
- During the initial booking — seat map for the priced offer, then include the seat item in create order (further down).
The order flow continues from Make a test booking — you need a confirmed order and a valid token. Every request and response was captured live against the test environment.
Step 1 — Get the seat map
POST /json/v2/orders/MX7NDN465E71/seats
The body is an empty object:
{}
The response returns one seat map per flight leg. Each assignable unit carries per-passenger pricing with an offerItemId (prefixed OFI-ST-) — that ID is what you accept in step 2. It encodes the segment, passenger, and seat; the price is recomputed from live booking state when accepted.
{
"data": {
"legSeatMaps": [
{
"departureStation": "PVU",
"arrivalStation": "SNA",
"equipmentType": "223",
"segmentRefId": "SEG-UFZVU05BfDIwMjYwOTE1fE1YMTY0NA",
"decks": [
{
"number": 1,
"compartments": [
{
"designator": "Y",
"units": [
{
"designator": "1A",
"assignable": true,
"availability": "Open",
"travelClassCode": "Y",
"properties": ["EC", "I", "L", "LS", "US", "W"],
"pitchInches": 39,
"tier": "First",
"passengerPricing": [
{
"paxRefId": "ADT-1",
"passengerType": "ADT",
"amount": 79,
"currency": "USD",
"offerItemId": "OFI-ST-U3xQVlVTTkF8MjAyNjA5MTV8TVgxNjQ0fEFEVC0xfDFB"
}
]
},
{
"designator": "24D",
"assignable": true,
"availability": "Open",
"travelClassCode": "Y",
"properties": ["A", "RS"],
"pitchInches": 31,
"tier": "Standard",
"passengerPricing": [
{
"paxRefId": "ADT-1",
"passengerType": "ADT",
"amount": 14,
"currency": "USD",
"offerItemId": "OFI-ST-U3xQVlVTTkF8MjAyNjA5MTV8TVgxNjQ0fEFEVC0xfDI0RA"
}
]
}
// … remaining units elided …
]
}
]
}
]
}
]
},
"error": null
}
We'll take seat 24D at $14.
Step 2 — Accept the seat offer
PATCH /json/v2/orders/MX7NDN465E71
An AcceptOffer change referencing the seat's offerItemId, plus the seat row/column and payment for the new balance. The offerId field is required by the schema but not resolved for a-la-carte items — pass the constant OF-ANC.
{
"changes": [
{
"type": "AcceptOffer",
"offerItems": [
{
"offerId": "OF-ANC",
"offerItemId": "OFI-ST-U3xQVlVTTkF8MjAyNjA5MTV8TVgxNjQ0fEFEVC0xfDI0RA",
"passengerIds": ["ADT-1"],
"seat": { "row": 24, "column": "D" }
}
]
}
],
"payment": {
"type": "CreditCard",
"cardType": "VI",
"cardNumber": "4111111111111111",
"expiryDate": "1227",
"securityCode": "123",
"payer": {
"name": { "givenName": "Jane", "surname": "Doe" },
"postalAddress": {
"line1": "123 Main St",
"city": "Los Angeles",
"stateProvince": "California",
"postalCode": "90210",
"countryCode": "US"
}
}
}
}
The response is the full updated order view. The seat shows up under services as a confirmed item, the order total grows to $73, and a second $14 payment appears:
{
"data": {
"order": {
"orderId": "MX7NDN465E71",
"recordLocator": "E2BL5F",
"statusCode": "CONFIRMED",
"balanceDue": { "amount": 0, "currency": "USD" },
"totalPrice": {
"total": { "amount": 73, "currency": "USD" }
// … base and taxes elided …
}
// … flight order item elided …
},
"services": [
{
"itemId": "OOI-ST-U3xQVlVTTkF8MjAyNjA5MTV8TVgxNjQ0fFBBWC1RVVJVTFRFfFNFQVR8MjRE",
"serviceId": "SVC-ST-U3xQVlVTTkF8MjAyNjA5MTV8TVgxNjQ0fFBBWC1RVVJVTFRFfFNFQVR8MjRE",
"code": "SEAT",
"name": "24D",
"category": "seat",
"ownerCode": "MX",
"statusCode": "CONFIRMED",
"totalPrice": {
"total": { "amount": 14, "currency": "USD" },
"base": { "amount": 0, "currency": "USD" },
"taxes": [],
"fees": [
{ "type": "ServiceFee", "code": "SEAT", "amount": { "amount": 14, "currency": "USD" } }
]
},
"paxRefId": "ADT-1",
"segmentRefIds": ["SEG-UFZVU05BfDIwMjYwOTE1fE1YMTY0NA"],
"attributes": { "unitDesignator": "24D", "row": 24, "column": "D" }
}
],
"payments": [
{ "paymentId": "PAY-MQ", "amount": { "amount": 59, "currency": "USD" }, "statusCode": "SUCCESSFUL" },
{ "paymentId": "PAY-Mg", "amount": { "amount": 14, "currency": "USD" }, "statusCode": "SUCCESSFUL" }
]
// … pax, contacts, journeys, tickets elided …
},
"error": null
}
Adding a seat during the initial booking
The same seat map exists for a priced offer, before any order — so a booking can be created with its seat in one shot.
1. Get the seat map for the priced offer (after price offer, before create):
POST /json/v2/offers/OF-3f2f49c5-e560-4f0e-b37c-b80cb8c8cd27/seats
{
"offerItemIds": ["OFI-3f2f49c5-e560-4f0e-b37c-b80cb8c8cd27-0"],
"passengers": [
{ "paxId": "ADT-1", "type": "ADT" }
]
}
Seat and service offer item IDs are scoped to a passenger, so the passengers here need paxId values. If the offer was priced with anonymous passengers ({"type": "ADT"} only) and you omit passengers in this call, the seat map comes back without offerItemIds and there is nothing to book. Use ADT-1, ADT-2, … and keep the same IDs in create order.
The response is the same legSeatMaps shape as the order-scoped call above — pick the seat and capture its offerItemId (OFI-ST-…).
2. Include the seat item in create order. Add it to offerItemIds and offerItemSelections next to the fare item, and pay the combined total ($59 fare + $14 seat):
{
"offerId": "OF-3f2f49c5-e560-4f0e-b37c-b80cb8c8cd27",
"offerItemIds": [
"OFI-3f2f49c5-e560-4f0e-b37c-b80cb8c8cd27-0",
"OFI-ST-U3xQVlVTTkF8MjAyNjA5MTV8TVgxNjQ0fEFEVC0xfDI0RA"
],
"offerItemSelections": [
{ "offerItemId": "OFI-3f2f49c5-e560-4f0e-b37c-b80cb8c8cd27-0", "passengerIds": ["ADT-1"] },
{ "offerItemId": "OFI-ST-U3xQVlVTTkF8MjAyNjA5MTV8TVgxNjQ0fEFEVC0xfDI0RA", "passengerIds": ["ADT-1"] }
],
"passengers": [
{
"passengerId": "ADT-1",
"type": "ADT",
"name": { "givenName": "Sara", "surname": "Doe" },
"dateOfBirth": "1980-01-01",
"gender": "Female"
}
]
// … contacts and payment exactly as in Make a test booking …
}
Seat items take exactly one passengerId, and it must match the paxRefId the seat was priced for. No seat row/column block is needed — the OFI-ST- ID already encodes the seat. The response is the usual order view: the order is created CONFIRMED with the seat already under services and the total covering both.
Notes
- Moving to a different seat is the same call with the new seat's
offerItemId. The swap is atomic. If allowed by rules, a portion of the previous seat fee may be credited toward the new seat. - Changes that create a positive balance require
payment. A held (unpaid) order can accept updates which increases the balance due. - If the seat was reserved by a different session between the seat map call and its selection, the change is rejected. Retrieve the seat map for current availability and try again.
Full schema reference: order ancillaries and change order.