> ## Documentation Index
> Fetch the complete documentation index at: https://developers.ttool.travel/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an order

> Create the order for an offer. Nothing is booked and nothing is paid, unless you ask for a hold.

Creating an order contacts nobody: no seats are taken and no money moves. You get an `orderId` and a price to confirm, then call [issue](https://developers.ttool.travel/api-reference/issue.md) to book, pay and ticket in one step. With `holdOnly`, the PNR is held at the airline without payment instead. See [On-hold bookings](https://developers.ttool.travel/guides/on-hold-bookings.md).

> [!WARNING]
>
> `orders` isn't idempotent. Every successful call creates a new order (and, with `holdOnly`, a new held PNR). An order you never issue costs nothing, but check the [order status](https://developers.ttool.travel/api-reference/get-order.md) before creating another for the same customer.

## Offer selection

Send **one** of these shapes. Both, or a partial set, is a validation error.

| Shape | Fields |
| - | - |
| Single offer (one-way, combined or packed round trip) | `requestId` + `flightProposalId` |
| Split round trip | `leavingRequestId` + `leavingFlightProposalId` + `returningRequestId` + `returningFlightProposalId` |

**requestId** `string (uuid)`

Single-offer shape.

**flightProposalId** `string (uuid)`

Single-offer shape: the `offerId`. If you applied a fare brand, use the `offerId` from change-options; the brand is already stored on it.

**leavingRequestId** `string (uuid)`

Split shape: the search `requestId`.

**leavingFlightProposalId** `string (uuid)`

Split shape: the outbound `offerId`.

**returningRequestId** `string (uuid)`

Split shape: `returningRequestId` from search.

**returningFlightProposalId** `string (uuid)`

Split shape: the return `offerId`.

**holdOnly** `boolean` (default: false)

Hold the PNR at the airline without paying. Only when `offer.supportsOnHold` is `true`. Issue or [cancel-hold](https://developers.ttool.travel/api-reference/cancel-hold.md) before `hold.expiresAt`.

## Contact

**contactInfo** `object` *required*

**properties**

**email** `string` *required*

Valid email, up to 200 characters.

**phoneNumber** `string` *required*

9 to 15 digits with an optional leading `+`. International format recommended.

**countryCode** `string` *required*

ISO 3166-1 **alpha-2**, such as `IQ`, `AE`, `TR`.

## Passengers

**flightPassengers** `object[]` *required*

At least one adult. Never more infants than adults.

**properties**

**type** `string` *required*

`Adult`, `Child` or `Infant`.

**gender** `string` *required*

`Male` or `Female`.

**firstName** `string` *required*

As in the travel document. Up to 100 characters.

**lastName** `string` *required*

As in the travel document. Up to 100 characters.

**firstNameLocalize** `string`

Arabic first name, up to 100 characters.

**lastNameLocalize** `string`

Arabic last name, up to 100 characters.

**birthDate** `string` *required*

`yyyy-MM-dd`, in the past.

**birthCountryCode** `string` *required*

ISO 3166-1 alpha-2, such as `IQ`.

**docType** `string` *required*

`Passport` or `NationalCode`.

**passportNumber** `string`

Required when `docType` is `Passport`. Up to 10 characters.

**passportIssueCountryCode** `string`

Required for passports. ISO 3166-1 alpha-2, such as `IQ`.

**passportExpirationDate** `string`

Required for passports. In the future.

**passportIssueDate** `string`

Optional.

**nationalCode** `string`

Required when `docType` is `NationalCode`. Up to 12 characters.

## Response

The [order object](https://developers.ttool.travel/api-reference/get-order.md), the same one order status returns. A normal order comes back with `status` `Submit`; a `holdOnly` order with `status` `OnHold`, a `pnr` and a `hold` block.

**orderId** `integer`

Keep this. It's the input to issue, order status and cancel-hold, and your reference for support.

**orderCode** `integer`

Human-readable order number.

**status** `string`

`Submit` (created, nothing booked) or `OnHold`.

**pnr** `string`

Airline record locator. Present for on-hold orders.

**price** `object`

`currency` and `total`. Confirm this with the customer before issuing.

**hold** `object`

On-hold orders only.

**properties**

**expiresAt** `string | null`

Latest moment the order can still be issued. Can be `null` for a few seconds after creation; read the order again.

**isFinal** `boolean`

`false` while the airline may still revise the deadline.

**serverTime** `string`

Platform clock, the same clock as `expiresAt`. Remaining time = `expiresAt − serverTime`.

**flights** `object[]`

The order's flight segments.

**tickets** `object[]`

Empty until the order is issued.

## Errors

| HTTP | `errorCode` | Action |
| - | - | - |
| 400 | `INVALID_REQUEST_FORMAT` | Fix the fields listed in `errorDetails` |
| 400 | `INVALID_COUNTRY_CODE` | Unknown codes are in `errorDetails.unknownCountryCodes` |
| 400 | `HOLD_NOT_SUPPORTED` | `holdOnly` sent for an offer whose `supportsOnHold` is `false` |
| 409 | `FLIGHT_NO_LONGER_AVAILABLE` | Offer expired or changed. Search again. |
| 409 | `FLIGHT_PRICE_CHANGED` | `holdOnly` only: the price changed at hold time and nothing is held. Search again. |
| 502 | `SUBMIT_ORDER_FAILED`, `HOLD_FAILED` | The platform or the airline refused; the message says why. Safe to search and try again. |
| 503 / 504 | `SERVICE_UNAVAILABLE`, `PROVIDER_TIMEOUT` | Temporary. Retry after a short delay. |

```bash Single offer theme={null}
curl -X POST "https://api.staging.ttool.travel/hub/api/v1/flights/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "3f1a1c9e-7b2d-4c7e-9a1f-2b3c4d5e6f70",
    "flightProposalId": "8d0e3b6a-2f41-4b8e-b1c9-5d6e7f8a9b0c",
    "holdOnly": false,
    "contactInfo": { "email": "customer@example.com", "phoneNumber": "+9647701234567", "countryCode": "IQ" },
    "flightPassengers": [{
      "type": "Adult",
      "gender": "Male",
      "firstName": "JOHN",
      "lastName": "DOE",
      "birthDate": "1990-01-15",
      "birthCountryCode": "IQ",
      "docType": "Passport",
      "passportNumber": "A12345678",
      "passportIssueCountryCode": "IQ",
      "passportIssueDate": "2020-01-15",
      "passportExpirationDate": "2030-01-15"
    }]
  }'
```

```bash On hold theme={null}
curl -X POST "https://api.staging.ttool.travel/hub/api/v1/flights/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "{requestId}",
    "flightProposalId": "{offerId}",
    "holdOnly": true,
    "contactInfo": { "email": "customer@example.com", "phoneNumber": "+9647701234567", "countryCode": "IQ" },
    "flightPassengers": [ { "...": "as above" } ]
  }'
```

```bash Split round trip theme={null}
curl -X POST "https://api.staging.ttool.travel/hub/api/v1/flights/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "leavingRequestId": "{requestId}",
    "leavingFlightProposalId": "{outboundOfferId}",
    "returningRequestId": "{returningRequestId}",
    "returningFlightProposalId": "{returnOfferId}",
    "contactInfo": { "email": "customer@example.com", "phoneNumber": "+9647701234567", "countryCode": "IQ" },
    "flightPassengers": [ { "...": "as above" } ]
  }'
```

```json 200 theme={null}
{
  "orderId": 184233,
  "orderCode": 1005123,
  "status": "Submit",
  "price": { "currency": "USD", "total": 436.00 },
  "flights": [ { "...": "segments" } ],
  "tickets": []
}
```

```json 200 (on hold) theme={null}
{
  "orderId": 184233,
  "orderCode": 1005123,
  "status": "OnHold",
  "pnr": "ABC123",
  "price": { "currency": "USD", "total": 350.90 },
  "hold": { "expiresAt": "2026-11-21T14:30:00", "isFinal": false, "serverTime": "2026-11-20T10:02:11" },
  "flights": [ { "...": "segments" } ],
  "tickets": []
}
```

```json 400 theme={null}
{
  "success": false,
  "error": { "errorCode": "HOLD_NOT_SUPPORTED", "errorCategory": "Validation", "httpStatusCode": 400 }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.