> ## 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.

# Bookings

> Create, manage, and operate on bookings — the core scheduling primitive.

A **booking** is the central scheduling primitive in MarketBox. It pins
a `supplier` and a `client` to a window of time, against one or more
service offerings, with optional notes and participants.

## The booking lifecycle

A booking is created as `SCHEDULED` and settles into one of the four outcomes
on the bottom row. After the session ends, it waits in
`AWAITING_CONFIRMATION` until someone settles it. Nothing moves a booking to
`COMPLETED` on its own: no timer or confirmation window completes it. If
your suppliers don't file attendance reports, set `COMPLETED` yourself once
the booking reads `AWAITING_CONFIRMATION`, or it stays there.

```
SCHEDULED ──► STARTED ──► AWAITING_CONFIRMATION ──► DISPUTED
    │  │          │              ▲      │               │
    │  └──────────┼──────────────┘      │               │
    ▼             ▼                     ▼               ▼
 COMPLETED · CLIENT_NO_SHOW · SUPPLIER_NO_SHOW · CANCELLED
    │             │                 │
    └─────────────┴─────────────────┴──► AWAITING_CONFIRMATION (operator reversal)

 COMPLETED ──► DISPUTED (the client reports they didn't attend, within 24 hours)
```

Each state on the top row can reach each outcome on the bottom row, except that
a `SCHEDULED` booking reaches `COMPLETED` only through the supplier's own
attendance report. A `SCHEDULED` booking that ends without being started moves
straight to `AWAITING_CONFIRMATION`.

