Skip to main content
Before you call a single endpoint, it helps to hold one rule in your head: nothing is booked without an order item to draw down. Every booking in MarketBox — single or package — consumes credits from an order item that already exists. This page explains that model so the guides that follow (single bookings, package bookings, availability, addresses) make sense as variations on one idea, not four unrelated flows.

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 carries orderId 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 a SINGLE_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.
Book against a package with a single call to 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.
You create the PACKAGE order item the same way you create any order item: POST /orders { clientId, currency, items: [{ skuType: "PACKAGE", packageId }] }. The server derives the service, offering, session count, price, and expiry from the package definition — you only supply the packageId.

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:
  1. Build the slate. POST /availability/package-slate with the packageId, a location, and an rrule (e.g. every Mon/Wed/Fri, 8 sessions) returns a primarySlate with a slateId and the resolved slots[]. To plan what is left on a credit the client already owns, send its orderId and orderItemId instead of packageId.
  2. Book it by id. POST /orders/{orderId}/package-bookings with 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. idempotencyKey is 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.
You never have to copy times or locations out of the slate response by hand — sending the 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.)
Provide exactly one of sessions, slateId, or slotIds when booking a package — never a mix. And once you have a slate, book it (or the subset you want via slotIds) as-is; don’t re-derive the location yourself, since the slate already resolved it correctly.
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 still DRAFT 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 DRAFT order 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 status reads PAID. 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’s status first, 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 carries participantSettings: 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.