- Build a booking flow — hosted sign-in, the BFF pattern, and onboarding.
- Create a package booking with a slate — how slates are planned and booked.
Every call goes through your BFF, which attaches the
x-api-key header. Three
of the four calls also forward the client’s Authorization: Bearer <token>.
The browser never sees the API key.How it works
Booking a credit is four calls, always in this order:- Identify the client.
POST /clients/mereturns the signed-in client’s profile: theirclientIdand their saved addresses. - List their credits.
GET /clients/me/creditsreturns every package credit the client can book, with the sessions left on each. The client picks one. - Plan the slate from the credit.
POST /availability/package-slatewith the credit’sorderIdandorderItemId, the client’sclientId, a location and anrrulereturns aprimarySlatewith aslateId. - Book the slate as the client.
POST /clients/me/orders/{orderId}/package-bookingswith{ orderItemId, idempotencyKey, slateId }books every session in one call and draws them from the credit.
Only paid credits can be booked here.
GET /clients/me/credits lists a
credit only when its order is PAID, and the booking call refuses any credit
that list would leave out. That is the rule for every client flow: a client
books their own credits only once the order is PAID. The API-key route
also books from DRAFT and PENDING orders, so if your server books
credits with the key alone, check the order’s status first. A client who
hasn’t paid yet should finish checkout first. See Accept payments with Stripe.1
Identify the client
Call The response is the client profile under Keep two things from it on the server:
POST /clients/me with both credentials. It onboards a first-time client
(201) and returns the existing profile on every later call (200), so it is
safe to call whenever the client opens their packages. See
Onboard the client.data (abridged):clientId for Step 3, and the
addresses the client can pick from.2
List the client's credits
GET /clients/me/credits returns the credits the client can book. Each entry
is one PACKAGE order item they own:quantityRemainingis how many sessions the client can book now. It is the session count the slate in Step 3 plans.expiresAtis the last moment a session can start.nullmeans the credit never expires.quantityReturnedcounts sessions cancellations gave back, ever. It is already insidequantityRemaining. Use it for copy such as “1 session was returned to your package”, never to compute a balance.packageIdcan benull, and the package may since have been edited or deleted. The credit still books: it keeps the service and offering it was sold with. Name it fromserviceIdandofferingId.
200 with data: []. Used-up, expired and
removed credits are left out, and so are credits on unpaid or cancelled
orders.3
Plan the slate from the credit
When the client picks a credit, your BFF plans it with
The full request body MarketBox receives looks like this:A credit plans differently from a package:Show the client the times in
POST /availability/package-slate. Send the credit’s orderId and
orderItemId in place of packageId, plus the client’s clientId from
Step 1. This call takes only the API key.- It plans only the sessions left. The
rrule’sCOUNTis replaced by the credit’squantityRemaining. Send any boundedCOUNT; the credit decides the number. - It plans the credit’s own service and offering. You don’t send them.
- No session starts at or after the credit’s
expiresAt. A credit that expires before its sessions fit is422 NO_COMPLETE_SLATE. clientIdguards the order. An order that belongs to another client is refused exactly like one that doesn’t exist,400 INVALID_ORDER_REFERENCE, and nothing is planned.
status: "OK" and a primarySlate. Here the credit
had three sessions left (slots abridged to the first):slots[], in the booking’s zone
(bookingTz). Keep the slateId on the server or in the page; Step 4 needs
only that. A slate from alternates[] or cadenceAlternatives[] of the same
response is planned from the same credit, so it books the same way.Nothing bookable is a
422: NO_COMPLETE_SLATE when no single supplier can
fit every session before the expiry, NO_AVAILABILITY when there is no
availability in the window at all. Let the client try other days, a later
start date or another address.4
Book the slate as the client
Book the slate with the client’s token on
A successful booking is The bookings record the client as the person who made them, as if they
had booked in the MarketBox dashboard. Your Application is kept in each
booking’s history as the channel.Read the credits again (Step 2) to refresh the page. A credit with nothing
left drops out of the list.
POST /clients/me/orders/{orderId}/package-bookings. The body is the same as
the API-key route: the orderItemId, an idempotencyKey and the slateId.Create the idempotencyKey in the browser when the client clicks Book,
and send the same key if the click is retried. A key minted on every BFF call
can’t make a retry safe.201, one entry per session (abridged to the first):What the booking call checks
The client-plane route runs every check of the API-key route — the credit’s own offering, sessions remaining, the expiry, a cancelled order and idempotency. See What a booking call checks. It adds three of its own, all checked before anything is booked.The order must be the client’s
Another client’s order is a404 with the same body as an order that doesn’t
exist, so an id can’t be used to probe someone else’s order:
Only a listed credit books
A creditGET /clients/me/credits would not list is 409 CREDIT_NOT_BOOKABLE: an order that isn’t PAID, a credit that is used up or
expired, a removed line, or a line that isn’t a package.
CANCELLED order is 409 ORDER_CANCELLED instead. Don’t retry either one:
re-read the credits and offer only those listed.
The slate must be planned from this credit
AslateId or slotIds must come from a slate planned with this orderId
and orderItemId. A slate planned from a packageId, or from another credit,
is a 404 with the same body as an unknown id. Plan again from the credit
(Step 3). Explicit sessions need no slate.
When a slot goes stale
If a session’s time was taken between planning and booking, the call returns409 SLOT_NO_LONGER_BOOKABLE with freshSuggestions. Those slates are
planned from the same credit, so the client can pick one and you book its
slateId on this route with a new idempotencyKey. freshSuggestions is
null when the credit has nothing left to plan.
Reference
Endpoints used in this guide
Configuration
Errors and edge cases
See Errors for the full envelope and code list.