Create Order

Creates an order for a chosen trip in a single atomic call: the provider reserves the seats and books the passengers, returning one ticket per passenger. There is no separate seat-lock/reserve step — if the provider needs to hold seats it does so internally for the duration of this request.

INFO

agentorder_id is our internal reservation id; echo it back on the order for reconciliation. Each passenger carries the fields advertised as required by the matching Trip Details; fields the provider did not request may be omitted. tariff_code is the chosen fare (Fare.code from /trip); seat_id is the chosen seat (SeatMap.id) when the trip has selectable seats.

Endpoint

Method: POST

URL: /v1/order

Request Headers

Parameter	Type	Required	Description
Authorization	String	Yes	Bearer <token> from Login

Request Parameters

Parameter	Type	Required	Description
└ trip_id	String	Yes	Trip id from a Search / Trip Details result
└ agentorder_id	String	Yes	Our internal reservation id
└ locale	String	No	Language, refer to Locale List
└ currency	String	No	Requested order currency
└ contact	Object	No	Booking contact (falls back to agency defaults when not required)
└ email	String	No	Contact email
└ phone	String	No	Contact phone
└ passengers	[OrderPassenger]	Yes	Passengers to book
└ index	Integer	Yes	0-based position; ties the ticket back to the request
└ firstname	String	Yes	First name
└ lastname	String	Yes	Last name
└ middlenames	String	No	Middle name(s)
└ type	String	No	Passenger type, refer to Passenger Types
└ tariff_code	String	No	Chosen fare (Fare.code from /trip)
└ seat_id	String	No	Chosen seat (SeatMap.id), when the trip has selectable seats
└ birthday	String	No	Date of birth (yyyy-MM-dd)
└ gender	String	No	One of m, f, x
└ citizenship	String	No	ISO-3166 alpha-2 country code
└ phone	String	No	Phone number
└ email	String	No	Email address
└ document	Object	No	Identity document
└ type	String	No	Document type (passport, ID, …)
└ number	String	No	Document number
└ expiry	String	No	Expiry date (yyyy-MM-dd)
└ issue_date	String	No	Issue date (yyyy-MM-dd)
└ issue_country	String	No	ISO-3166 alpha-2 country code

Request Example

{
  "trip_id": "trip_8f21",
  "agentorder_id": "TTN-100245",
  "locale": "en",
  "currency": "UAH",
  "contact": { "email": "[email protected]", "phone": "+380501112233" },
  "passengers": [
    {
      "index": 0,
      "type": "adult",
      "firstname": "Ivan",
      "lastname": "Petrenko",
      "tariff_code": "adult",
      "seat_id": "s12a",
      "birthday": "1990-05-14",
      "gender": "m",
      "citizenship": "UA",
      "phone": "+380501112233",
      "email": "[email protected]",
      "document": { "type": "passport", "number": "FC123456", "expiry": "2030-01-01", "issue_country": "UA" }
    }
  ]
}

Response Parameters

Parameter	Type	Required	Description
└ order	Object	Yes	Created order
└ id	String	Yes	Provider order id
└ agentorder_id	String	No	Echo of our reservation id from the request
└ status	String	No	Order status, refer to Order Status List (typically created)
└ currency	String	Yes	Order currency
└ cancel_until	String	No	Free-cancellation deadline (ISO-8601 with offset)
└ time_for_cancel	Integer	No	Seconds the order may be cancelled for free
└ tickets	[OrderTicket]	No	Issued tickets (one per passenger)
└ number	String	Yes	Provider ticket number
└ code	String	No	Provider booking/system code (matches RefundTicket.ticket_code)
└ uid	String	No	Provider-unique ticket identifier
└ passenger_index	Integer	Yes	Index of the OrderPassenger this ticket belongs to
└ seat	String	No	Assigned seat number
└ place_desc	String	No	Seat-class description
└ price	Number	No	Ticket price
└ currency	String	No	Currency
└ status	String	No	Per-ticket status (defaults to the order status)
└ cancel_until	String	No	Per-ticket free-cancellation deadline

Response Example

{
  "order": {
    "id": "ord_7c01",
    "agentorder_id": "TTN-100245",
    "status": "created",
    "currency": "UAH",
    "cancel_until": "2026-06-30T23:59:00+03:00",
    "time_for_cancel": 86400,
    "tickets": [
      {
        "number": "TKT-555001",
        "code": "BK-9931",
        "uid": "u-aa01",
        "passenger_index": 0,
        "seat": "12A",
        "place_desc": "Standard",
        "price": 650.0,
        "currency": "UAH",
        "status": "created"
      }
    ]
  }
}

Error Code List

code	message	Description
UNAUTHORIZED	Invalid token	The bearer token is missing, invalid, or expired (401).
NOT_FOUND	Trip not found	The trip_id is unknown or has expired.
INVALID_PASSENGER	Invalid passenger data	A required passenger field is missing or malformed.
SEAT_UNAVAILABLE	Seat no longer free	A requested seat_id was taken before the order completed.