Create a booking
POST/api/v1/bookings
Books one or more quotes as a single atomic order.
The call is synchronous: a 201 means every item is confirmed at the supplier and the
redemption artifact (coupon, boarding code, entitlement) exists. On any item failure the
engine compensates the items already booked and the whole order comes to rest FAILED —
a partially-confirmed order is impossible.
You never send a price. Net and sell both come from the frozen quote.
Which details to send
The variant is decided by the offering behind your quoteId, not by anything in this
request. Send the bag matching the vertical you searched:
| You searched | Send |
|---|---|
POST /api/v1/airport-transfer/search | AirportTransferDetails |
POST /api/v1/express-bus/search | ExpressBusDetails |
GET /api/v1/entertainment/catalog | EntertainmentDetails |
Details are validated before any money moves and before any supplier is called, so a
missing field costs nothing — you get a 400 naming every field you left out.
Reading the outcome
| Status | Meaning | What to do |
|---|---|---|
201 | CONFIRMED — booked | Deliver the artifact in items[].detail |
422 | FAILED — supplier declined | Nothing was charged. Re-quote and try again |
409 | Quote expired, or order RECONCILING | See below — the two cases differ |
A 409 is either an expired quote (get a new quote) or an order the engine has not yet
resolved with the supplier (RECONCILING — re-send this exact request with the same
idempotency key until you get 201 or 422). Never respond to a RECONCILING order by
booking again with a fresh key: that risks a second real booking that cannot be cancelled.
Request
Responses
- 201
- 400
- 401
- 403
- 404
- 409
- 422
Booked. Every item is CONFIRMED at the supplier. The Location header points at the
order.
Response Headers
URL of the created order
The request or its details bag is invalid. The message names every field at fault.
Validation runs before any money moves or any supplier call, so this costs nothing.
Missing or unusable API key.
Your agent is suspended, or is not entitled to the vertical/supplier behind this quote.
Entitlement is filtered silently in search — an offering you may not sell simply does not
appear — so not-entitled surfaces only at booking.
Unknown quoteId — the quote does not exist, or it was minted for a different channel.
Either the quote expired, or the order is not yet resolved (RECONCILING), or you
cannot fund it.
The three cases want different responses. An expired quote needs a new quote. A
RECONCILING order needs the same idempotency key re-sent. Insufficient funds needs
a top-up (the body carries the numbers).
The supplier declined. The order is FAILED, nothing was charged, and any partial work
was compensated. Re-quote before trying again.