Skip to main content
An order is created at checkout, but its life doesn’t end there. It gets paid, or not. Items change. Sessions are booked from it. Sometimes the whole thing is called off. This guide walks through what you can do to an order after it’s placed, and what the API does on its own. For the order object, its fields and every route, see Orders. For how an order is created and paid in the first place, see Client checkout, end to end.
The public API sends no webhooks. When something changes an order after your request returns, such as a card payment settling or a cancel cascade finishing, you find out by reading it again. See Tracking state without webhooks.

The four statuses

DRAFT and PENDING behave the same everywhere in the API: both take payments, both fund bookings, and both can be cancelled. Use PENDING only if your own flow needs to tell the two apart.

Move an order between statuses

POST /v1/projects/{projectId}/orders/{orderId}/status allows only these moves:
  • DRAFT → PENDING or CANCELLED
  • PENDING → DRAFT or CANCELLED
  • PAID → CANCELLED
  • CANCELLED → nothing
The 200 returns the order. Any other move, including a move to the status the order already has, is a 400:
409 VERSION_CONFLICT means the order changed while the server was applying your request, for example because a payment settled it. Read it again and decide again. See Concurrency. You can’t ask for PAID. An order becomes PAID in the same write that records the money that covers its total: Asking for PAID on the status route is a 409, and retrying won’t help:
To mark an order paid without taking money, record a comp for what it owes. A PAID order takes no more card payments. POST /orders/{orderId}/payment-intent on one is a 400, Order ord_… is PAID; cannot take payment.

An unpaid order still books

Payment doesn’t gate booking. A DRAFT or PENDING order funds bookings with your API key just as a PAID one does:
  • POST /bookings with a SINGLE_SESSION item.
  • POST /orders/{orderId}/package-bookings with a PACKAGE item.
  • POST /holds/{reservationId}/convert with either.
So booking before payment is your choice. If you book first, keep polling the order and decide what happens to one that never reaches PAID. See Tracking state without webhooks. A signed-in client is the exception. A client books their own package credits on the client plane only once the order is PAID. Until then the credit isn’t listed, and booking it is 409 CREDIT_NOT_BOOKABLE. See Book a client’s package credit. Only CANCELLED stops booking. Every booking route answers a cancelled order with a 409. The one exception is a retry of a package booking that succeeded before the cancel, with the same idempotencyKey: it replays the original result.

Change the items

Change an order’s items before any money is recorded against it. The item routes don’t check the order’s status, and they don’t settle the order. Only a payment or comp recording does, or MarketBox’s nightly reconciliation:
  • On a PAID order, the total changes but the status stays PAID, and amountPaid no longer matches.
  • On a part-paid order, removing an item can bring the total down to what’s already paid. The order stays unsettled until the next payment or comp, or the nightly reconciliation. A card can’t finish it: POST .../orders/{orderId}/payment-intent refuses an order with nothing left to pay, 400, Nothing is owed on this order: it is already paid or comped in full.
Each item route returns the whole order with its new totals.

Add an item

POST .../orders/{orderId}/items adds a single-session line. The server prices it from the offering, against the region the order was created with:
Add PACKAGE lines only when you create the order. The add route takes no packageId, so it can’t build a package line. Sending skuType: "PACKAGE" here is refused before anything is written:
To sell another package, create a new order with the PACKAGE line in items. See Selling a package. A service with no active rate for the line is 422 SERVICE_NOT_SOLD_AS. A service that isn’t LIVE, or an offering that isn’t ACTIVE, is 422 NOT_SELLABLE. See Creating an order.

Change a quantity

PATCH .../orders/{orderId}/items/{orderItemId} with { "quantity": 2 } changes the quantity only. The unit price stays as it was when the line was added. To re-price a line, remove it and add it again. Don’t change a PACKAGE line’s quantity. On a package line, quantity is the number of sessions, and the PATCH re-prices the line as unitPrice × quantity. For a package sold at a flat price, that total is wrong. Lowering it below the sessions already booked is accepted too: the bookings stay, and quantityRemaining becomes 0.

Remove an item

DELETE .../orders/{orderId}/items/{orderItemId} removes the line. Removing a PACKAGE line doesn’t cancel the bookings already made from it. Check GET .../orders/{orderId}/package-bookings?orderItemId=… first, and keep the bookingIds: once the line is removed, that read is a 404. Cancel the bookings if they should go too. See Cancel or reschedule a booking.

Cancel an order

Cancel an order the client genuinely called off. Send cancellationReason:
The reason is required. Without it, nothing is cancelled:
The order stores the reason as cancellationReason, and the user id of the account your key belongs to as cancelledBy. Cancelling doesn’t refund. Money already recorded stays on the ledger, and amountPaid doesn’t change. Refunds are made in the MarketBox dashboard. A cancelled order takes no new money: recording a payment or comp on it is 422 ORDER_NOT_PAYABLE. The public API has no refund route. Cancelling is final. No route reopens a CANCELLED order. To sell again, create a new order.

The bookings follow, a few seconds later

The status call returns as soon as the order is CANCELLED. Its bookings are cancelled afterwards, by a cascade that usually finishes within seconds:
  • It cancels SCHEDULED and STARTED bookings whose end hasn’t passed, and returns their package sessions to the order item.
  • It leaves bookings that already happened alone: AWAITING_CONFIRMATION, DISPUTED and settled ones.
  • It emails the client once, listing every cancelled session, and each supplier once, listing theirs.
So a booking you read straight after the call can still say SCHEDULED. To confirm the cascade finished, read each booking the order funded, a few seconds apart. For a package line, GET .../orders/{orderId}/package-bookings?orderItemId=… lists its bookings, one line per call. See A cancelled order’s bookings. To cancel one session and keep the order, cancel the booking instead. See Cancel a booking.

Cancel or delete

Delete refuses a real order. An order is real once it holds a booking, booked or already delivered, or any PENDING or SUCCEEDED transaction: a payment, a refund, a comp or an adjustment. Deleting one is a 409, and nothing changes:
Don’t retry it. Cancel the order instead. A card payment the client started counts: opening the payment page writes a PENDING payment, so an order abandoned there can’t be deleted. Cancel it. An order that never reached payment and booked nothing can be deleted. See Abandoned checkout.

Reference

Endpoints used in this guide

Errors and edge cases