Skip to main content
An order in MarketBox is the commerce ledger sitting alongside the booking ledger. It records what a client is paying for: line items referencing offerings, with frozen unit prices and a tax field. Where a booking answers “what’s scheduled?”, an order answers “what’s owed?”. This page is the reference. For what you do with an order once it’s placed, see Order lifecycle after checkout. To record cash, transfers and comps, see Record offline payments.

The order lifecycle

POST /v1/projects/{projectId}/orders/{orderId}/status moves an order along the single arrows:
  • DRAFT → PENDING, CANCELLED
  • PENDING → DRAFT, CANCELLED
  • PAID → CANCELLED
  • CANCELLED → nothing. Cancellation is terminal, so issue a new order instead.
Send cancellationReason with CANCELLED. It is required: without it the request is a 400 VALIDATION_ERROR and the order is not cancelled.
Cancelling an order cancels its remaining sessions and releases their credits. That cascade runs asynchronously, shortly after the status change returns, so a booking read straight afterwards can still show 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:
A 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:
Cancel it with 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 unitPrice and a quantity.
Fetch both in one call:

Currency is set once

When you create an order, you commit to a single currency. The currency is immutable thereafter — there is no PATCH 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:
This rule eliminates the order/item currency desync that plagues most naive commerce schemas. 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:
You can also create an order with 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 LIVE and not deleted, and its offering is ACTIVE. Otherwise the order is a 422 NOT_SELLABLE, and nothing is written. The same check runs on POST .../orders/{orderId}/items.
  • Every PACKAGE line names an ACTIVE package. A DRAFT or ARCHIVED package is a 422 PACKAGE_NOT_ACTIVE.
  • Every offering’s currency equals the order’s currency (else 400).
  • clientId belongs to this project. A client from another project is a 404 NOT_FOUND, and nothing is written.
  • The service is sold the way the line implies. A SINGLE_SESSION line needs an active SINGLE_BOOKING rate on the service; a PACKAGE line needs an active PACKAGE or SCHEDULED_PACKAGE rate. Otherwise the order is refused with a 422. The same check runs on POST .../orders/{orderId}/items:
Previously such a line was written with no rate attached, and so priced without the rate’s fees. Activate the rate in the MarketBox console, or sell the service another way. A line for a service that isn’t LIVE is refused like this. The message names what stopped the sale:
The other messages are:
  • Service srv_… was deleted and is no longer sold
  • Offering off_… is INACTIVE and is not sold; only ACTIVE offerings take new bookings and orders
Publish the service, or set the offering 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:
Orders already placed for the package keep their sessions, and stay bookable. Each item carries 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

Send attribution to record which search and site session the purchase came from:
  • searchId — the searchId of 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, assistant or other.
It is optional, stored as given, and readable on the order. It is copied onto every booking the order funds, so you can’t set it on a booking, a hold or a package booking directly. A 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. unitPrice is derived from the offering and snapshotted. It takes no packageId, so add PACKAGE lines when you create the order.
  • PATCH .../orders/{orderId}/items/{orderItemId} — change quantity only. skuType, serviceId, offeringId, and the frozen unitPrice are immutable.
  • DELETE .../orders/{orderId}/items/{orderItemId} — remove the item from the order. Removing a PACKAGE line doesn’t retract the bookings already made from it. Check GET .../orders/{orderId}/package-bookings before you remove one.
The snapshot pattern is deliberate: an order is a historical record of “what the client bought at the price it was when they bought it.”

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:
The same 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’s amountPaid, 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.
A recording that covers the balance moves the order to 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" requires reason, 1–500 characters. Record why the charge was waived, such as "Service recovery — late supplier". A comp with no reason is a 400.
  • Send idempotencyKey on any recording you might retry. A first recording returns 201 with replayed: false. The same key on the same order returns the row the first call created, as 200 with replayed: true, and records nothing. Branch on the status or on replayed, never on “any 2xx means I just took a payment”. A key belongs to one order and does not expire.
A 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:
Each of these is a 400:
  • Sending both status and paymentMethod.
  • Sending startSettledAt or endSettledAt without paymentMethod.
  • Sending startCreatedAt or endCreatedAt with paymentMethod.
  • Replaying a cursor after switching listing mode. A cursor belongs to the filters that produced it, so start a fresh request instead.
The no-filter mode is incomplete for older orders. It reads an index that is written only when an order is created. Orders created before this listing mode shipped, and orders migrated from MarketBox v1, are missing from it until a backfill runs. An empty or short result there does not mean the project has no orders. List by status when you need every historical order.

Endpoint index

  • POST /v1/projects/{projectId}/orders
  • GET /v1/projects/{projectId}/orders
  • GET /v1/projects/{projectId}/orders/{orderId}
  • GET /v1/projects/{projectId}/orders/{orderId}/aggregate
  • PATCH /v1/projects/{projectId}/orders/{orderId}
  • POST /v1/projects/{projectId}/orders/{orderId}/status
  • DELETE /v1/projects/{projectId}/orders/{orderId}
  • GET /v1/projects/{projectId}/clients/{clientId}/orders
  • POST /v1/projects/{projectId}/orders/{orderId}/items
  • PATCH /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 booking
  • GET /v1/projects/{projectId}/orders/{orderId}/package-bookings
  • POST /v1/projects/{projectId}/orders/{orderId}/transactions — see Transactions
  • GET /v1/projects/{projectId}/transactions — see Transactions
  • POST /v1/projects/{projectId}/orders/{orderId}/payment-intent — see Accept payments with Stripe