Skip to main content
A hold is a claim on a supplier’s time. It blocks that time for everyone else — nobody can book it, hold it, or even see it as available — until you either convert the hold into real bookings or it lapses. It is what turns “the client is on the payment page” into a state the booking engine actually respects. A hold works on any supplier time: one session, a cherry-picked subset of a package slate, or a whole 8-session slate. Holding a single session needs no package, no slate, and no PACKAGE business model — POST /holds with an explicit intervals array is all it takes. Convert is one endpoint for both shapes: it reads the order item you name and decides from its skuType whether it is booking one single session or N package sessions. It builds on The booking engine model — read that first if you haven’t. Holds pair naturally with Accept payments with Stripe: hold, charge, convert once the payment succeeds. For the guard that makes any of this mean anything, see Concurrency. For where the hold sits in the whole checkout, see Client checkout, end to end. For the hold object and each route on one page, see Holds.
Every request in this guide is authenticated with the x-api-key header, attached server-side by your BFF — never in the browser. A hold names supplier time and hands back a reservationId that can book that time; it does not belong in a client bundle.
If you hold, you convert. The direct booking routes (POST /bookings and POST /orders/{orderId}/package-bookings) know nothing about holds and will not consume one — not even your own. Call them for time you hold and they return 409 SLOT_HELD, naming the very reservationId you created. Once you have held time, the only way to book it is POST /holds/{reservationId}/convert. See Handling a held slot below.

How it works

A checkout with a hold is three calls, always in this order:
  1. Hold the time. POST /holds with exactly one of intervals (an explicit list of supplier time — the single-session form; each interval carries the same location contract as a booking), slateId (every slot of a package slate), or slotIds (a cherry-picked subset). Returns a reservationId and a heldUntil.
  2. Create the order and take payment. An order with a SINGLE_SESSION item (for a one-session hold) or a PACKAGE item (for a multi-session hold) is what funds the bookings. Charge the client however you already do. Pass this hold’s reservationId on the order-create call — it’s the preferred region source, so the order prices off the exact location the hold (and the eventual bookings) already carry. See Regional pricing.
  3. Convert. POST /holds/{reservationId}/convert with { orderId, orderItemId } — call it from your server once the payment succeeds. The public API sends no webhooks: Stripe’s events go to MarketBox, not to you. Convert does not check payment, so you choose when: after polling GET /orders/{orderId} until status reads PAID (the only proof the charge went through), or as soon as the client’s stripe.confirmPayment resolves, if the hold may expire before PAID lands. The second books before payment is confirmed, so keep polling and reconcile any order that never reaches PAID. A package hold in a client flow is the exception: convert it only after the order reads PAID, because a client’s package credits book only once paid. Convert is idempotent on the reservationId, so a retry replays the same bookings instead of double-booking.
If the client abandons, POST /holds/{reservationId}/release frees the time immediately.
1

Hold a single session

Send intervals — an explicit list of supplier time. This is the general form and the one to reach for when there is no package involved: a single session can now be held on its own, with nothing but a supplierId and a UTC window.Every interval carries the same location contract as a booking — bookingTz and locationType are required, and locationType decides which of locationId / latitude / longitude / address must come with it. That isn’t ceremony: convert rebuilds the booking from the reservation alone (never by re-reading a slate that may have expired while your client was paying), so whatever the booking will need, the hold has to be holding already.These are the rules on POST /bookings, unchanged. For the address shape, see Booking addresses.heldBy is who owns the hold — use your checkout session id. It is the key to the heartbeat in Step 3, and convert must present the same value.
A successful hold returns 201 with the reservation and the exact time — and the exact place — it claims. The response echoes the full interval shape back, so you can verify what convert will build the booking from:
locationId alone is not enough — and an stz_ id is not a Location. A mobile / in-home session’s locationId is a supplier travel zone (stz_…), which lives in a different table from a Location (loc_…). locationType is what tells convert which one it is holding. Send an stz_ id with locationType: "PHYSICAL" and convert will look it up in Locations and fail with 404 Location stz_… not found. See A travel-zone checkout, end to end.
Exactly one of intervals, slateId, or slotIds. Sending two (or none) is a 400 VALIDATION_ERROR. holdDurationMins is optional and resolves: your value → the offering’s holdDurationMinsOverride (slate and slot forms only, where an offering is known) → the project’s suggestionConfig.holdDurationMins → 5 minutes.
Every interval in one request is claimed in a single transaction — a hold is all-or-nothing. You never end up holding 3 sessions of a 5-session package and having to unwind it yourself.
2

Hold a package slate instead

