Order-first
The order is the purchase record. The order item is the thing that gets consumed. A booking is what consumes it. You always create the order (and its item) before you create a booking. The booking’s service line then carriesorderId and orderItemId, tying the
schedule entry back to the commerce record it drew down.
For a single session, one order item funds exactly one booking. For a
package, one order item funds many bookings — see below.
An order can exist without ever being paid, and a booking can be created
against it while it’s still unpaid. See Credits and payment.
Single vs package
MarketBox has two shapes of order item, and the difference between them is the difference between the two booking flows you’ll build. Single booking — one order item per service line. You create an order with aSINGLE_SESSION item, then create one booking whose service line
references that item’s orderId and orderItemId. One item, one booking,
one draw-down.
Package booking — one PACKAGE order item, drawn down across N sessions.
This is the part worth internalizing: the order item is the package
instance, and its quantityRemaining field is the live credit ledger.
You don’t track “how many sessions has this client used” yourself — you read
it off the order item.
POST /orders/{orderId}/package-bookings. The server creates every session’s
booking atomically, stamps each one with the same packageOrderItemId, and
decrements quantityRemaining by however many sessions it books. When
quantityRemaining hits zero, the package is spent — there’s nothing left
to draw down.
Slates
Booking eight sessions one at a time — checking availability, picking a slot, repeating — doesn’t scale, and it’s easy to end up with sessions that don’t actually fit the client’s recurring schedule. MarketBox solves this with slates. A slate is a complete, N-session plan for a package from one supplier, computed in one call from a recurrence rule (rrule) and a location. Ask
POST /availability/search for one-off single slots; ask
POST /availability/package-slate for a whole plan — the server picks the
best single supplier that can fill every session, resolves each session’s
time and location up front, and hands you back a slateId.
The two-step shape is always the same:
- Build the slate.
POST /availability/package-slatewith thepackageId, a location, and anrrule(e.g. every Mon/Wed/Fri, 8 sessions) returns aprimarySlatewith aslateIdand the resolvedslots[]. To plan what is left on a credit the client already owns, send itsorderIdandorderItemIdinstead ofpackageId. - Book it by id.
POST /orders/{orderId}/package-bookingswith just{ orderItemId, idempotencyKey, slateId }— the server re-resolves every session’s supplier, time, and location itself (including filling in the location for travel-zone bookings) and creates all N bookings in one atomic transaction.idempotencyKeyis required: mint it once per booking attempt and resend the same key on a retry, so a retry replays the first result instead of booking twice.
The atomic write (
atomicity: "all_or_nothing", the default) books at most
15 sessions in one call. A larger slate is refused with
422 PACKAGE_SLATE_TOO_LARGE_FOR_ATOMIC, and nothing is booked. Book it in
smaller calls with slotIds, or send atomicity: "best_effort" if your
project has partial package booking enabled — otherwise that is
422 BEST_EFFORT_NOT_ENABLED.slateId back is enough. (An older, more manual path
exists where you transcribe each resolved slot into a sessions[] array
yourself, but book-by-slateId is the one to reach for by default.)
Slates aren’t held forever — a chosen slot can go stale between building the
slate and booking it, in which case you’ll get a 409 telling you so with
fresh alternatives. The availability and slates guide
covers building slates, holds, and stale-slot recovery in full.
Reserving vs. booking
A plain booking —POST /bookings, or a package booked directly by
slateId/sessions/slotIds — is created immediately. There’s no
in-between “reserved” state and no reservation window to manage.
A timed hold is the in-between state. POST /holds claims a supplier’s
time — one session, a cherry-picked subset of a slate, or a whole slate —
so nobody else can book it (or even see it as available) while your client
pays. On payment success you convert the hold into real bookings with
POST /holds/{reservationId}/convert; on abandonment you release it, or you
simply let it lapse at heldUntil.
Holding a single session needs no package and no slate — just the
supplier and a UTC window. And the rule that catches everyone: if you
hold, you convert. The direct booking routes never consume a hold, not
even your own — they return 409 SLOT_HELD with the reservationId in the
body. See Hold slots during checkout for
the full lifecycle.
Credits and payment
Here’s the detail that trips up most integrations: credits exist at order creation, not at payment. Creating an order (with its item) immediately gives you something bookable, and creating a booking against that order item succeeds even while the order is stillDRAFT and unpaid. A CANCELLED
order is the one exception: its credits were released when it was cancelled,
so it plans and books nothing (409 ORDER_CANCELLED).
Credits outlive the catalog. A booking against an order item already bought
succeeds after its service leaves LIVE, or its package is ARCHIVED. Only
its offering must still be ACTIVE: otherwise the booking is
422 NOT_SELLABLE. New orders, by contrast, need a LIVE service and an
ACTIVE offering. See
What the status controls.
Payment — via Stripe or a manual transaction — settles the order. It moves
money and updates the order’s status and paid amount. The API-key booking
routes don’t check it.
What your flow should require depends on what is being booked:
- Single bookings: don’t require payment. Book against a
DRAFTorder and settle it afterward, in a client flow too. - Package credits in a client flow: require it. A client books their
own credits only once the order’s
statusreadsPAID. The client plane (Book a client’s package credit) enforces this for you. If your server books credits with the API key alone, check the order’sstatusfirst, because the key routes won’t. - A business booking on a client’s behalf: may book package credits from an unpaid order.
This also means you can build the entire scheduling half of your
integration — orders, order items, single and package bookings — without
touching payment at all, then layer Stripe on top separately. See
Accept payments with Stripe for how
charging an order works once you’re ready for it.
Participant settings
Each service carriesparticipantSettings: what suppliers and clients may do
with, and see on, bookings of that service. You read them on
GET .../services and GET .../services/{serviceId}, and set them on
POST .../services and PUT .../services/{serviceId}.
It is replaced whole on
PUT. Send every field, or omit
participantSettings to leave the settings unchanged. The one exception is
client.participantDisplay: omitted, it keeps its stored value.
The settings bind suppliers and clients acting for themselves — for example on
the supplier plane,
where a disabled action is 403 PARTICIPANT_ACTION_DISABLED and a passed
notice window is 409 NOTICE_WINDOW_PASSED. Your API-key calls act for the
business, and the settings don’t restrict them.
Where to go next
Create a single booking
Walk through the single-session flow end to end: order, order item, booking.
Create a package booking
Build a package order item and draw it down across multiple sessions.
Availability and slates
Search single slots, build package slates, and handle stale-slot retries.
Booking addresses
When a structured address is required and how it’s threaded through bookings and slates.
Services and offerings
The catalog a booking is made from: services, business models and offerings.
Packages
Prepaid sessions of one offering, and what stops them being sold or booked.
Holds
Reserved supplier time: place, extend, convert and release.
Transactions
The money ledger behind every order, and how a row settles it.