Every request in this guide is authenticated with the
x-api-key header,
attached server-side by your BFF — never in the browser.Prerequisite: the service needs an active
PACKAGE business
model. Package creation (POST /services/{serviceId}/offerings/{offeringId}/packages)
fails with 400 if the parent service doesn’t have one enabled. Business
models are set at the service level, not per-offering, so enabling it
makes packages creatable across every offering on that service.Every booking created from a package — including via holds → convert — is
stamped businessModelType: "PACKAGE" with packageOrderItemId
set, never SINGLE_BOOKING. Keep that in mind for reporting/analytics that
segment bookings by business model.How it works
A package booking is four calls, always in this order:- Find the package.
GET /services/{serviceId}/packages?status=ACTIVElists every sellable bundle on the service, across all of its offerings — the call a storefront makes before the client has picked an option. It gives you thepackageIdevery later step needs. - Build the slate.
POST /availability/package-slatewith thepackageId, a location, and anrrule(recurrence pattern) returns aprimarySlate— the best single supplier’s plan that fills every session — with aslateId. - Create the order.
POST /orderswith onePACKAGEitem is what makes the package purchasable — it’s the order item every session will draw down. The server derives the service, offering, session count, and price from the package. - Book the slate.
POST /orders/{orderId}/package-bookingswith{ orderItemId, idempotencyKey, slateId }creates all N bookings atomically — up to 15 sessions with the defaultall_or_nothing. You never copy times or locations out of the slate response by hand — the server re-resolves every session itself.
The API doesn’t require payment, but a client flow must. Credits exist
the moment the order is created, not when it’s paid, so this route books all
N sessions from a
DRAFT order. That suits a business booking on a client’s
behalf. When the client books their own package credits, book only from an
order whose status reads PAID. Check it yourself before calling this
route, because it won’t refuse an unpaid order. Or use the
client-plane route, which refuses unpaid
credits for you. Single bookings don’t need a PAID order in either flow.
A CANCELLED order books nothing. See
A cancelled order books nothing.1
Find the package
A package is a sellable bundle — a name, a The standard list envelope, one entry per bundle (abridged to two of the
service’s packages):Take the
creditCount, and pricing.
List every one on a service with
GET /services/{serviceId}/packages?status=ACTIVE. This is the discovery
call: it spans all of the service’s offerings, so you can make it before
the client has chosen an option, and each package carries its offeringId
so you can join it against the offerings list you already hold.Don’t list business models and render them as packages. The
PACKAGE business model is only a flag on the service meaning
“this service can be sold as packages.” It is not a sellable bundle,
and it carries no creditCount and no pricing — those fields live on
the packages this endpoint returns. Reading the business-models list and
rendering each row as a package gives you one package-shaped object with
null session count and null price, and hides the real bundles entirely.
The packages are here; the business model just permits them.A service with no packages is a
200 with data: [], not an error —
hide the tab, don’t branch on a status code. An unknown serviceId is a
404, so a typo can never masquerade as “this service sells no packages.”
Valid status values are DRAFT, ACTIVE, and ARCHIVED — there is no
INACTIVE.packageId of the bundle the client picks into the next step.2
Build the slate
Call A successful response carries
POST /availability/package-slate with the package, a location, a
timezone, and a bounded recurrence rule. The example below uses the
travel-zone branch (lat + lng + address) — you can pass a stored
locationId instead if you have one.status: "OK" and the primarySlate — the
sessionsFilled out of sessionsRequested, plus the resolved slots[]
(shown here abridged to the first slot of 8):If nothing bookable can be found, the response is
422 with code: "NO_COMPLETE_SLATE" (a complete single-supplier plan doesn’t exist under
the project’s supplier policy) or code: "NO_AVAILABILITY" (no availability
at all in the window). See the Reference section below.matchScore is the mean of matchComponents — here 1, since session one
lands on the window’s first day and the plan runs at exactly the requested
cadence. See How well a slate matches
for the full breakdown and how ranking works.You only need primarySlate.slateId for the next steps — hold onto it.3
Create the order
Create an order with one Same response shape as a single-session order — the order under This
PACKAGE item naming the package. You don’t send
the service, offering, session count, or price — the server derives all of
them from the package definition. You do need to tell the order where
this booking happens, or it prices off the client’s default saved address
(or the package’s DEFAULT rule) instead of the region you quoted. This guide’s flow never holds the slate (holding is
covered separately, below), so the region source it actually has on hand at
this point is the same address (or locationId) passed to
POST /availability/package-slate in Step 2 — pass that:data.order,
the item(s) under data.items[]. For a PACKAGE item, quantity and
quantityRemaining start equal to the package’s creditCount:orderItemId is the package instance — its quantityRemaining is
the live credit ledger every booking call decrements. Hold onto it along
with orderId and the slateId from Step 2.4
Book the slate
Book all N sessions in one call by passing the A successful response returns
orderItemId from Step 3,
the slateId from Step 2 and an idempotencyKey — no session details
required. Provide exactly one of sessions, slateId, or slotIds;
slateId is the recommended path. idempotencyKey is required: a body
without it is a 400 VALIDATION_ERROR.Mint the key once per booking attempt — for example in the browser when
the client clicks Book — and send the same key when you retry that
attempt. A key minted inside the handler is new on every call, so a retry
would no longer be recognised as one.201 with one entry per booked session (shown
abridged to the first two of eight):At most 15 sessions per atomic call.
all_or_nothing books every
session in one transaction, which caps it at 15. A larger slate is
422 PACKAGE_SLATE_TOO_LARGE_FOR_ATOMIC, and nothing is booked. Use
atomicity: "best_effort" (the project must enable
suggestionConfig.allowPartialPackages), or book a smaller slate.Stale slot. If a chosen slot was booked by someone else (or expired)
between building the slate and booking it, this call returns
409 with
{ code: "SLOT_NO_LONGER_BOOKABLE", freshSuggestions } instead of a
booking. Rebuild the slate (or use freshSuggestions directly) and retry —
don’t retry the same stale slateId blindly. freshSuggestions is planned
from the order item you are booking: its remaining sessions, its offering and
its expiry. So every slate in it can be booked on this order item. It is
null when the item has nothing left to plan.What a booking call checks
POST .../package-bookings draws down one order item. Before it writes
anything, it checks the request against that credit.
Every session books the credit’s own offering
APACKAGE order item funds sessions of one service and offering: the
ones it was sold with. Every service line of every session must name that
serviceId and offeringId. This applies to slateId, slotIds and
sessions alike. A session that mixes the item’s offering with another is
refused whole, and nothing is booked:
Book only what remains
Each service line uses one session of the credit. Asking for more sessions thanquantityRemaining is refused up front, and nothing is booked:
409 means another booking used the credits after the
check passed. Re-read quantityRemaining and book what is left.
A session that starts after the item’s expiresAt is 409 PACKAGE_EXPIRED.
With atomicity: "all_or_nothing" that refuses the whole call. With
best_effort the session is reported in failed[] and the rest book.
A cancelled order books nothing
When an order is cancelled, MarketBox cancels its remaining sessions and releases their credits.quantityRemaining can then look bookable, but those
credits belong to a dead order. So a CANCELLED order is refused on every
route that plans or books from it:
POST /availability/package-slatewith itsorderIdandorderItemId;POST /orders/{orderId}/package-bookings;POST /clients/me/orders/{orderId}/package-bookings;POST /bookingswith itsorderId;POST /holds/{reservationId}/convertwith itsorderId, even for a hold that already converted.
DRAFT, PENDING and PAID
orders book as before.
Retry safely with idempotencyKey
Send a fresh idempotencyKey for each booking attempt, and the same key
when you retry that attempt:
- A retry with the same key and the same body replays the stored
201. This holds even when the first call used the last of the credits, and even if the order was cancelled after the first call. A replay books nothing new and sends no second confirmation email. - The same key with a different body is
409 IDEMPOTENCY_KEY_CONFLICT. That includes a body that would be invalid on its own, such as one naming another offering. - A
slateIdorslotIdsretry must arrive within the slate’sresolvableUntilwindow. After that it is refused as a stale slate, not replayed. Check whether the first call succeeded by reading the order’s bookings.
Book the sessions left on a credit
A client who already owns a credit may want to book what is left on it: the rest of a package after a cancellation returned some sessions, or a package bought earlier and never scheduled. Plan the slate from the credit instead of from the package. SendorderId and orderItemId in place of packageId:
- It plans the sessions that remain. The
rrule’sCOUNTis replaced by the item’squantityRemaining. A package replaces it with itscreditCount. - It plans the credit’s own service and offering, so the slate always passes the offering check.
- The plan ends at the credit’s
expiresAt. No slot starts at or after it. When the window comes from the cadence (nolookAheadDaysorendDate) and you ask for no relaxation, a credit that expires before its sessions fit is422 NO_COMPLETE_SLATE, andreasonnames the expiry. When you size the window yourself, or opt in to relaxation, the window is cut at the expiry, and too early an expiry gives the genericNO_COMPLETE_SLATE. - It works after the package was edited or deleted. The order item keeps what it was sold with.
packageId, or orderId with orderItemId.
Neither, both, or orderId without orderItemId is a 400 VALIDATION_ERROR.
To have MarketBox confirm the credit is the client’s, add their clientId
beside orderId and orderItemId. An order that belongs to another client is
then refused exactly like an order that doesn’t exist: 400 INVALID_ORDER_REFERENCE, and nothing is planned. Without clientId, the order
is not checked against a client. clientId beside packageId is a 400 VALIDATION_ERROR.
Book the result with POST /orders/{orderId}/package-bookings and
{ orderItemId, idempotencyKey, slateId }, as in Step 4. When the signed-in client books
their own credit from your site, use the client-plane route instead. See
Book a client’s package credit.
A credit that can’t be planned is refused before anything is searched:
An expired credit, for example, comes back as:
Advanced: book explicit sessions
Book-by-slateId above is the recommended path for almost every
integration. Two more advanced paths exist for cases where you need more
control:
- Transcribe explicit sessions. Instead of sending
slateId, copy every resolved slot from the slate response into asessions[]array yourself. This is the fallback path — use it only if you must alter or filter individual sessions, and copy each slot verbatim (don’t re-derive locations). - Hold, then convert. Reserve the slate’s supplier time while the
client pays, then convert the hold into confirmed bookings on payment
success — the pattern you want for a timed checkout.
POST /holds { slateId }→POST /holds/{reservationId}/convert. Full walkthrough in Hold slots during checkout. Holding byslateId(orslotIds) needs no location fields at all — the slate’s slots already carry the timezone, location type, location and address, and the hold copies them onto the reservation. Only the explicitintervalsform makes you supply them.
Reference
Endpoints used in this guide
Configuration
Errors and edge cases
See Errors for the full envelope and code list.