Same endpoint, same response shape — swap intervals for the slateId returned by POST /availability/package-slate (see Create a package booking). Every slot of the slate is held at once. Pass slotIds instead to cherry-pick a subset.No location fields at all on this form. The slate’s persisted slots already carry bookingTz, locationType, locationId, coordinates and address, and the hold copies them onto the reservation for you. The required fields introduced above apply only to the explicit intervals form — package integrators send exactly what they always sent.
The hold carries one interval per session — each one echoed with the location the slate resolved for it (abridged here to the first of eight; this slate was built on the lat/lng branch, so its slots are TRAVEL_ZONE):
Slates stay resolvable for 24 hours after they’re built. Holding a stale slateId (or one from another project) is a 409 with SUGGESTION_EXPIRED, SLATE_NOT_FOUND, or SLOT_NOT_FOUND — rebuild the slate rather than retrying.
3

Keep the hold alive while the client pays

Expiry is lazy. Nothing runs at heldUntil — no sweeper, no webhook, no status change. The hold simply stops blocking anyone at that instant, and the time is up for grabs again. A hold read after its heldUntil may still report status: "HELD"; compare heldUntil against the current time rather than trusting status alone.So: convert before heldUntil, or extend. To extend, re-POST to /holds with the same intervals, the same heldBy, and the reservationId you were given. That is your checkout heartbeat: the existing hold’s heldUntil moves out, the same reservationId comes back, and no second hold is minted — so the id you convert later is still the right one.
Thread the location fields through the heartbeat too. The heartbeat re-sends intervals, and intervals are validated the same way on every call: an interval without bookingTz and locationType is a 400 VALIDATION_ERROR, heartbeat or not. Keep the array you built in Step 1 verbatim (or replay the intervals the 201 echoed back at you) — don’t rebuild a trimmed { supplierId, startUtc, endUtc } version for the heartbeat.
You can also read the hold at any point with GET /holds/{reservationId} — it echoes the same full interval shape, which is the fastest way to check what convert is actually going to build:
A hold from a different heldBy over the same time is a conflict, not an extension — you get 409 SLOT_HELD. Keep heldBy stable for the life of one checkout; don’t regenerate it per request. Passing a reservationId whose heldBy doesn’t match yours is 409 RESERVATION_FORBIDDEN; one that is unknown is 409 RESERVATION_NOT_FOUND; one already converted or released is 409 RESERVATION_NOT_HELD.
4

Convert the hold into bookings

On payment success, convert. One endpoint for both shapes — you don’t tell it what you’re booking, it reads the order item’s skuType:
  • a SINGLE_SESSION item books the one held interval as an ordinary single booking (businessModelType: "SINGLE_BOOKING");
  • a PACKAGE item books every held interval as package sessions, drawing down that item’s credits.
The bookings are rebuilt from the reservation (supplier, time, location) and the order item (client, service, offering, price) — never by re-resolving a suggestion that may have expired — so the booked service and the credit it draws down cannot disagree.
A successful convert returns 201 with one entry per booked session:
This response is NOT wrapped in { data }, unlike orders and bookings. Read created, failed, and quantityRemaining directly off the body. created[].sessionIndex is 0-based (a slate’s slots[].sessionIndex is 1-based — don’t compare them without adjusting).
packageOrderItemId echoes the order item the credits came from. For a SINGLE_SESSION item it is the same id as orderItemId.
Convert is idempotent — retry it freely. It is keyed internally on convert:<reservationId>, and the reservation flip is atomic with the booking write, so a convert you send twice (a timeout, a double click, a second poll that also saw PAID) replays the same bookings rather than creating a second set. An already-CONVERTED reservation short-circuits and returns its stored result. Don’t try to de-duplicate this yourself.
Convert is what sends the emails — holding sends nothing. A hold has no booking attached to it, so nothing is mailed while the client is still on the payment page. The moment convert succeeds, MarketBox sends the client their booking confirmation and each assigned supplier their new-booking notice, and schedules the reminder and the rating requests that follow.So don’t send your own booking confirmation from your server — the client will already have one. A multi-session package converts into a single confirmation covering every session, not one per session. A replayed convert does not re-send anything.See Emails for the full set and for the two things you can configure: the from name and the reply-to address.
Convert too late and you get 409 HOLD_EXPIRED — the hold stopped blocking at heldUntil and the time may have gone. If it’s still free, hold it again and convert the new reservation; if someone took it, you’ll see SLOT_BOOKED instead.
A charged card plus HOLD_EXPIRED leaves money with no booking. The public API has no refund endpoint, so if the time is gone the business has to refund the payment from the MarketBox dashboard. Avoid getting there: choose a holdDurationMins long enough to cover a 3-D Secure challenge, and keep the heartbeat (Step 3) running until convert returns — not just until the client clicks Pay.
5

Release, if the client abandons

