> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The booking engine model

> How orders, bookings, slates, and credits fit together in MarketBox.

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.

```mermaid theme={null}
flowchart LR
    A[Order] --> B[Order item]
    B --> C[Booking]
    B -.->|package: N sessions| D[Booking]
    B -.->|package: N sessions| E[Booking]
```

For a single session, one order item funds exactly one booking. For a
package, one order item funds many bookings — see below.

> [!NOTE]
>
> 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](#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.

```json theme={null}
// POST /orders response (abridged) — the PACKAGE item after creation
{
  "items": [
    {
      "orderItemId": "oi_01k...",
      "skuType": "PACKAGE",
      "quantity": 8,
      "quantityRemaining": 8,
      "expiresAt": "2026-10-06T00:00:00.000Z"
    }
  ]
}
```

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.

> [!TIP]
>
> 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:

```mermaid theme={null}
flowchart LR
    A["POST /availability/package-slate<br/>→ slateId"] --> B["POST /orders/{orderId}/package-bookings<br/>{ slateId }<br/>→ N bookings"]
```

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.

> [!NOTE]
>
> 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.)

> [!WARNING]
>
> 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](https://docs.gomarketbox.com/guides/availability-and-slates.md)
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](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md) 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](https://docs.gomarketbox.com/resources/services.md#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](https://docs.gomarketbox.com/guides/book-a-package-credit.md)) 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.

> [!NOTE]
>
> 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](https://docs.gomarketbox.com/guides/accept-payments-with-stripe.md) 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}`.

```json theme={null}
{
  "supplier": {
    "canCancelBookings": false,
    "cancelNoticeHours": 24,
    "canRescheduleBookings": true,
    "rescheduleNoticeHours": 24,
    "canSeeClientLastName": true,
    "canSeeClientEmail": false,
    "canSeeClientPhone": false
  },
  "client": {
    "canRescheduleBookings": true,
    "rescheduleNoticeHours": 24,
    "participantDisplay": "FULL"
  }
}
```

| Field | What it controls |
| - | - |
| `supplier.canCancelBookings`, `supplier.cancelNoticeHours` | Whether suppliers may cancel their upcoming bookings, and until how many hours before the start. `0` means any time before the start. |
| `supplier.canRescheduleBookings`, `supplier.rescheduleNoticeHours` | The same, for moving a booking to another time with the same supplier. |
| `supplier.canSeeClientLastName` | When `false`, suppliers see the client's first name and last initial only. |
| `supplier.canSeeClientEmail`, `supplier.canSeeClientPhone` | Whether suppliers see the client's email and phone. |
| `client.canRescheduleBookings`, `client.rescheduleNoticeHours` | Whether clients may move their own upcoming sessions. Clients can't cancel. |
| `client.participantDisplay` | How other participants are named to clients on their own bookings: `FULL`, `FIRST_NAME` or `HIDDEN` (a count only). |

**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](https://docs.gomarketbox.com/guides/supplier-portal-bookings.md#cancel-and-reschedule),
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

> [card] [Create a single booking](https://docs.gomarketbox.com/guides/create-a-single-booking.md)
>
> Walk through the single-session flow end to end: order, order item, booking.

> [card] [Create a package booking](https://docs.gomarketbox.com/guides/create-a-package-booking.md)
>
> Build a package order item and draw it down across multiple sessions.

> [card] [Availability and slates](https://docs.gomarketbox.com/guides/availability-and-slates.md)
>
> Search single slots, build package slates, and handle stale-slot retries.

> [card] [Booking addresses](https://docs.gomarketbox.com/guides/booking-addresses.md)
>
> When a structured address is required and how it's threaded through bookings and slates.

> [card] [Services and offerings](https://docs.gomarketbox.com/resources/services.md)
>
> The catalog a booking is made from: services, business models and offerings.

> [card] [Packages](https://docs.gomarketbox.com/resources/packages.md)
>
> Prepaid sessions of one offering, and what stops them being sold or booked.

> [card] [Holds](https://docs.gomarketbox.com/resources/holds.md)
>
> Reserved supplier time: place, extend, convert and release.

> [card] [Transactions](https://docs.gomarketbox.com/resources/transactions.md)
>
> The money ledger behind every order, and how a row settles it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.