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.How it works
A checkout with a hold is three calls, always in this order:- Hold the time.
POST /holdswith exactly one ofintervals(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), orslotIds(a cherry-picked subset). Returns areservationIdand aheldUntil. - Create the order and take payment. An order with a
SINGLE_SESSIONitem (for a one-session hold) or aPACKAGEitem (for a multi-session hold) is what funds the bookings. Charge the client however you already do. Pass this hold’sreservationIdon 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. - Convert.
POST /holds/{reservationId}/convertwith{ 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 pollingGET /orders/{orderId}untilstatusreadsPAID(the only proof the charge went through), or as soon as the client’sstripe.confirmPaymentresolves, if the hold may expire beforePAIDlands. The second books before payment is confirmed, so keep polling and reconcile any order that never reachesPAID. A package hold in a client flow is the exception: convert it only after the order readsPAID, because a client’s package credits book only once paid. Convert is idempotent on thereservationId, so a retry replays the same bookings instead of double-booking.
POST /holds/{reservationId}/release frees the
time immediately.
1
Hold a single session
Send A successful hold returns
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.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: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.2
Hold a package slate instead
Same endpoint, same response shape — swap 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
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.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 You can also read the hold at any point with
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.GET /holds/{reservationId} —
it echoes the same full interval shape, which is the fastest way to check
what convert is actually going to build: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 A successful convert returns
skuType:- a
SINGLE_SESSIONitem books the one held interval as an ordinary single booking (businessModelType: "SINGLE_BOOKING"); - a
PACKAGEitem books every held interval as package sessions, drawing down that item’s credits.
201 with one entry per booked session:packageOrderItemId echoes the order item the credits came from. For a
SINGLE_SESSION item it is the same id as orderItemId.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.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.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, becauselocationId 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.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
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.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 callPOST /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:
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}/convertwith yourorderIdandorderItemIdinstead. That is the booking. - It’s not yours (another client is mid-checkout) → the time is
genuinely taken for now.
heldUntiltells 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.
Troubleshooting
Every failure below is deterministic and tells you what to fix. Nothing here exceptOCCUPANCY_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 bothPOST /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.