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

# Orders

> Build and manage orders — the commerce primitive for tracking what a client owes.

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](https://docs.gomarketbox.com/guides/order-lifecycle-after-checkout.md).
To record cash, transfers and comps, see
[Record offline payments](https://docs.gomarketbox.com/guides/record-offline-payments.md).

## The order lifecycle

```
DRAFT ◄──► PENDING ══► PAID
  │           │          │
  └───────────┴──────────┴──► CANCELLED
```

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

```json theme={null}
{
  "status": "CANCELLED",
  "cancellationReason": "Client changed their mind before the first session"
}
```

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](https://docs.gomarketbox.com/guides/create-a-package-booking.md#a-cancelled-order-books-nothing).

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](#settling-an-order). Asking for `PAID` is a `409`, and
retrying will not help:

```json theme={null}
{
  "code": "ORDER_NOT_SETTLED",
  "message": "Order ord_01kx16f2a0h8a2my9u3f4tv0sp cannot be marked PAID by hand. Record a payment (or a comp) instead; the order becomes PAID when the ledger covers its total.",
  "statusCode": 409,
  "requestId": "0f3b8d2e-6a1c-4e97-b5d4-8c2a7e9f1b36"
}
```

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:

```json theme={null}
{
  "code": "ORDER_NOT_DELETABLE",
  "message": "Order ord_01kx16f2a0h8a2my9u3f4tv0sp has 2 booking(s) and 1 payment or refund record(s) against it, so it cannot be deleted. Cancel it instead (status CANCELLED).",
  "statusCode": 409,
  "requestId": "4c9e2a7b-1d3f-4b86-a0e5-7f2c8d1b6e93"
}
```

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](https://docs.gomarketbox.com/guides/client-checkout-end-to-end.md#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:

```
GET /v1/projects/{projectId}/orders/{orderId}/aggregate
```

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

```json theme={null}
{
  "code": "BAD_REQUEST",
  "message": "Item off_xxx currency EUR does not match order currency USD",
  "statusCode": 400,
  "requestId": "c8e4a1f6-3d9b-4c58-a207-9e5c1b7d4a68"
}
```

This rule eliminates the order/item currency desync that plagues most
naive commerce schemas.

`locale` follows the same rule: set at create, immutable thereafter.

> [!NOTE]
>
> 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](https://docs.gomarketbox.com/concepts/regional-pricing.md).

## 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](https://docs.gomarketbox.com/concepts/regional-pricing.md):

```json theme={null}
{
  "clientId": "cli_456",
  "currency": "USD",
  "locale": "en-US",
  "locationId": "loc_01kx16f2a0h8a2my9u3f4tv0sp",
  "items": [
    {
      "skuType": "SINGLE_SESSION",
      "serviceId":  "srv_...",
      "offeringId": "off_...",
      "quantity": 1
    }
  ]
}
```

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](https://docs.gomarketbox.com/resources/packages.md#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](https://docs.gomarketbox.com/concepts/emails.md#where-the-rating-links-go).

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

```json theme={null}
{
  "code": "SERVICE_NOT_SOLD_AS",
  "message": "Service srv_01kv60qg12e82acr78edfnjhvv is not sold as a single booking; it has no active SINGLE_BOOKING rate",
  "statusCode": 422,
  "requestId": "7c1e4b9a-2d53-4f08-a6e1-3b9d0c5f2a71"
}
```

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:

```json theme={null}
{
  "code": "NOT_SELLABLE",
  "message": "Service srv_01kv60qg12e82acr78edfnjhvv is INACTIVE and is not sold; only LIVE services take new bookings and orders",
  "statusCode": 422,
  "requestId": "2d9f6a13-8b4e-4c07-9e51-6f3a2b8c1d40"
}
```

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:

```json theme={null}
{
  "code": "PACKAGE_NOT_ACTIVE",
  "message": "Package pkg_01kv61b3x8m2q4r6t8v0w2y4z6 is ARCHIVED and cannot accept new orders",
  "statusCode": 422,
  "requestId": "8e4c1b7a-3f92-4d65-a0b8-5c2e9d1f7a36"
}
```

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:

```json theme={null}
{
  "clientId": "cli_456",
  "currency": "USD",
  "attribution": {
    "searchId": "<searchId from the search response>",
    "sessionKey": "sess-4f9a2c",
    "surface": "results"
  }
}
```

* `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](https://docs.gomarketbox.com/guides/report-site-events.md#tie-a-purchase-to-its-search).

## 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`:

| Value | Meaning |
| - | - |
| `NO_RATE` | Neither the matched price rule, its parent rules, nor the service set a rate. |
| `NOT_TAXABLE` | The resolved tax settings mark the line not taxable. |
| `ZERO_RATE` | Taxable at 0%. |
| `MIGRATED_V1` | Imported from MarketBox v1, which recorded tax on the order rather than per line. |
| `PACKAGE_EXEMPT_LEGACY` | A package line written while package purchases were untaxed (June–September 2026). |

`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](https://docs.gomarketbox.com/concepts/service-fees.md) 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:

```json theme={null}
{
  "code": "TAX_MISMATCH",
  "message": "tax 2000 CAD disagrees with order ord_01kv8m3n5p7q9r1s3t5v7w9x1z: its lines compute 2600 CAD and it stores 2600 CAD. Omit tax — the platform computes it from the line items.",
  "statusCode": 400,
  "requestId": "5b8e2d41-7c9a-4f13-b6e0-9a2c4d7f1e38"
}
```

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](https://docs.gomarketbox.com/guides/accept-payments-with-stripe.md).
* **Cash, bank transfers and comps** are recorded with
  `POST /v1/projects/{projectId}/orders/{orderId}/transactions`.

```json theme={null}
{
  "kind": "PAYMENT",
  "source": "CASH",
  "amount": { "amount": 4500, "currency": "CAD" },
  "idempotencyKey": "9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b"
}
```

A recording that covers the balance moves the order to `PAID` in the same
write, and stamps two fields on it:

| Field | Meaning |
| - | - |
| `paymentMethod` | How the order was settled: `STRIPE`, `CASH`, `EXTERNAL`, `COMP`, `MIXED` (more than one source contributed), or `LEGACY` (migrated from MarketBox v1 with no settling ledger rows). Absent until the order is `PAID`. |
| `settledAt` | The instant the money that completed the order was recorded — your "cash received" date. |

`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](https://docs.gomarketbox.com/resources/transactions.md#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](https://docs.gomarketbox.com/resources/transactions.md).

## Listing orders

| Endpoint | Notes |
| - | - |
| `GET /v1/projects/{projectId}/orders` | One of three listing modes, chosen by the filter you send. |
| `GET /v1/projects/{projectId}/clients/{clientId}/orders` | All orders for one client (any status). |

`GET /v1/projects/{projectId}/orders` answers exactly one question per request:

| Send | Lists | Narrow with |
| - | - | - |
| `status` | Orders in that status. | `startCreatedAt`, `endCreatedAt` |
| `paymentMethod` | Settled orders, by how they were paid. `DRAFT` and `PENDING` orders never appear. A settled order you later cancelled still appears, refunded or not, with `status: "CANCELLED"`. This is the reconciliation read: "what did we take in cash last month?" | `startSettledAt`, `endSettledAt` |
| Neither | Every order. | `startCreatedAt`, `endCreatedAt` |

Start bounds are inclusive. End bounds are **exclusive**, so pass the next
period's start to cover a whole month:

```bash theme={null}
curl "$MARKETBOX_API_URL/v1/projects/$MARKETBOX_PROJECT_ID/orders?paymentMethod=CASH&startSettledAt=2026-09-01T00:00:00.000Z&endSettledAt=2026-10-01T00:00:00.000Z" \
  -H "x-api-key: $MARKETBOX_API_KEY"
```

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.

> [!WARNING]
>
> **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](https://docs.gomarketbox.com/guides/create-a-package-booking.md)
* `GET  /v1/projects/{projectId}/orders/{orderId}/package-bookings`
* `POST /v1/projects/{projectId}/orders/{orderId}/transactions` — see [Transactions](https://docs.gomarketbox.com/resources/transactions.md)
* `GET  /v1/projects/{projectId}/transactions` — see [Transactions](https://docs.gomarketbox.com/resources/transactions.md)
* `POST /v1/projects/{projectId}/orders/{orderId}/payment-intent` — see [Accept payments with Stripe](https://docs.gomarketbox.com/guides/accept-payments-with-stripe.md)


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