Skip to main content
This guide is for a client who already owns a package credit and comes back to your booking flow to schedule it. They may have bought the package earlier and never booked it. Or a cancellation may have returned some sessions to it. Either way, there is no new order and no payment: the client spends sessions they already paid for. The flow plans one slate from the credit and books the whole slate with a single call, like Create a package booking with a slate. The difference is who acts. The client is signed in, so the booking call runs on the client plane, as that client. It builds on two guides. Read them first if you haven’t:
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:
  1. Identify the client. POST /clients/me returns the signed-in client’s profile: their clientId and their saved addresses.
  2. List their credits. GET /clients/me/credits returns every package credit the client can book, with the sessions left on each. The client picks one.
  3. Plan the slate from the credit. POST /availability/package-slate with the credit’s orderId and orderItemId, the client’s clientId, a location and an rrule returns a primarySlate with a slateId.
  4. Book the slate as the client. POST /clients/me/orders/{orderId}/package-bookings with { 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 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.
The response is the client profile under data (abridged):
Keep two things from it on the server: clientId for Step 3, and the addresses the client can pick from.
Two different things are called clientId. The OAuth clientId (NEXT_PUBLIC_OIDC_CLIENT_ID) identifies your Application to hosted login. The MarketBox clientId (cli_…) identifies the person in this project. Step 3 needs the cli_ one, read from this response.
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:
Show each credit with its sessions left and its expiry:
  • quantityRemaining is how many sessions the client can book now. It is the session count the slate in Step 3 plans.
  • expiresAt is the last moment a session can start. null means the credit never expires.
  • quantityReturned counts sessions cancellations gave back, ever. It is already inside quantityRemaining. Use it for copy such as “1 session was returned to your package”, never to compute a balance.
  • packageId can be null, 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 from serviceId and offeringId.
A client with no credits gets 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 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.
The full request body MarketBox receives looks like this:
A credit plans differently from a package:
  • It plans only the sessions left. The rrule’s COUNT is replaced by the credit’s quantityRemaining. Send any bounded COUNT; 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 is 422 NO_COMPLETE_SLATE.
  • clientId guards 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.
The same request-shape rules as a package slate apply. lookAheadStartDate needs a numeric ±HH:MM offset that matches the zone on that date — Toronto is -05:00 in November, not -04:00. timezone must be an IANA name, and rrule must have a bounded COUNT. Each is a 400 VALIDATION_ERROR. See Cadence rules.
A successful plan returns status: "OK" and a primarySlate. Here the credit had three sessions left (slots abridged to the first):
Show the client the times in 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 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.
This response is NOT wrapped in { data }. Read created, failed and quantityRemaining directly off the body.
A successful booking is 201, one entry per session (abridged to the first):
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.

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 a 404 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 credit GET /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.
A 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

A slateId 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 returns 409 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.