The order lifecycle
POST /v1/projects/{projectId}/orders/{orderId}/status moves an order along
the single arrows:
DRAFT→PENDING,CANCELLEDPENDING→DRAFT,CANCELLEDPAID→CANCELLEDCANCELLED→ nothing. Cancellation is terminal, so issue a new order instead.
cancellationReason with CANCELLED. It is required: without it the
request is a 400 VALIDATION_ERROR and the order is not cancelled.
SCHEDULED. It
cancels only SCHEDULED and STARTED bookings. AWAITING_CONFIRMATION and
DISPUTED bookings have already happened, so the cascade leaves them alone,
as it does settled ones. The client gets one email listing every cancelled
session, and each affected supplier gets one listing their own.
A CANCELLED order’s credits can’t be planned or booked: every route that
draws them answers 409 ORDER_CANCELLED. See
Create a package booking.
Any other transition is a 400 BAD_REQUEST.
You cannot request PAID. An order becomes PAID (the double arrow) when
its ledger covers its total, in the same write that records the money. See
Settling an order. Asking for PAID is a 409, and
retrying will not help:
409 VERSION_CONFLICT from the same route still means the order changed
underneath you: re-read it and decide again.
DELETE /v1/projects/{projectId}/orders/{orderId} is a soft-delete —
the order is hidden from lists but its data is retained. Deleting an order
that isn’t already CANCELLED also sets its status to CANCELLED. Delete is
for orders raised in error; cancel an order that was genuinely called off.
Delete refuses a real order. An order is real once it holds a booking,
booked or already delivered, or a PENDING or SUCCEEDED payment or refund.
Deleting one is a 409, and nothing changes:
POST .../orders/{orderId}/status instead. An abandoned
checkout whose order books nothing and took no money can still be deleted.
See Abandoned checkout. A
booking that reaches the order between that check and the delete is
cancelled with it, and no one is emailed about it.
Anatomy
An order is two things stored together:- The order: client, currency, locale, tax, status, totals, audit metadata.
- The items: line-by-line, each referencing one offering with a
frozen
unitPriceand aquantity.
Currency is set once
When you create an order, you commit to a single currency. The currency is immutable thereafter — there is noPATCH that changes it.
Every item added to the order must match the order’s currency. The API
enforces this at add-item time and at create-time:
locale follows the same rule: set at create, immutable thereafter.
An item’s
unitPrice is resolved from the offering’s (or package’s)
regional price rules against the order’s region, not from a single fixed
price — a mismatch here more often means the order didn’t resolve the
region you expected than that the price data is wrong. See
Regional pricing.Creating an order
POST /v1/projects/{projectId}/orders. Optionally pass one region source —
reservationId, locationId, or address — so items price against the
right regional rule instead of falling back to the client’s default address
or the DEFAULT rule; see Regional pricing:
items: [] and add items afterwards.
A PACKAGE line names the package instead: { "skuType": "PACKAGE", "packageId": "pkg_…" }. The server derives the service, offering, session
count, price and expiry from the package. See
Selling a package. Add PACKAGE lines here, at create:
POST .../orders/{orderId}/items takes no packageId.
Pass locale — the language the buyer completed the purchase in, typically the
language segment of your storefront URL — and MarketBox records it three times:
on the order, as a snapshot on every booking this order funds, and as the
client’s defaultLocale (latest booking wins). It is normalized to canonical
BCP-47 on write, so en-us is stored as en-US; a tag that is not
language[-Script][-REGION] is a 400 VALIDATION_ERROR. You do not send it on
POST /bookings — the booking copies it from the order. The recorded values
drive the {clientLocale} and {bookingLocale} tokens in your review-page
URL; see Emails.
The server pulls each offering’s current price into the item as the
frozen unitPrice. From then on, the line’s price is decoupled from
the offering — if the offering’s price changes later, existing order
items keep the price they were captured at.
The server validates:
- Every offering exists (else 404). A deleted offering counts as not found.
- Every line is sellable: its service is
LIVEand not deleted, and its offering isACTIVE. Otherwise the order is a422 NOT_SELLABLE, and nothing is written. The same check runs onPOST .../orders/{orderId}/items. - Every
PACKAGEline names anACTIVEpackage. ADRAFTorARCHIVEDpackage is a422 PACKAGE_NOT_ACTIVE. - Every offering’s currency equals the order’s currency (else 400).
clientIdbelongs to this project. A client from another project is a404 NOT_FOUND, and nothing is written.- The service is sold the way the line implies. A
SINGLE_SESSIONline needs an activeSINGLE_BOOKINGrate on the service; aPACKAGEline needs an activePACKAGEorSCHEDULED_PACKAGErate. Otherwise the order is refused with a422. The same check runs onPOST .../orders/{orderId}/items:
LIVE is refused like this. The message
names what stopped the sale:
Service srv_… was deleted and is no longer soldOffering off_… is INACTIVE and is not sold; only ACTIVE offerings take new bookings and orders
ACTIVE, then retry. Retiring a
service stops new sales only. Order items already bought stay bookable after
the service leaves LIVE, as long as their offering is still ACTIVE.
A PACKAGE line for a package that isn’t on sale is refused the same way:
priceSource. RULE means the unitPrice came from the
offering or package pricing rules (see priceRuleId). MANUAL means staff set
the price in the MarketBox console when they created the order, so
priceRuleId is null and unitPrice matches no rule. Items written before the
field existed have no priceSource.
Attribution
Sendattribution to record which search and site session the purchase came
from:
searchId— thesearchIdof the search response the client booked from.sessionKey— the opaque per-session key you send with site events, at most 64 characters. Never an email, IP address or user id.surface— where on your site the purchase started:home,results,listing,site_search,profile,widget,assistantorother.
searchId MarketBox never issued is kept but not
counted. See Report site events.
Managing items
Items have their own sub-resource under an order:POST .../orders/{orderId}/items— add an item.unitPriceis derived from the offering and snapshotted. It takes nopackageId, so addPACKAGElines when you create the order.PATCH .../orders/{orderId}/items/{orderItemId}— change quantity only.skuType,serviceId,offeringId, and the frozenunitPriceare immutable.DELETE .../orders/{orderId}/items/{orderItemId}— remove the item from the order. Removing aPACKAGEline doesn’t retract the bookings already made from it. CheckGET .../orders/{orderId}/package-bookingsbefore you remove one.
How tax is computed
The platform computes tax. You never send a rate or a tax amount. Each line takes its tax settings from the price rule it matched. When that rule sets no tax, the line inherits from the rule’s parents, most specific first:STATE, then COUNTRY, then DEFAULT. When no rule sets tax, the line uses
the service’s own taxSettings. The result is frozen on the line as
taxSnapshot.
PACKAGE lines are taxed by the same rule as every other line. Package lines
written between June and September 2026, while package purchases were
untaxed, keep their zero tax.
A line with no tax says why in taxExemptReason:
taxExemptReason is absent when the line is taxed at a positive rate. It is
also absent on lines written before the field existed. Treat the list as open:
new values can be added.
The order’s tax is the sum of its line tax plus the tax on any taxable service
fee. See Service fees for how a fee is taxed.
Updating an order
PATCH /v1/projects/{projectId}/orders/{orderId} changes nothing you can set.
Client, currency and locale are fixed. To change them, cancel the order and
create a new one. Change the line items to change the total.
tax is not editable. The platform recomputes it when the order is created and
whenever its lines change. The body still accepts tax for compatibility, but
only when it equals both the tax the lines compute and the tax the order
stores. Omit it.
Any other figure is refused, and nothing is written:
400 TAX_MISMATCH is returned when you send tax on an order whose
lines are in a different currency from the order. The message then names
both currencies.
On an order whose stored tax no longer matches its lines, no figure passes.
That is deliberate: rewriting tax on a paid order could drop its total below
what was already paid.
Settling an order
The ledger is the source of truth for money. An order’samountPaid,
amountComped, paymentMethod, settledAt and PAID status are all derived
from its transactions. An order moves from DRAFT or PENDING to PAID when
amountPaid plus amountComped covers total.
Money reaches the ledger in two ways:
- Cards go through the payment-intent flow and settle when Stripe’s webhook arrives. See Accept payments with Stripe.
- Cash, bank transfers and comps are recorded with
POST /v1/projects/{projectId}/orders/{orderId}/transactions.
PAID in the same
write, and stamps two fields on it:
amountComped totals the order’s ADJUSTMENT rows with source: COMP. A
PAYMENT row with source: COMP counts toward amountPaid instead. Treat
amountComped as zero when absent. See
What each row does to the order.
Two rules on the transaction body:
source: "COMP"requiresreason, 1–500 characters. Record why the charge was waived, such as"Service recovery — late supplier". A comp with no reason is a400.- Send
idempotencyKeyon any recording you might retry. A first recording returns201withreplayed: false. The same key on the same order returns the row the first call created, as200withreplayed: true, and records nothing. Branch on the status or onreplayed, never on “any 2xx means I just took a payment”. A key belongs to one order and does not expire.
409 TRANSACTION_IDEMPOTENCY_RECORD_MISSING means the key matched an earlier
recording whose row could not be read back. It is terminal. Do not retry it.
Re-read the order’s transactions and contact support with the requestId.
Every transaction also carries channel, the path that wrote it (OPEN_API
for your key, BACKOFFICE, STRIPE_WEBHOOK, and others), and reason. For
the transaction object, its kinds, and listing the ledger, see
Transactions.
Listing orders
GET /v1/projects/{projectId}/orders answers exactly one question per request:
Start bounds are inclusive. End bounds are exclusive, so pass the next
period’s start to cover a whole month:
400:
- Sending both
statusandpaymentMethod. - Sending
startSettledAtorendSettledAtwithoutpaymentMethod. - Sending
startCreatedAtorendCreatedAtwithpaymentMethod. - Replaying a
cursorafter switching listing mode. A cursor belongs to the filters that produced it, so start a fresh request instead.
Endpoint index
POST /v1/projects/{projectId}/ordersGET /v1/projects/{projectId}/ordersGET /v1/projects/{projectId}/orders/{orderId}GET /v1/projects/{projectId}/orders/{orderId}/aggregatePATCH /v1/projects/{projectId}/orders/{orderId}POST /v1/projects/{projectId}/orders/{orderId}/statusDELETE /v1/projects/{projectId}/orders/{orderId}GET /v1/projects/{projectId}/clients/{clientId}/ordersPOST /v1/projects/{projectId}/orders/{orderId}/itemsPATCH /v1/projects/{projectId}/orders/{orderId}/items/{orderItemId}DELETE /v1/projects/{projectId}/orders/{orderId}/items/{orderItemId}POST /v1/projects/{projectId}/orders/{orderId}/package-bookings— see Create a package bookingGET /v1/projects/{projectId}/orders/{orderId}/package-bookingsPOST /v1/projects/{projectId}/orders/{orderId}/transactions— see TransactionsGET /v1/projects/{projectId}/transactions— see TransactionsPOST /v1/projects/{projectId}/orders/{orderId}/payment-intent— see Accept payments with Stripe