Booking on credit#

POST /v1/bookings converts a priced order into a real booking, charged against your account's credit line.

No payment gateway is involved. You do not hand us a card and we do not take one from your guest. The booking authorizes against your credit limit, posts a charge to your ledger, and is settled later by invoice.

The request#

Three fields do the real work. The rest is guest detail.

orderId — the order you priced.

acceptedTotal — the grand total you are agreeing to, as last quoted. If the price has moved, the call is rejected rather than charging you the new figure.

externalBookingId — your idempotency key. Your own id for this attempt, unique within your account, max 64 characters. Generate it before the first attempt and persist it.

primaryGuest is mandatory. callbackUrl is how you avoid polling — see Callbacks.

cURL

curl -X POST "$BASE/v1/bookings" \
  -u "$ELIVAAS_API_KEY:" \
  -H 'Content-Type: application/json' \
  -d &#39;{
    "orderId": "ord_7Kd2m1RtY0",
    "externalBookingId": "your-ref-000123",
    "acceptedTotal": 22050.00,
    "primaryGuest": {
      "firstName": "Asha",
      "lastName": "Rao",
      "email": "asha@example.com",
      "phone": "+919812345678"
    },
    "specialRequests": "Late check-in, around 10pm",
    "callbackUrl": "https://you.example.com/hooks/elivaas"
  }&#39;

201 (trimmed)

{
  "bookingId": "bkg_20Etl54TyD",
  "externalBookingId": "your-ref-000123",
  "status": "CONFIRMED",
  "checkIn": "2026-08-10",
  "checkOut": "2026-08-13",
  "totalAmount": 22050.00
}

orderIdstringrequired: From a prior POST /v1/orders.
externalBookingIdstringrequired: Your idempotency key. Unique within your account, max 64 characters.
acceptedTotalnumberrequired: The order's grand total you are accepting. Compared against the live price; a mismatch is 409.
primaryGuestBookingGuestrequired: Lead guest for the stay.
additionalGuestsarray: Everyone else on the booking.
specialRequestsstring: Free text, passed through to the property.
callbackUrlstring: An https URL we POST the booking's terminal outcome to. Requires a signing secret on your account.

Idempotency, and why it is not optional#

How it behaves:

You send	You get
A new id	A new booking
The same id, same payload	The original booking. Nothing new is charged
The same id, a different payload	`409` — two different bookings attempted under one id

The key is unique per account, not globally. Another account may use the same string; it will never collide with yours.

The credit gate #

Every booking is authorized against your credit limit before anything is reserved. The check runs synchronously and takes a lock on your balance, so two concurrent bookings cannot both spend the last of your credit.

A refusal is 402 with the exact numbers, so you can show a real message rather than "please try later".

INSUFFICIENT_CREDIT — shortfall is how much more you need, in rupees. Pay an invoice or ask us to raise the limit.

ACCOUNT_ON_HOLD — an overdue balance past your grace period has blocked booking entirely. Reads keep working; only booking is refused. Paying clears it.

Treat 402 as a normal branch in your booking flow. It is not an error condition — it is the answer.

402

{
  "status": 402,
  "error": "Payment Required",
  "message": "This booking would exceed the agent group's available credit.",
  "path": "/v1/bookings",
  "timestamp": "2026-07-29T13:05:56.198280408Z",
  "reasonCode": "INSUFFICIENT_CREDIT",
  "availableCredit": 18400.00,
  "shortfall": 3650.00
}

Watch your headroom with GET /v1/statement rather than discovering it at booking time.

When the price moved#

A 409 with acceptedTotal and currentTotal means the stay repriced between your quote and your booking. Nothing was booked and nothing was charged.

Reprice with POST /v1/orders/{orderId}/reprice, show the new figure, and book again with it. Retrying the old total fails identically — by design, so a price can never move underneath a customer who already agreed to one.

`202`, and what it means#

A 201 means confirmed. A 202 means accepted and being confirmed with the property — the booking exists and is in progress.

It is not a refusal and not an error. Either wait for the callback or poll GET /v1/bookings/{bookingId} until the status is terminal. Do not re-POST: the booking already exists, and a second attempt under a new id would duplicate it.

Reading bookings back#

GET /v1/bookings/{bookingId} returns one booking in full.

GET /v1/bookings lists them, and takes your ids as well as ours — externalBookingIds looks up by the key you supplied, which is usually what your reconciliation job actually has.

updatedSince gives you an incremental feed of everything that changed, which is the right shape for a nightly sync.

A booking belonging to another account is never returned — by either id — and comes back as 404, identically to one that does not exist.

By your own id

curl -G "$BASE/v1/bookings" -u "$ELIVAAS_API_KEY:" \
  --data-urlencode 'externalBookingIds=your-ref-000123'

What changed

curl -G "$BASE/v1/bookings" -u "$ELIVAAS_API_KEY:" \
  --data-urlencode 'updatedSince=2026-07-28T00:00:00Z' \
  --data-urlencode 'size=100'

What the booking did to your account#

It posted a charge to your ledger and reduced your available credit. Nothing is payable yet. On your billing cycle those charges become a GST invoice, and that is what you settle.

Next#

Callbacks — stop polling. Or Amendments and Cancellations for changing a live booking.