reservationId, resv_….
A hold is how a checkout keeps a slot while the client pays. For the
step-by-step flow, with code, see
Hold slots during checkout. This page is
the reference for the object and its routes.
Every holds route takes the API key alone. Call them from your server, never
from the browser.
The hold lifecycle
Both
CONVERTED and RELEASED are final. A hold can’t be extended or
converted out of either.
Expiry is lazy. Nothing happens at heldUntil. The hold simply stops
blocking, and still reads HELD. Compare heldUntil with the current time
rather than trusting status alone. Converting after heldUntil is a
409 HOLD_EXPIRED.
Anatomy of a hold
The holds routes return the hold itself, not wrapped indata:
Convert builds the bookings from the hold alone. So the intervals must already
carry everything a booking needs.
GET /holds/{reservationId} shows you
exactly what convert will read.
A hold also has an owner, heldBy. It isn’t returned, so keep the value you
sent.
Placing a hold
POST /v1/projects/{projectId}/holds takes exactly one of three forms:
Sending none, or more than one, is a
400 VALIDATION_ERROR.
The other fields are optional:
The
201 returns the hold. Every interval is held in one write, so a hold is
all or nothing: you never hold 3 sessions of a 5-session slate.
Time already held or booked is a 409. The body names what’s in the way:
SLOT_BOOKED has the same shape, with claimType: "BOOKING" and a
bookingId. Search availability again: a booking won’t move.
Holding time you already hold, under the same heldBy, doesn’t conflict with
your own hold. Without reservationId it places a new hold, though, with a
new id, and the earlier hold loses that time. The earlier hold still reads
HELD but blocks nothing, and converting it is a 409 SLOT_HELD naming the
new hold. To keep one hold for the whole checkout, extend it.
Extending a hold
To keep a hold alive while the client pays, repeat thePOST /holds call with:
- the same intervals the hold already covers;
- the same
heldBy; - the hold’s
reservationId.
heldUntil moves out, the same reservationId comes back, and no second hold
is made. This is the checkout heartbeat, step 3 of
Hold slots during checkout.
The extend is refused with a 409 when the hold can’t be extended:
Reading a hold
GET /v1/projects/{projectId}/holds/{reservationId} returns the hold. An
unknown reservationId is a 404:
Converting a hold
POST /v1/projects/{projectId}/holds/{reservationId}/convert turns the hold
into bookings:
skuType decides what’s booked:
- A
SINGLE_SESSIONitem books the hold’s one interval as a single booking. A hold with more than one interval is a409 RESERVATION_MULTI_INTERVAL. - A
PACKAGEitem books every interval as a session of the package, drawing one session each from the item. - Any other
skuTypeis a400 UNSUPPORTED_SKU_TYPE.
heldBy is optional here. If you send it, it must be the hold’s owner, or the
convert is a 409 RESERVATION_FORBIDDEN.
atomicity is all_or_nothing by default: every session books, or none
does. best_effort books what it can, and needs the project’s
suggestionConfig.allowPartialPackages.
The 201 isn’t wrapped in data:
created[].sessionIndex is 0-based. The client and supplier get their booking
emails on the first convert, not on a replay. Two first converts racing each
other can both send them.
Convert is idempotent
Convert is safe to retry. A hold that’s alreadyCONVERTED returns the same
result again, and books nothing. That holds even when two calls race. Retry a
timeout or a 409 OCCUPANCY_CONTENTION with the same request.
Convert doesn’t check payment
The order need not bePAID. You choose when to convert: after
GET /orders/{orderId} reads PAID, or as soon as the client’s payment is
confirmed in the browser, if the hold might lapse first. The public API sends
no webhooks. See
Tracking state without webhooks.
In a client’s own flow, convert a package hold only once the order is PAID.
A client books their package sessions only from a paid order.
A CANCELLED order converts nothing, not even as a replay, because its
cascade released its sessions:
Releasing a hold
POST /v1/projects/{projectId}/holds/{reservationId}/release frees the time
at once. Call it when the client abandons checkout, instead of waiting for
the hold to lapse.
It answers 200 with the hold’s status after the call. All three are
final states, not failures:
Release can be refused under contention
A release competes with other writes for the supplier’s calendar. The API retries it internally. If it keeps losing, you get a409:
HELD. Retry the release after a short, jittered pause.
If you give up, the hold still lapses on its own at heldUntil.
Refusals
The most common refusals, by route. The full list, with what to do about each, is in Troubleshooting.
A hold enforces the slate’s 24-hour window when it is placed or extended, so
its times are never older than the slate allows. Convert doesn’t re-check it:
the hold already carries everything the bookings need, so a client who takes
a while to pay still books.
Every package refusal on convert leaves nothing booked, and retrying the same
call won’t help. Before you convert a package hold, check the item’s
quantityRemaining and expiresAt on GET /orders/{orderId}/aggregate.
Endpoint index
POST /v1/projects/{projectId}/holdsGET /v1/projects/{projectId}/holds/{reservationId}POST /v1/projects/{projectId}/holds/{reservationId}/convertPOST /v1/projects/{projectId}/holds/{reservationId}/releasePOST /v1/projects/{projectId}/availability/package-slate— see Availability and slates