Skip to main content
A hold reserves a supplier’s time for a short while. Nobody else can book or hold that time until the hold is converted into bookings, released, or lapses. Its id is a 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.
If you hold, you convert. POST /bookings and POST .../orders/{orderId}/package-bookings never use a hold, not even your own. Called for time you hold, they return 409 SLOT_HELD. Once you hold time, the only way to book it is POST /holds/{reservationId}/convert. See Handling a held slot.

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 in data:
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 the POST /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:
Read the hold first when a convert fails. Most failures are an interval that lacks the field the booking needs.

Converting a hold

POST /v1/projects/{projectId}/holds/{reservationId}/convert turns the hold into bookings:
The order item’s skuType decides what’s booked:
  • A SINGLE_SESSION item books the hold’s one interval as a single booking. A hold with more than one interval is a 409 RESERVATION_MULTI_INTERVAL.
  • A PACKAGE item books every interval as a session of the package, drawing one session each from the item.
  • Any other skuType is a 400 UNSUPPORTED_SKU_TYPE.
The client comes from the order, and the service and offering from the order item. So a booking and the session it draws down always agree. 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 already CONVERTED 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 be PAID. 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 a 409:
The hold is still 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}/holds
  • GET /v1/projects/{projectId}/holds/{reservationId}
  • POST /v1/projects/{projectId}/holds/{reservationId}/convert
  • POST /v1/projects/{projectId}/holds/{reservationId}/release
  • POST /v1/projects/{projectId}/availability/package-slate — see Availability and slates