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 asSCHEDULED 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 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.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:
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
Sendstatus: "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:
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.
booking, services, participants
and notes, it returns:
reports— the attendance reports filed on the booking, at most one per side.parties—clientandsupplier, each with its id and a best-effortfullName.supplierisnullwhen no supplier is assigned. No email address is returned for either party. This is the only public way to turn aclientIdinto a name.
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,PHYSICALorTRAVEL_ZONE. Required, and it decides the other location fields.PHYSICALneedslocationId.TRAVEL_ZONEneedslocationId(thestz_travel zone),latitude,longitudeandaddress.VIRTUALtakes 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 requiresserviceId,offeringId,businessModelType,orderIdandorderItemId;quantitydefaults to 1. Price and duration are pulled from the offering at create time and snapshotted into the booking.notes— optional initial notes.
bookingEndUtc > bookingStartUtc.- Every referenced offering exists (otherwise
404) and isACTIVE(otherwise422 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 beingLIVE. - All service lines share a single currency (otherwise 400).
bookingTzis a valid IANA identifier.clientIdandsupplierIdbelong to this project. An id from another project is a404 NOT_FOUND, exactly as if it did not exist, and nothing is written. The same check applies tosupplierIdonPATCH, toclientIdonPOST .../participants, and to the ids on order create, package bookings, holds and manual transactions.- A line that draws on an order item names a
businessModelTypethat item is sold as: aSINGLE_SESSIONitem books asSINGLE_BOOKING, aPACKAGEitem asPACKAGEorSCHEDULED_PACKAGE. Anything else is a400 ORDER_ITEM_BUSINESS_MODEL_MISMATCH:
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,bookingTzsupplierIdlatitude,longitude,addresscapacity
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:
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 returningBookingDto:
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 aSCHEDULEDorSTARTEDbooking takes a registration: anything else is422 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. AnAWAITING_CONFIRMATIONbooking still takes a check-in. A settled, disputed or cancelled one is422 BOOKING_NOT_OPEN_FOR_PARTICIPANTS.DELETE .../bookings/{bookingId}/participants/{clientId}— cancel the participant (soft-delete; capacity recovers).
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}/bookingsGET /v1/projects/{projectId}/bookingsGET /v1/projects/{projectId}/bookings/{bookingId}GET /v1/projects/{projectId}/bookings/{bookingId}/aggregatePATCH /v1/projects/{projectId}/bookings/{bookingId}POST /v1/projects/{projectId}/bookings/{bookingId}/statusDELETE /v1/projects/{projectId}/bookings/{bookingId}GET /v1/projects/{projectId}/suppliers/{supplierId}/bookingsGET /v1/projects/{projectId}/clients/{clientId}/bookingsPOST /v1/projects/{projectId}/bookings/{bookingId}/participantsGET /v1/projects/{projectId}/bookings/{bookingId}/participantsGET /v1/projects/{projectId}/bookings/{bookingId}/participants/{clientId}POST /v1/projects/{projectId}/bookings/{bookingId}/participants/{clientId}/check-inDELETE /v1/projects/{projectId}/bookings/{bookingId}/participants/{clientId}POST /v1/projects/{projectId}/bookings/{bookingId}/notesGET /v1/projects/{projectId}/bookings/{bookingId}/notesPATCH /v1/projects/{projectId}/bookings/{bookingId}/notes/{noteId}DELETE /v1/projects/{projectId}/bookings/{bookingId}/notes/{noteId}POST /v1/projects/{projectId}/bookings/{bookingId}/reportsGET /v1/projects/{projectId}/bookings/{bookingId}/reportsPOST /v1/projects/{projectId}/bookings/{bookingId}/reviews— see Reviews and Collect reviews and show ratingsGET /v1/projects/{projectId}/bookings/{bookingId}/reviews