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→PENDINGorCANCELLEDPENDING→DRAFTorCANCELLEDPAID→CANCELLEDCANCELLED→ nothing
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.
PAID comes from the ledger
You can’t ask for PAID. An order becomes PAID in the same write that
records the money that covers its total:
- A card payment settles when Stripe tells MarketBox, usually a second or two after the client confirms. See Accept payments with Stripe.
- Cash, a bank transfer or a comp settles when you record it. See Record offline payments.
PAID on the status route is a 409, and retrying won’t help:
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. ADRAFT or PENDING order funds bookings
with your API key just as a PAID one does:
POST /bookingswith aSINGLE_SESSIONitem.POST /orders/{orderId}/package-bookingswith aPACKAGEitem.POST /holds/{reservationId}/convertwith either.
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
PAIDorder, the total changes but the status staysPAID, andamountPaidno 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-intentrefuses an order with nothing left to pay,400,Nothing is owed on this order: it is already paid or comped in full.
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:
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:
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. SendcancellationReason:
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 isCANCELLED. Its bookings are
cancelled afterwards, by a cascade that usually finishes within seconds:
- It cancels
SCHEDULEDandSTARTEDbookings whose end hasn’t passed, and returns their package sessions to the order item. - It leaves bookings that already happened alone:
AWAITING_CONFIRMATION,DISPUTEDand settled ones. - It emails the client once, listing every cancelled session, and each supplier once, listing theirs.
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:
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.