amountPaid, amountComped, paymentMethod,
settledAt and PAID status are all worked out from its rows. See
Settling an order.
Money reaches the ledger two ways:
- Cards go through Stripe.
POST .../orders/{orderId}/payment-intentwrites aPENDINGrow, and Stripe’s confirmation to MarketBox settles it. See Accept payments with Stripe. - Cash, bank transfers and comps are recorded by you, with
POST .../orders/{orderId}/transactions. See Recording a transaction, and for the task end to end, Record offline payments.
relatedTransactionId.
Anatomy of a transaction
Kinds
Package sessions actually used are redemptions minus reversals. Treat the list
of kinds as open: switch on
kind with a default branch.
Recording a transaction
POST /v1/projects/{projectId}/orders/{orderId}/transactions records money
that moved outside Stripe:
kindisPAYMENTorADJUSTMENT.REFUNDis refused.sourceisCASH,EXTERNALorCOMP.STRIPEis refused: card rows come only from the payment-intent flow.amount.currencymust be the order’s currency.clientIdis optional. It must be a client in this project.
SUCCEEDED at once. There is no pending state to poll.
What each row does to the order
When
amountPaid plus amountComped covers the order’s total, a DRAFT or
PENDING order becomes PAID in the same write. paymentMethod and
settledAt are stamped on it then. You can’t ask for PAID directly. See
Settling an order.
To waive what an order still owes, record an ADJUSTMENT with source: COMP
for the balance. It counts as comped, not paid.
A CANCELLED order takes no new money. A PAYMENT, or an ADJUSTMENT with
source: COMP, on a cancelled order is a 422 ORDER_NOT_PAYABLE, and nothing
is written:
ADJUSTMENT with source: CASH or EXTERNAL is still recorded on a
cancelled order, because it doesn’t move the balance.
A PAID order isn’t checked. A payment on it is recorded, and amountPaid
rises past total. Read the order before you take money against it.
A comp needs a reason
A row withsource: COMP needs reason, 1–500 characters. Record why the
charge was waived, such as "Service recovery — late supplier". Without one,
the row is refused:
Send an idempotency key
SendidempotencyKey on any recording you might retry. It’s up to 128
characters.
- A first recording returns
201, withreplayed: false. - The same key on the same order returns the row the first call made, as
200withreplayed: true. Nothing is recorded again.
replayed. Never treat any 2xx as “I just
took a payment”. A key belongs to one order and doesn’t expire: the same key
on another order records a new row.
Refusals
Listing transactions
GET /v1/projects/{projectId}/transactions reads the ledger, newest first.
orderId, clientId and status don’t combine. Only one of them takes
effect, in that order, and the others are ignored without an error. So
orderId with status=FAILED returns every row on the order, failed or not.
To narrow by more than one, filter on your side.
startDate is inclusive and endDate is exclusive. Send both bounds as full
ISO-8601 instants, such as 2026-10-01T00:00:00.000Z, and use the next
period’s start as endDate.
Page with cursor until nextCursor is null. A page can hold fewer rows
than limit before the end, so never stop on a short page. A cursor belongs
to the filters that made it: start again when you change them. See
Pagination.
Summing the ledger
Both settled and unsettled rows come back. Count onlystatus: "SUCCEEDED" rows: a PENDING Stripe row is a payment started, not
money received.
To work out what was collected, add the SUCCEEDED PAYMENT rows and
subtract the SUCCEEDED REFUND rows, per source. Leave out:
ADJUSTMENTrows withsource: COMP: money waived, not collected.- Other
ADJUSTMENTrows, such as tips migrated from MarketBox v1, unless you report tips. CREDIT_REDEMPTIONandCREDIT_REVERSALrows, which aren’t money.
PAYMENT with source: COMP is also a waiver, recorded as paid. Report it
apart from cash.
GET /orders?paymentMethod=CASH with startSettledAt and endSettledAt lists
orders settled wholly in cash. It misses cash on an order settled from more
than one source, which is MIXED, and on an order not yet PAID. For every
cash row, read the ledger. See Listing orders.
Endpoint index
POST /v1/projects/{projectId}/orders/{orderId}/transactionsGET /v1/projects/{projectId}/transactionsPOST /v1/projects/{projectId}/orders/{orderId}/payment-intent— see Accept payments with Stripe