Skip to main content
A transaction is one row in a project’s money ledger. Each row belongs to one order. An order’s amountPaid, amountComped, paymentMethod, settledAt and PAID status are all worked out from its rows. See Settling an order. Money reaches the ledger two ways: The ledger is append-only. A row is never edited. A correction is a new row that points at the one it corrects through 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:
  • kind is PAYMENT or ADJUSTMENT. REFUND is refused.
  • source is CASH, EXTERNAL or COMP. STRIPE is refused: card rows come only from the payment-intent flow.
  • amount.currency must be the order’s currency.
  • clientId is optional. It must be a client in this project.
The row is written 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:
An 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 with source: 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

Send idempotencyKey on any recording you might retry. It’s up to 128 characters.
  • A first recording returns 201, with replayed: false.
  • The same key on the same order returns the row the first call made, as 200 with replayed: true. Nothing is recorded again.
Branch on the status code or on 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 only status: "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:
  • ADJUSTMENT rows with source: COMP: money waived, not collected.
  • Other ADJUSTMENT rows, such as tips migrated from MarketBox v1, unless you report tips.
  • CREDIT_REDEMPTION and CREDIT_REVERSAL rows, which aren’t money.
A 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}/transactions
  • GET /v1/projects/{projectId}/transactions
  • POST /v1/projects/{projectId}/orders/{orderId}/payment-intent — see Accept payments with Stripe