**`COMPLETED` isn't final for 24 hours.** A client who reports that they didn't
attend within 24 hours of the booking becoming `COMPLETED` moves it to
`DISPUTED`, whoever completed it. Don't treat a booking as settled until that
window has passed. See [Attendance and disputes](#attendance-and-disputes).

`status` on every booking response is one of nine values:

| Status | Meaning | Who puts a booking here |
| - | - | - |
| `SCHEDULED` | Created, not yet started. The only start state. | Booking creation. Nothing transitions *into* it. |
| `STARTED` | The session is under way. | Your key, once `bookingStartUtc` has passed. The supplier plane has no route that sets it. |
| `AWAITING_CONFIRMATION` | The session has ended and the booking is waiting to be settled. It stays here until the supplier reports attendance, or your key or an operator sets an outcome. | The platform, in an hourly sweep after `bookingEndUtc` passes, so up to about an hour later. See [Tracking state without webhooks](https://docs.gomarketbox.com/concepts/tracking-state-without-webhooks.md#a-session-ends). An operator can also reverse a settled booking back here within a window. |
| `DISPUTED` | The client reported that they didn't attend, and the booking was otherwise going to be (or had just been) `COMPLETED`. | The platform, when an attendance report is filed. See [Attendance and disputes](#attendance-and-disputes). Resolved by an operator in the MarketBox console. |
| `COMPLETED` | Delivered. | A `SUPPLIER` attendance report that says they attended, filed by the supplier or by your key, or a status change by your key. Nothing completes a booking automatically. A client can still dispute it for 24 hours. |
| `CLIENT_NO_SHOW` | The client did not attend. | Your key, after a grace period past the start. No attendance report sets it: a report says only whether its own side attended. |
| `SUPPLIER_NO_SHOW` | The supplier did not attend. | A `SUPPLIER` attendance report that says they did not attend, filed by the supplier or by your key, or a status change by your key after the same grace period. |
| `CANCELLED` | Called off. **Hard-terminal**: money may have moved, so nothing leaves this state. | The supplier, through the [supplier plane](https://docs.gomarketbox.com/guides/build-a-supplier-portal.md), only while the booking is `SCHEDULED` and before `bookingEndUtc`. Your key, also from `STARTED`, but only before `bookingEndUtc`. An operator, also from `AWAITING_CONFIRMATION` and `DISPUTED`. Your key can't cancel a session that has taken place: settle it instead. |
| `NO_SHOW` | **Legacy, read-only.** The pre-split no-show, which does not say which side was absent. Nothing transitions out of it. | Nothing, any more. Bookings recorded before the split keep it indefinitely. |

You move a booking with
`POST /v1/projects/{projectId}/bookings/{bookingId}/status`. The request
body's `status` enum is narrower than the response's: `SCHEDULED` and
`DISPUTED` can be observed but never requested, so they are not in it.
`AWAITING_CONFIRMATION` is in the enum because an operator can request it, but
your key cannot: sending it is always a `400`.

The supplier's own attendance report is filed through the
[supplier plane](https://docs.gomarketbox.com/guides/supplier-portal-bookings.md#bookings-and-the-attendance-report).
You can also file a report with your key, through
`POST /v1/projects/{projectId}/bookings/{bookingId}/reports`. It does exactly
what the same answer does in the MarketBox dashboard. A `SUPPLIER` report
settles the booking, and a `CLIENT` report can open a dispute. See
[Attendance and disputes](#attendance-and-disputes).

> [!NOTE]
>
> **What an API key may do.** A key carries every transition an operator
> has, except the ones that need a human to decide between two accounts of
> what happened: it cannot resolve a `DISPUTED` booking, and it cannot
> reverse a settled booking (`COMPLETED`, `CLIENT_NO_SHOW`,
> `SUPPLIER_NO_SHOW`) back to `AWAITING_CONFIRMATION`. Both are reserved for
> the MarketBox console. It also cannot cancel an `AWAITING_CONFIRMATION`
> booking. The session has taken place, and cancelling it would void the
> supplier's claim to be paid. Settle it instead, with `COMPLETED` or a
> no-show. Which transitions are open also depends on the
> clock — a booking cannot be started before `bookingStartUtc`, or marked a
> no-show until a grace period after it.

A transition the booking cannot make from where it stands is a
`400 BAD_REQUEST` whose `message` names the booking's **current** status, so a
rejection tells you what to retry from:

```json theme={null}
{
  "code": "BAD_REQUEST",
  "message": "Cannot transition booking status from AWAITING_CONFIRMATION to CANCELLED",
  "statusCode": 400,
  "requestId": "8c2f5a1e-4d7b-4e93-a6c0-1b9e3f7d2a58"
}
```

`409 VERSION_CONFLICT` means the
booking changed underneath you — re-read it and decide again. See
[Errors](https://docs.gomarketbox.com/concepts/errors.md).

### Attendance and disputes

Each side of a booking files at most one attendance report, saying whether
**that side** attended. The supplier's report settles the booking. The client's
report never settles it, but it can open a dispute. MarketBox decides when a
report is filed. No job settles bookings later.

| Situation | Result |
| - | - |
| The supplier reports `attended: true`, and no client report says `attended: false` | `COMPLETED` |
| The supplier reports `attended: true`, and a client report already says `attended: false` | `DISPUTED` |
| The supplier reports `attended: false` | `SUPPLIER_NO_SHOW`, whatever the client said |
| The client reports `attended: false` before the supplier has reported | Recorded. The booking waits for the supplier. |
| The client reports `attended: false` within 24 hours of the booking becoming `COMPLETED` | `DISPUTED`, whoever completed it: the supplier's report, an operator or your key |
| The client reports `attended: false` more than 24 hours after `COMPLETED` | Recorded only |
| The client reports `attended: true` | Recorded only |
| Nobody reports | Stays `AWAITING_CONFIRMATION` |

The 24 hours run from the instant the booking became `COMPLETED`, which is its
`statusUpdatedAt` while it is `COMPLETED`. An operator resolves a `DISPUTED`
booking in the MarketBox console. Your key can't.

A report you file with your key follows the same table. It's a report from
the side named in `reporterRole`, exactly as if that side had filed it in
MarketBox. You can file one only once the session has ended. Otherwise you get
`422 BOOKING_NOT_REPORTABLE`, and nothing is written:

| When | `message` |
| - | - |
| The session hasn't ended | "This booking cannot be reported on until its session has ended" |
| The booking is `CANCELLED` | "A cancelled booking cannot be reported on" |
| A `SUPPLIER` report on a booking that's already settled | "This booking is already settled, so a supplier report can no longer change it" |

```json theme={null}
{
  "code": "BOOKING_NOT_REPORTABLE",
  "message": "This booking cannot be reported on until its session has ended",
  "statusCode": 422,
  "requestId": "4a9d2e7c-1f36-4b85-9e0a-7c3b5d1f8e26"
}
```

A `CLIENT` report on a settled booking is recorded. It changes nothing unless
it opens a dispute.

To let suppliers file their report from your own portal, see
[Supplier day view and attendance reports](https://docs.gomarketbox.com/guides/supplier-day-view-and-reporting.md#after-the-booking-ends).

### `NO_SHOW` can no longer be set

Send `CLIENT_NO_SHOW` or `SUPPLIER_NO_SHOW` to record which side was absent.
Sending `NO_SHOW` is a `400` whose `message` names the value.

`NO_SHOW` is still a status a booking can **carry**. Bookings recorded before
the split keep it and are not being migrated, because nobody recorded which
party failed to show. If you switch exhaustively on `status`, keep a case for
it.

### Cancelling and the package credit

Send `status: "CANCELLED"` to cancel. In the same atomic write, MarketBox
releases the supplier's time and settles the order item the booking drew on.
What happens to the session depends on the order item:

| Booking drew on | Default outcome | `creditTreatment` |
| - | - | - |
| A `PACKAGE` order item, session still to come (`SCHEDULED`, `STARTED`) | `RETURN`. The session goes back to the order item: `quantityRemaining` rises and a `CREDIT_REVERSAL` transaction offsets the original `CREDIT_REDEMPTION`. | Send `"FORFEIT"` to keep the session spent, for example for a late cancellation. `"RETURN"` states the default explicitly. |
| A `PACKAGE` order item, session already taken place (`AWAITING_CONFIRMATION`, `DISPUTED`) | `FORFEIT`. The session stays spent. | Only an operator can cancel these, so this default applies to cancels made in the MarketBox console. Your key gets a `400`. |
| A `SINGLE_SESSION` order item | The allocation is closed. No quantity comes back, because a single session holds no reusable credit. | Don't send it. It is a `422 NO_SESSION_CREDIT`, and nothing is cancelled. |

```json theme={null}
{
  "status": "CANCELLED",
  "cancellationReason": "Client called the morning of the session",
  "creditTreatment": "FORFEIT"
}
```

`cancellationReason` is required with `CANCELLED`. Leave it out and nothing is
cancelled:

```json theme={null}
{
  "code": "VALIDATION_ERROR",
  "message": "cancellationReason: cancellationReason is required when status is CANCELLED",
  "statusCode": 400,
  "requestId": "3e7a1c5d-9b24-4f68-8d0e-6a2f4c9b1e57"
}
```

`creditTreatment` is only valid with `CANCELLED`. The status route never moves
money: a forfeited session is not refunded, and a returned one is not charged
again.

For the whole flow, including reschedule, delete and the checks your server
must make for a client, see
[Cancel or reschedule a booking](https://docs.gomarketbox.com/guides/cancel-or-reschedule-a-booking.md).

The cancellation email to the client reports what happened to their session
credit. It does not include your `cancellationReason` text, which stays on the
booking.

Every booking response now carries the cancellation record, when there is one:

| Field | Meaning |
| - | - |
| `creditTreatment` | What was decided about the session credit: `RETURN`, `FORFEIT`, `REFUND_ORIGINAL_PAYMENT`, or `NOT_APPLICABLE` (the booking held no package credit). Absent on bookings cancelled before this field existed. |
| `cancellationInitiatedBy` | `CLIENT`, `SUPPLIER` or `BUSINESS`, when the cancellation recorded it. |
| `cancellationReasonCode` | A reportable reason, such as `WEATHER` or `BOOKED_IN_ERROR`, when the cancellation recorded one. |

`REFUND_ORIGINAL_PAYMENT`, `cancellationInitiatedBy` and
`cancellationReasonCode` are set by cancellations made in the MarketBox
console. You can read them, but the public API does not set them.

Every booking also records who last moved it. `statusUpdatedAt` is the
instant, `statusUpdatedBy` is the actor, and `statusUpdatedByCapacity` is one
of `ADMIN`, `SUPPLIER`, `CLIENT`, `SYSTEM` or `API`. A change made through
the public API is attributed to the **API key** that made it, in the `API`
capacity — the key is what gets rotated or revoked, so "which key did this"
is the question an incident asks.

A booking is **soft-deleted** with
`DELETE /v1/projects/{projectId}/bookings/{bookingId}`. Soft-deleted
bookings disappear from list endpoints but their data is retained for
audit purposes. Reserve delete for bookings created in error; cancel a booking
that was genuinely called off.

A delete is a cancel first. It settles the booking exactly like a default
cancel: it releases the supplier's time, returns a package session to its
order item, and closes a single-session allocation.

You can delete only a booking your key could cancel through `/status`. A
booking that has taken place or been settled (`AWAITING_CONFIRMATION`,
`COMPLETED`, a no-show) is refused, and nothing changes:

```json theme={null}
{
  "code": "BOOKING_NOT_DELETABLE",
  "message": "Booking bk_01kv60qge5eh59ap0gw0pqrrys is COMPLETED and cannot be cancelled in this capacity now, so it cannot be deleted",
  "statusCode": 422,
  "requestId": "6f1b8d3a-2c94-4e57-b0a6-9d4e2f7c1b35"
}
```

Deleting a booking that is already `CANCELLED` leaves that cancel's settlement
as it stands. It sends no second cancellation email.

## Anatomy

A booking has three nested collections beyond its own metadata:

> [card] Services
>
> The offerings booked — each line carries the offering snapshot,
> quantity, duration, and price at the time the booking was made.

> [card] Participants
>
> The clients attending. Used for group/class-style bookings with
> capacity above 1. Supports check-in.

> [card] Notes
>
> Free-form notes scoped to either the booking or one of its
> services. Soft-deletable.

Fetch all three in one call with the **aggregate** endpoint:

```
GET /v1/projects/{projectId}/bookings/{bookingId}/aggregate
```

This is the right call for "show me everything about this booking" —
one round trip instead of five. Beside `booking`, `services`, `participants`
and `notes`, it returns:

* **`reports`** — the attendance reports filed on the booking, at most one per
  side.
* **`parties`** — `client` and `supplier`, each with its id and a best-effort
  `fullName`. `supplier` is `null` when no supplier is assigned. No email
  address is returned for either party. This is the only public way to turn a
  `clientId` into a name.

A booking funded by an order that carried
[`attribution`](https://docs.gomarketbox.com/resources/orders#attribution) carries a copy of it:
the `searchId`, `sessionKey` and `surface` of the purchase. It is read-only on
the booking.

## Creating a booking

`POST /v1/projects/{projectId}/bookings` creates a booking and its
services in one transaction. Every booking draws on an order item, so create
the order first. The body carries:

* **`clientId`** — who is served. Required.
* **`supplierId`** — who serves. Optional: omit it to create an unassigned
  booking.
* **`bookingStartUtc`**, **`bookingEndUtc`**, **`bookingTz`** — when. Required.
  Local-time fields are derived. See [Timezones](https://docs.gomarketbox.com/concepts/timezones.md).
* **`locationType`** — `VIRTUAL`, `PHYSICAL` or `TRAVEL_ZONE`. Required, and it
  decides the other location fields. `PHYSICAL` needs `locationId`.
  `TRAVEL_ZONE` needs `locationId` (the `stz_` travel zone), `latitude`,
  `longitude` and `address`. `VIRTUAL` takes none of them.
* **`capacity`** — how many participants this booking can hold (1 for
  one-to-one bookings; >1 for classes). Defaults to 1.
* **`services`** — at least one service line. Each line requires
  `serviceId`, `offeringId`, `businessModelType`, `orderId` and
  `orderItemId`; `quantity` defaults to 1. Price and duration are pulled from
  the offering at create time and **snapshotted** into the booking.
* **`notes`** — optional initial notes.

See [the quickstart](https://docs.gomarketbox.com/quickstart.md#3-create-a-booking) for a complete request.

The server validates:

* `bookingEndUtc > bookingStartUtc`.
* Every referenced offering exists (otherwise `404`) and is `ACTIVE`
  (otherwise `422 NOT_SELLABLE`). The service's own status isn't re-checked:
  each line draws on an order item already bought, so it stays bookable when
  its service stops being `LIVE`.
* All service lines share a single currency (otherwise 400).
* `bookingTz` is a valid IANA identifier.
* `clientId` and `supplierId` belong to this project. An id from another
  project is a `404 NOT_FOUND`, exactly as if it did not exist, and nothing is
  written. The same check applies to `supplierId` on `PATCH`, to `clientId` on
  `POST .../participants`, and to the ids on order create, package bookings,
  holds and manual transactions.
* A line that draws on an order item names a `businessModelType` that item is
  sold as: a `SINGLE_SESSION` item books as `SINGLE_BOOKING`, a `PACKAGE` item
  as `PACKAGE` or `SCHEDULED_PACKAGE`. Anything else is a
  `400 ORDER_ITEM_BUSINESS_MODEL_MISMATCH`:

```json theme={null}
{
  "code": "ORDER_ITEM_BUSINESS_MODEL_MISMATCH",
  "message": "Order item oi_01kx16f2a0h8a2my9u3f4tv0sp is a SINGLE_SESSION line and can only be booked as SINGLE_BOOKING, not PACKAGE",
  "statusCode": 400,
  "requestId": "5b0e6a2c-8f41-4d7e-9c3a-2e6d1f0b7a94"
}
```

Each service line's order item is checked before anything is written. The
first line that fails decides the error:

| Status | `code` | Meaning |
| - | - | - |
| `400` | `INVALID_ORDER_REFERENCE` | `orderId` doesn't name an order in this project. |
| `409` | `ORDER_CANCELLED` | The order is `CANCELLED`. Its cascade already released its credits, so it books nothing. |
| `400` | `INVALID_ORDER_ITEM_REFERENCE` | `orderItemId` isn't an item on that order. |
| `400` | `ORDER_ITEM_SERVICE_MISMATCH` | The order item is for a different `serviceId` or `offeringId` than the line. |
| `400` | `ORDER_ITEM_QUANTITY_UNAVAILABLE` | The order item has fewer sessions left than the line's `quantity`. |
| `400` | `ORDER_ITEM_BUSINESS_MODEL_MISMATCH` | The line's `businessModelType` isn't one the order item is sold as (see above). |

The supplier's time is claimed in the same write as the booking. When it can't
be claimed, you get a `409` and nothing is written:

| `code` | Meaning | What to do |
| - | - | - |
| `SLOT_HELD` | A live hold covers the time. The body carries `conflicts[]` and a `hint` naming the hold. | Convert the hold with `POST .../holds/{reservationId}/convert`, or release it. This route never consumes a hold. |
| `SLOT_BOOKED` | The supplier already has a booking that overlaps. | Search availability again. |
| `OCCUPANCY_CONTENTION` | The supplier's calendar is under heavy concurrent writes. | Retry. |

See [Concurrency](https://docs.gomarketbox.com/concepts/concurrency.md#the-three-supplier-time-conflicts) for
the `conflicts[]` shape.

The booking's location and price are checked in the same write:

| Status | `code` | Meaning |
| - | - | - |
| `404` | `NOT_FOUND` | `locationId` names no Location or travel zone in this project, such as "Booking location loc\_01kx16f2a0h8a2my9u3f4tv0sp not found". |
| `400` | `BAD_REQUEST` | The location is the wrong type for `locationType`, or a travel zone of another supplier. `message` names it, such as "Location loc\_01kx16f2a0h8a2my9u3f4tv0sp has locationType TRAVEL\_ZONE, expected PHYSICAL for this booking". |
| `422` | `UNPROCESSABLE_ENTITY` | A `PHYSICAL` Location has no coordinates: "Location loc\_01kx16f2a0h8a2my9u3f4tv0sp is missing latitude/longitude coordinates". The business fixes the Location. Resending won't help. |
| `422` | `OFFERING_NOT_PRICED` | The offering has no `DEFAULT` price rule: "Offering has no DEFAULT price rule". The business adds one. Resending won't help. |
| `422` | `NOT_SELLABLE` | A line's offering isn't `ACTIVE`: "Offering off\_01kx16f2a0h8a2my9u3f4tv0sp is INACTIVE and is not sold; only ACTIVE offerings take new bookings and orders". The business reactivates it, or you book another offering. Resending won't help. |

> [!NOTE]
>
> **Note fan-out is non-atomic.** If a note write fails after the
> booking is created, the booking still exists with fewer notes than
> requested, and the error propagates to you. Retry the note creation
> against the existing `bookingId`.

> [!NOTE]
>
> **`locale` is derived, not sent.** A booking carries `locale`, the language
> the funding order was placed in, copied from the order at create time —
> through `POST /bookings`, `POST /orders/{orderId}/package-bookings` and hold
> conversion alike. It is a snapshot: a client who books in `fr-CA` and later in
> `en-US` keeps `fr-CA` on the first booking, so a review link mailed nine days
> later still lands on the right page. Absent when the order had none. Set it on
> the order — see [Orders](https://docs.gomarketbox.com/resources/orders.md#creating-an-order).

## Rescheduling

`PATCH /v1/projects/{projectId}/bookings/{bookingId}` updates time and
core fields. The body may include any subset of:

* `bookingStartUtc`, `bookingEndUtc`, `bookingTz`
* `supplierId`
* `latitude`, `longitude`, `address`
* `capacity`

You cannot send the four `bookingLocal*` fields or `locale` — they're
server-derived. You cannot change the client either: `clientId` is not a PATCH
field, so a `clientId` in the body is dropped and the booking keeps its client.

If you change any time field, the server recomputes all four local
fields against the (possibly new) `bookingTz`.

A change is refused, with nothing written, when:

| Status | `code` | Meaning |
| - | - | - |
| `409` | `VERSION_CONFLICT` | The booking changed since you read it. Re-read it and decide again. |
| `409` | `SLOT_HELD` / `SLOT_BOOKED` | The new time or supplier is taken. The body carries `conflicts[]` and `hint`, as on create. Offer another time. |
| `409` | `OCCUPANCY_CONTENTION` | The supplier's calendar is under heavy concurrent writes. Retry. |
| `404` | `NOT_FOUND` | The booking, the supplier or the location doesn't exist. |
| `400` | `BAD_REQUEST` | The booking can't take the location change, for example a travel zone of another supplier. |
| `422` | `BOOKING_NOT_AMENDABLE` | You changed the time or supplier of a booking that isn't `SCHEDULED` or `STARTED`. Its other fields can still be edited. |
| `422` | `UNPROCESSABLE_ENTITY` | The booking's `PHYSICAL` Location has no coordinates. |

Only a `SCHEDULED` or `STARTED` booking can move in time or change supplier.
Once it has been reported on, settled or cancelled, the move is refused:

```json theme={null}
{
  "code": "BOOKING_NOT_AMENDABLE",
  "message": "Booking bk_01kv60qge5eh59ap0gw0pqrrys is AWAITING_CONFIRMATION: only a scheduled or started booking can have its time, supplier or duration changed",
  "statusCode": 422,
  "requestId": "2d7e4b9a-6c13-4f80-a5e2-8b1c3d9f6a47"
}
```

A supplier can also cancel or move their own booking from your portal, when
the service's [participant settings](https://docs.gomarketbox.com/concepts/booking-engine-model.md#participant-settings)
allow it. Those changes come through the supplier plane, record the supplier as
the initiator, and email the client and the business. See
[Supplier portal: bookings](https://docs.gomarketbox.com/guides/supplier-portal-bookings.md#cancel-and-reschedule).
Your API-key calls act for the business, and participant settings don't
restrict them.

A booking whose length deliberately differs from its service's duration carries
`durationOverrideMinutes` and `durationOverrideReason`. Staff set them in the
MarketBox console, and `bookingEndUtc` already reflects the override. Absent is
the normal case: the booking runs as long as its service says.

## Listing bookings

Three list endpoints — all paginated, all returning `BookingDto`:

| Endpoint | Scope |
| - | - |
| `GET /v1/projects/{projectId}/bookings` | All bookings in a project. |
| `GET /v1/projects/{projectId}/suppliers/{supplierId}/bookings` | Bookings assigned to one supplier. |
| `GET /v1/projects/{projectId}/clients/{clientId}/bookings` | Bookings owned by one client. |

All three accept the same query params: `startDate`, `endDate`,
`status`, `limit`, `cursor`.

`startDate` / `endDate` are **UTC** windows. See
[Timezones](https://docs.gomarketbox.com/concepts/timezones.md) for how to convert from a local
window.

## Participants

Group bookings (`capacity > 1`) support a participant list:

* `POST .../bookings/{bookingId}/participants` — register a client.
  409 if capacity is full or the client is already on the list. Only a
  `SCHEDULED` or `STARTED` booking takes a registration: anything else is
  `422 BOOKING_NOT_OPEN_FOR_PARTICIPANTS`. A removed participant can be
  registered again.
* `GET .../bookings/{bookingId}/participants` — list the current
  roster. Not paginated — bounded by capacity.
* `POST .../bookings/{bookingId}/participants/{clientId}/check-in` —
  mark a participant as checked in. An `AWAITING_CONFIRMATION` booking still
  takes a check-in. A settled, disputed or cancelled one is
  `422 BOOKING_NOT_OPEN_FOR_PARTICIPANTS`.
* `DELETE .../bookings/{bookingId}/participants/{clientId}` — cancel
  the participant (soft-delete; capacity recovers).

The booking's own client is registered when it's created, and registering a
participant charges nothing. See
[Group bookings and check-in](https://docs.gomarketbox.com/guides/group-bookings-and-check-in.md).

## Notes

Notes are attached at one of two scopes:

| Scope | When to use |
| - | - |
| `BOOKING` | Applies to the whole booking. Omit `bookingServiceId`; `null` is a `400`. |
| `BOOKING_SERVICE` | Applies to one service line. Set `bookingServiceId: <id>`. |

CRUD lives under `.../bookings/{bookingId}/notes[/{noteId}]`. The list
is not paginated — it's bounded by what fits in the aggregate.

## Endpoint index

See the [API reference](https://docs.gomarketbox.com/api-reference/introduction.md) for full schemas
and a live playground for every endpoint:

* `POST /v1/projects/{projectId}/bookings`
* `GET  /v1/projects/{projectId}/bookings`
* `GET  /v1/projects/{projectId}/bookings/{bookingId}`
* `GET  /v1/projects/{projectId}/bookings/{bookingId}/aggregate`
* `PATCH /v1/projects/{projectId}/bookings/{bookingId}`
* `POST /v1/projects/{projectId}/bookings/{bookingId}/status`
* `DELETE /v1/projects/{projectId}/bookings/{bookingId}`
* `GET  /v1/projects/{projectId}/suppliers/{supplierId}/bookings`
* `GET  /v1/projects/{projectId}/clients/{clientId}/bookings`
* `POST /v1/projects/{projectId}/bookings/{bookingId}/participants`
* `GET  /v1/projects/{projectId}/bookings/{bookingId}/participants`
* `GET  /v1/projects/{projectId}/bookings/{bookingId}/participants/{clientId}`
* `POST /v1/projects/{projectId}/bookings/{bookingId}/participants/{clientId}/check-in`
* `DELETE /v1/projects/{projectId}/bookings/{bookingId}/participants/{clientId}`
* `POST /v1/projects/{projectId}/bookings/{bookingId}/notes`
* `GET  /v1/projects/{projectId}/bookings/{bookingId}/notes`
* `PATCH /v1/projects/{projectId}/bookings/{bookingId}/notes/{noteId}`
* `DELETE /v1/projects/{projectId}/bookings/{bookingId}/notes/{noteId}`
* `POST /v1/projects/{projectId}/bookings/{bookingId}/reports`
* `GET  /v1/projects/{projectId}/bookings/{bookingId}/reports`
* `POST /v1/projects/{projectId}/bookings/{bookingId}/reviews` — see [Reviews](https://docs.gomarketbox.com/resources/reviews.md) and [Collect reviews and show ratings](https://docs.gomarketbox.com/guides/collect-reviews-and-show-ratings.md)
* `GET  /v1/projects/{projectId}/bookings/{bookingId}/reviews`


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