Skip to main content
This guide walks through the flow for booking a package — a block of session credits redeemed across N recurring sessions (e.g. “8 swim lessons, Mon/Wed/Fri”). Instead of finding and booking each session one at a time, you build one slate — a complete, server-resolved N-session plan — and book the whole thing with a single call. It builds on The booking engine model — read that first if you haven’t, especially the Slates section. This guide also assumes the BFF pattern and an API key already set up.
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:
  1. Find the package. GET /services/{serviceId}/packages?status=ACTIVE lists 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 the packageId every later step needs.
  2. Build the slate. POST /availability/package-slate with the packageId, a location, and an rrule (recurrence pattern) returns a primarySlate — the best single supplier’s plan that fills every session — with a slateId.
  3. Create the order. POST /orders with one PACKAGE item 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.
  4. Book the slate. POST /orders/{orderId}/package-bookings with { orderItemId, idempotencyKey, slateId } creates all N bookings atomically — up to 15 sessions with the default all_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 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.
The standard list envelope, one entry per bundle (abridged to two of the service’s packages):
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.
Take the packageId of the bundle the client picks into the next step.
2

Build the slate

Call 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.
lookAheadStartDate must carry a numeric ±HH:MM offset (e.g. -04:00) — a Z suffix is rejected. That offset must also match the timezone’s actual UTC offset for that date, including daylight saving — Toronto is -04:00 in summer (EDT) but -05:00 in winter (EST), so a copy-pasted -04:00 will be wrong off-season. timezone must be an IANA identifier (America/Toronto, never EST). rrule must include a bounded, positive COUNT (e.g. COUNT=8) — an unbounded rrule almost always returns nothing bookable. All three are enforced request-shape validation (400), not just convention.
A successful response carries 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 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:
Holding the slate first (see Hold slots during checkout)? Pass reservationId instead — it’s the preferred region source when you have it, since the hold is the same record the eventual bookings are rebuilt from, so the order can’t disagree with them on price:
reservationId takes priority over locationId/address if you send more than one — see Regional pricing for the full priority order.
Without reservationId, locationId, or address, the order prices off the client’s default saved address (or their first saved address, if no default is set). Only a client with no saved address at all prices at the package’s DEFAULT rule. Either way, the price and currency may differ from the regional price you displayed on the storefront. If you get Package currency X does not match order currency Y, that’s what happened: you told the order what currency you quoted, but not where the booking happens, so it resolved a different regional rule. See Regional pricing.
Same response shape as a single-session order — the order under data.order, the item(s) under data.items[]. For a PACKAGE item, quantity and quantityRemaining start equal to the package’s creditCount:
Same nesting as single bookings: the order id is at data.order.orderId, not data.orderId. Read the PACKAGE item’s orderItemId off data.items[0].orderItemId.
This 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 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.
This response is NOT wrapped in { data }, unlike every other endpoint in this API (orders, bookings, etc.). A generic res.data unwrap silently breaks here — read created, failed, and quantityRemaining directly off the response body.
A successful response returns 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.
Off-by-one trap. sessionIndex is 1-based in the slate’s slots[] (Step 2) but 0-based in this created[] response. Slot sessionIndex: 1 corresponds to booking sessionIndex: 0 — don’t compare them directly without adjusting.
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

A PACKAGE 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:
A slate planned for another offering can’t be booked against this item. Plan the slate from the package the item was sold from, or from the credit itself (see Book the sessions left on a credit).
Behaviour change (October 2026). This call used to accept sessions of any offering and draw them from the credit. It now answers 400 ORDER_ITEM_SERVICE_MISMATCH, the same rule POST /bookings applies to single-session credits.

Book only what remains

Each service line uses one session of the credit. Asking for more sessions than quantityRemaining is refused up front, and nothing is booked:
The same code as a 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-slate with its orderId and orderItemId;
  • POST /orders/{orderId}/package-bookings;
  • POST /clients/me/orders/{orderId}/package-bookings;
  • POST /bookings with its orderId;
  • POST /holds/{reservationId}/convert with its orderId, even for a hold that already converted.
Each of them comes back with the same envelope:
Don’t retry. Create a new order for the client. 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 slateId or slotIds retry must arrive within the slate’s resolvableUntil window. After that it is refused as a stale slate, not replayed. Check whether the first call succeeded by reading the order’s bookings.
Behaviour change (October 2026). A same-key retry after the first call used the last credits used to answer 400 ORDER_ITEM_QUANTITY_UNAVAILABLE. It now replays the stored 201. A reused key with a different body that is also invalid used to get that body’s 400 or 404. It now gets 409 IDEMPOTENCY_KEY_CONFLICT.

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. Send orderId and orderItemId in place of packageId:
A credit plans differently from a package:
  • It plans the sessions that remain. The rrule’s COUNT is replaced by the item’s quantityRemaining. A package replaces it with its creditCount.
  • 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 (no lookAheadDays or endDate) and you ask for no relaxation, a credit that expires before its sessions fit is 422 NO_COMPLETE_SLATE, and reason names 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 generic NO_COMPLETE_SLATE.
  • It works after the package was edited or deleted. The order item keeps what it was sold with.
Send exactly one source: 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 a sessions[] 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 by slateId (or slotIds) 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 explicit intervals form makes you supply them.
Transcribing sessions is covered in depth in the availability and slates guide, along with building single one-off slots and full stale-slot recovery.
If you hold a slate, you must convert it — POST .../package-bookings will not consume your own hold and returns 409 SLOT_HELD naming the reservationId you created. See Concurrency.

Reference

Endpoints used in this guide

Configuration

Errors and edge cases

See Errors for the full envelope and code list.