Don’t wait for lazy expiry when you already know the checkout is dead — release, and the supplier’s time is bookable again immediately.
Release is idempotent. An already released hold returns RELEASED. An already converted one returns CONVERTED: it is booked and can’t be un-booked this way. An unknown reservationId returns NOT_FOUND. All three are 200s and final states, not failures.
Release can return 409 OCCUPANCY_CONTENTION. When other writes keep winning the race for the supplier’s calendar, the API retries the release, then gives up:
The hold is still HELD, so the time stays blocked. Retry the release after a short, jittered pause. If you stop retrying, the hold still lapses on its own at heldUntil.

A travel-zone checkout, end to end

A mobile / in-home session — the supplier travels to the client — is the flow with the most moving parts, because locationId is a supplierTravelZoneId (stz_…) rather than a Location, and the client’s coordinates and street address are what the supplier actually navigates to. All of it has to be on the hold, because convert builds the booking from the hold.
1

Hold the travel-zone session

locationType: "TRAVEL_ZONE" + the stz_ zone id + latitude + longitude + the full structured address. Miss any one of them and the hold is rejected with a 400 before anything is claimed.
The 201 echoes every one of those fields back on intervals[0] — if locationType or address come back null, you didn’t send them, and the convert in Step 3 will fail. Check the echo, don’t assume.
2

Create the order and charge the client

Nothing travel-zone-specific here: an order with one SINGLE_SESSION item for the service and offering being sold, plus this hold’s reservationId, then your usual Stripe flow. The address you sent to /holds is the session’s address — it is not the order’s billing address and is not sent again on the order; passing reservationId is what lets the order read that same address back out to resolve the same regional price the booking will use. See Regional pricing.Heartbeat the hold while the payment page is open (Step 3 above), re-sending these same intervals with all their location fields plus the reservationId.
3

Convert on payment success

Convert reads locationType: "TRAVEL_ZONE" off the reservation, so it does not try to resolve stz_01kv60qgs4e4nbjhzradnqtj0h as a Location. It writes the booking with the held zone, coordinates and address, derives bookingLocalDate / bookingLocalStartTime / … from bookingTz, and — for travel-zone work — prices the offering from the client’s region (address.country / address.state / address.zipCode), because there is no Location record to price against.
404 Location stz_… not found on convert. This means the hold was placed with an stz_ travel-zone id but locationType: "PHYSICAL", or no locationType at all — so convert looked the id up in the Locations table, where a travel zone does not exist. It is not a data problem and there is nothing to retry: fix the hold. Release the reservation, re-hold with locationType: "TRAVEL_ZONE" (plus latitude, longitude, address), and convert the new reservationId. Confirm with GET /holds/{reservationId} that intervals[0].locationType reads TRAVEL_ZONE before you convert.

Handling a held slot

This is the one error worth memorising, because it is the shape of the most common mistake: you hold time, then call POST /bookings (or POST .../package-bookings) for that same time, and you are blocked by your own hold. The direct booking routes never consume a hold. They return 409:
The body hands you everything you need. conflicts can mix holds and bookings, so take the first entry whose claimType is HOLD, read its reservationId, and:
  • It’s your hold (the reservation you created for this checkout) → don’t retry the booking call. Call POST /holds/{reservationId}/convert with your orderId and orderItemId instead. That is the booking.
  • It’s not yours (another client is mid-checkout) → the time is genuinely taken for now. heldUntil tells you when it lapses. Offer a different slot; don’t spin on the same one.
SLOT_BOOKED is the same shape with claimType: "BOOKING" and a bookingId instead — a confirmed booking is in the way, and no amount of converting will move it. Search availability again.
The reverse mistake — holding and then converting — has no trap: convert consumes your own hold by design, and any other live claim over the same time still blocks it with the same SLOT_HELD / SLOT_BOOKED body.

Troubleshooting

Every failure below is deterministic and tells you what to fix. Nothing here except OCCUPANCY_CONTENTION is worth retrying unchanged.

Placing or extending a hold — POST /holds

Converting a hold — POST /holds/{reservationId}/convert

Releasing a hold — POST /holds/{reservationId}/release

GET /holds/{reservationId} is your debugger. It returns the reservation exactly as convert will read it — including locationType, locationId, latitude, longitude and address. If a convert is failing, read the hold first: nine times in ten the interval is missing the field the booking needs.

Reference

Endpoints used in this guide

Configuration

Interval fields (the intervals form)

slateId and slotIds take none of these: the slate’s slots already carry them and the hold copies them onto the reservation.

Errors and edge cases

See Troubleshooting above for the full status/code table for both POST /holds and POST /holds/{reservationId}/convert, and Errors for the envelope and the global code list. The hold object, its statuses and every holds route are in Holds.