Create order
POST /json/{version}/orders creates a booking from a priced offer returned by price offer. It is the JSON counterpart of the NDC IATA_OrderCreateRQ. Returns 201 Created on success.
Authorization
Create order requires full transaction (book) permissions on the API key; read-only keys are rejected.
See payments for methods, card brands, and the sandbox test card. Passenger field rules are on passengers.
Request
| Field | Description |
|---|---|
offerId | Priced offer ID from price offer. |
offerItemIds | Offer items to book. Must exist on the priced offer. |
offerItemSelections | One entry per offer item, optionally restricting it to specific passengerIds. |
passengers | Full passenger records — see passengers. Summary: passengerId, type (ADT / CHD / INF), name (givenName + surname required), optional dateOfBirth, gender (Male / Female), nationality, residenceCountry, loyaltyProgram, travelDocuments, per-passenger contact (email/phone, contacts), and infantPassengerId. |
contact | The required primary booking contact: emailAddress is mandatory, phoneNumber and postalAddress optional, and name defaults to the lead passenger. Phones must normalize to E.164. See contacts. |
remarks | Optional free-text booking remarks. |
payment | Required. { "type": "Hold" } for an unpaid hold, or a card payment — see payments. |
Hold (default example)
POST /json/v0/orders
Authorization: <bearer token from /auth/token>
Content-Type: application/json
{
"offerId": "OF-8c1e2f04-9d21-4b7a-b3c2-77c101f1a001",
"offerItemIds": [
"OFI-8c1e2f04-9d21-4b7a-b3c2-77c101f1a001-0"
],
"offerItemSelections": [
{
"offerItemId": "OFI-8c1e2f04-9d21-4b7a-b3c2-77c101f1a001-0"
}
],
"passengers": [
{
"passengerId": "PX1",
"type": "ADT",
"name": {
"givenName": "Jane",
"surname": "Doe"
}
}
],
"contact": {
"phoneNumber": "8015551212"
},
"payment": {
"type": "Hold"
}
}
Pay with the sandbox Visa test card
{
"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"
}
}
}
}
Response
The response is the same OrderView projection returned by order retrieve: order (header and flight items), services, pax, contacts, journeys, payments, and tickets. A Hold booking may include seat and service offer items; it returns statusCode: "ONHOLD" with paymentTimeLimit and balanceDue covering everything held, and is confirmed later with change order.
{
"data": {
"order": {
"orderId": "ABC123",
"recordLocator": "ABC123",
"ownerCode": "MX",
"statusCode": "ONHOLD",
"creationDateTime": "2026-07-01T15:04:05Z",
"paymentTimeLimit": "2026-07-02T15:04:05Z",
"balanceDue": {
"amount": 99,
"currency": "USD"
},
"totalPrice": {
"total": {
"amount": 99,
"currency": "USD"
},
"base": {
"amount": 91.5,
"currency": "USD"
},
"taxes": [
{
"code": "US",
"amount": {
"amount": 7.5,
"currency": "USD"
}
}
],
"fees": []
},
"items": [
{
"itemId": "OOI-FL-eyJ2IjoxfQ",
"statusCode": "CONFIRMED",
"totalPrice": {
"total": {
"amount": 99,
"currency": "USD"
},
"base": {
"amount": 91.5,
"currency": "USD"
},
"taxes": [
{
"code": "US",
"amount": {
"amount": 7.5,
"currency": "USD"
}
}
],
"fees": []
},
"paxRefIds": [
"PAX-eyJ2IjoxfQ"
],
"segmentRefIds": [
"SEG-eyJ2IjoxfQ"
],
"fare": {
"fareBasisCode": "Y",
"cabinTypeCode": "Y",
"rbd": "Y",
"priceClassRefId": "EZU",
"bundleName": "Nice"
}
}
]
},
"services": [
{
"itemId": "SVR-eyJ2IjoxfQ",
"serviceId": "SVR-eyJ2IjoxfQ",
"code": "BAG1",
"name": "First checked bag",
"category": "baggage",
"ownerCode": "MX",
"totalPrice": {
"total": {
"amount": 35,
"currency": "USD"
},
"base": {
"amount": 35,
"currency": "USD"
},
"taxes": [],
"fees": []
},
"paxRefId": "PAX-eyJ2IjoxfQ",
"segmentRefId": "SEG-eyJ2IjoxfQ",
"attributes": {
"pieceCount": 1
}
}
],
"pax": [
{
"paxId": "PAX-eyJ2IjoxfQ",
"ptc": "ADT",
"name": {
"givenName": "Jane",
"surname": "Doe"
}
}
],
"contacts": [
{
"contactId": "CTC-UA",
"contactTypeCode": "P",
"contactTypeName": "Primary",
"phoneNumbers": [
{
"number": "+18015551212",
"type": "Other"
}
],
"name": {
"givenName": "Jane",
"surname": "Doe"
}
}
],
"journeys": [
{
"journeyId": "JOU-eyJ2IjoxfQ",
"origin": "SLC",
"destination": "CHS",
"departureDateTime": "2026-09-15T08:00:00",
"arrivalDateTime": "2026-09-15T12:00:00",
"duration": "PT4H",
"stops": 0,
"segments": [
{
"segmentId": "SEG-eyJ2IjoxfQ",
"marketingCarrier": "MX",
"marketingFlightNumber": "101",
"origin": "SLC",
"destination": "CHS",
"departureDateTime": "2026-09-15T08:00:00",
"arrivalDateTime": "2026-09-15T12:00:00",
"cabinTypeCode": "Y",
"rbd": "Y"
}
]
}
],
"payments": [],
"tickets": []
},
"error": null
}
Create order errors
See the shared error codes catalog for common create/pay failures. Codes this endpoint may return:
| Code | HTTP status | Cause |
|---|---|---|
ERR-1002 | 404 | Unsupported version segment in the path. |
ERR-1004 | 400 | Invalid field value: a phone that cannot normalize to E.164, or a malformed email. |
ERR-1005 | 422 | Request validation failed: duplicate passenger IDs, infants exceeding adults, missing contact. |
ERR-3000 | 404 | Referenced offer could not be found. |
ERR-3001 | 404 | Referenced offer has expired. |
ERR-4001 | 400 | Order could not be created from the selected offer. |
ERR-6000 | 422 | Payment method not supported. |
ERR-6001 | 422 | Card brand not supported. |
ERR-6002 | 400 | Payment rejected. |
ERR-6005 | 503 | Payment processing timed out. |
ERR-8000 | 401 | Missing or invalid API key or bearer token. |
ERR-8001 | 403 | API key lacks full transaction permissions. |
ERR-8002 | 503 | Authentication store unavailable. |
ERR-9003 | 500 | Booking failed upstream. |