Skip to main content
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.
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. status on every booking response is one of nine values: 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. 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.
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:
409 VERSION_CONFLICT means the booking changed underneath you — re-read it and decide again. See Errors.

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

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:
cancellationReason is required with CANCELLED. Leave it out and nothing is cancelled:
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. 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: 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:
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:

Services

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

Participants

The clients attending. Used for group/class-style bookings with capacity above 1. Supports check-in.

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:
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 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.
  • 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 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:
Each service line’s order item is checked before anything is written. The first line that fails decides the error: 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: See Concurrency for the conflicts[] shape. The booking’s location and price are checked in the same write:
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.
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.

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: 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:
A supplier can also cancel or move their own booking from your portal, when the service’s 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. 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: All three accept the same query params: startDate, endDate, status, limit, cursor. startDate / endDate are UTC windows. See Timezones 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.

Notes

Notes are attached at one of two scopes: 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 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 and Collect reviews and show ratings
  • GET /v1/projects/{projectId}/bookings/{bookingId}/reviews