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 headers

Header	Required	Description
`Idempotency-Key`	No	Up to 255 characters, unique per order attempt. A repeat request with the same key returns the original order instead of booking again (keys are retained for 24 hours, scoped per seller). A repeat while the first attempt is still processing returns `ERR-4011`; reusing the same key for a different request body returns `ERR-1011`. Send one on every create so a timed-out request can be retried safely.

Request body

Field	Description
`offerId`	Priced offer ID from price offer, or a shopped offer ID from create offers. A shopped offer ID triggers short sell: the offer is priced inside the create call and the resulting priced offer is booked. If the repriced total differs from the shopped total and `expectedTotal` is not sent, the request is rejected with `ERR-3006` before any booking is made.
`offerItemIds`	Offer items to book. Must exist on the offer.
`offerItemSelections`	One entry per offer item, optionally restricting it to specific `passengerIds`. Up to 100 entries.
`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. Up to 5 remarks, max 1 024 characters each.
`expectedTotal`	Optional stated order total (`amount` in USD). On short sell (a shopped `offerId`), the stated amount is checked against the repriced total, allowing the call to proceed when the price has drifted. On a priced offer, this is the only price agreement a Hold can carry.
`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": {
    "emailAddress": "[email protected]",
    "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,
          "weight": {
            "value": 50,
            "unit": "LBR"
          }
        }
      }
    ],
    "pax": [
      {
        "paxId": "PAX-eyJ2IjoxfQ",
        "ptc": "ADT",
        "name": {
          "givenName": "Jane",
          "surname": "Doe"
        }
      }
    ],
    "contacts": [
      {
        "contactId": "CTC-UA",
        "contactTypeCode": "P",
        "contactTypeName": "Primary",
        "emailAddress": "[email protected]",
        "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-1011`	`422`	Idempotency-Key reused: same key sent with a different request body.
`ERR-3000`	`404`	Referenced offer could not be found.
`ERR-3001`	`404`	Referenced offer has expired.
`ERR-3006`	`409`	Short sell only: repriced total differs from the shopped total and no `expectedTotal` was sent.
`ERR-3007`	`422`	The requested flight is not available in the tour-operator inventory.
`ERR-3008`	`409`	Contracted pricing for this journey has not been verified yet.
`ERR-4001`	`400`	Order could not be created from the selected offer.
`ERR-4011`	`409`	Order create with this Idempotency-Key is still in progress; retry with the same key.
`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.