Skip to main content
Not every client pays by card through your site. Some pay cash at the door, some by bank transfer, and sometimes the business waives a charge. This guide records that money in MarketBox, so the order shows what was paid and settles to PAID when it’s covered. Card payments don’t belong here. They go through Stripe: see Accept payments with Stripe. For the transaction object, every kind and source, and the full list of refusals, see Transactions.
Both routes in this guide take the x-api-key header alone. Call them from your server or the business’s own tools, never from a client’s browser.

How it works

  1. Read the order. Check its status, its currency and what it still owes.
  2. Record the money. POST /orders/{orderId}/transactions with a kind, a source, the amount and an idempotencyKey.
  3. Check the result. 201 is a new recording, 200 is a replay of one you already made. When the ledger covers the order’s total, the order is PAID.
  4. Reconcile later. GET /transactions reads the ledger back.

Step 1: Read the order

GET /v1/projects/{projectId}/orders/{orderId} returns the figures you need: What the order still owes is total.amount - amountPaid.amount - (amountComped?.amount ?? 0). For a total of 9000 with 4500 paid, the balance is 4500, which is $45.00. A CANCELLED order takes no payment or comp. The recording is a 422, and nothing is written:
A PAID order isn’t checked. A payment on it is recorded, and amountPaid rises past total. Nothing in the API can give that money back: refunds are made in the MarketBox dashboard. So read the order first, and refuse to take money against one that’s already settled.

Step 2: Record the money

Pick the kind and source from what happened:
  • amount.amount is in minor units. 4500 is $45.00.
  • amount.currency must be the order’s currency. An order’s currency never changes, and the route doesn’t convert.
  • note is free text for the business’s team, up to 500 characters.
  • clientId is optional. Leave it out to use the order’s client.
The row is written SUCCEEDED at once. There is nothing to poll.

Send an idempotency key

A cash recording is the request you least want to make twice. Make an idempotencyKey (a UUID is fine) when someone presses Record, store it with the payment on your side, and send the same key on every retry.
  • The first call records the money and 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.
Show “recorded” on either. Count the money only on a 201: a 200 is money you already counted. A replay returns the original row as it was. The server doesn’t compare bodies, so a retry with the same key and a different amount still returns the first amount. A retry must still be a valid request, though: the body, the order, the currency and any clientId are checked before the key, so a retry that fails one of those gets the 400 or 404, not the replay. Use a new key for a new payment, and never reuse one across two payments on the same order.

Waive what’s left with a comp

To waive a balance, record an ADJUSTMENT with source: COMP for the amount still owed, with a reason:
It raises amountComped, not amountPaid, so reports keep money waived apart from money received. Comp last. A card checkout charges total minus amountPaid, and ignores amountComped. So if you comp part of an order and then send the client to pay by card, they’re charged for the comped part too. Take the card payment first, then comp what’s left. Record why the charge was waived, not that it was: the row already says that. A comp with no reason is refused, and nothing is recorded:
A reason of only spaces is a 400 BAD_REQUEST, A COMP transaction needs a reason. Two other rows are accepted but rarely what you want:
  • PAYMENT with source: COMP counts toward amountPaid, as if the waived money were received. It needs a reason too, like every comp. Use ADJUSTMENT instead, so your cash figures stay true.
  • ADJUSTMENT with CASH or EXTERNAL is a note in the ledger. It doesn’t move the balance or settle the order.

Step 3: Check the result

The order becomes PAID

When amountPaid plus amountComped covers total, a DRAFT or PENDING order becomes PAID in the same write as the recording. Two fields are stamped on it then:
  • paymentMethod: CASH, EXTERNAL or COMP, or MIXED when more than one source paid.
  • settledAt: when the recording that completed it was made.
The response is the transaction, not the order. To show the new status, read the order. In the rare case the read still shows the old status, read once more a moment later. A recording that doesn’t cover the balance is a part payment. The order keeps its status until a later payment or comp covers it, so you can take a deposit now and the rest at the session. An ADJUSTMENT with CASH or EXTERNAL never settles an order. You can’t ask for PAID yourself. POST /orders/{orderId}/status with PAID is 409 ORDER_NOT_SETTLED. See Order lifecycle after checkout.

What PAID unlocks

  • A signed-in client’s package credits. A client can see and book a package only once its order is PAID. See Book a client’s package credit. So when a client pays cash for a package, record it before they try to book.
  • Nothing else. Single bookings, and package bookings made with your API key, don’t wait for PAID. See Order lifecycle after checkout.

A recorded order can’t be deleted

Once an order holds any recorded transaction, including a comp or an adjustment, DELETE /orders/{orderId} refuses it with 409 ORDER_NOT_DELETABLE. Cancel it instead. See Cancel or delete.

When a recording is refused

Nothing is recorded on any of these. The currency doesn’t match the order’s:
Send the order’s currency. If the client paid in another currency, convert it on your side and say so in note. The order changed while the payment was being recorded:
Retry with the same idempotencyKey. The key makes sure the retry can’t record twice. 409 TRANSACTION_IDEMPOTENCY_RECORD_MISSING is the exception. The key was used, but its row can’t be read back. It’s terminal: retrying can never succeed. Don’t retry, and don’t record the payment again under a new key. Read the order’s ledger (see Reconcile the ledger) and contact support with the requestId. The rest are in Refusals.

A recording was wrong

The ledger is append-only. No route edits or deletes a row, and kind: REFUND is refused. To correct a mistake:
  • Too little recorded: record the difference as another payment.
  • Too much recorded, or the wrong order: refund or correct it in the MarketBox dashboard. The public API has no refund route.

Reconcile the ledger

GET /v1/projects/{projectId}/transactions reads the ledger, newest first. It takes one of orderId, clientId or status, with an optional startDate and endDate. The three filters don’t combine. Only one takes effect, in the order orderId, clientId, status, and the rest are ignored without an error. So orderId with status=SUCCEEDED returns every row on the order. Send one filter, and filter the rest on your side. To total a day’s cash and transfers, list by status=SUCCEEDED for the day, then count by source on your side:
  • startDate is inclusive and endDate is exclusive. Pass the next day’s start as endDate. Both are UTC instants, so turn the business’s local midnight into one first.
  • Send both with milliseconds, as .000Z. The bounds are compared with each row’s timestamp as text, so …T05:00:00Z lands up to a second off.
  • Page with cursor until nextCursor is null. A page can hold fewer than limit rows before the end, so never stop on a short page. See Pagination.
Then sum by source:
  • Count only SUCCEEDED rows. A PENDING Stripe row is a payment started, not money received. When you list by orderId or clientId, every status comes back.
  • Leave out ADJUSTMENT rows. An ADJUSTMENT with source: COMP is money waived. Report it apart from what you collected.
  • Leave out CREDIT_REDEMPTION and CREDIT_REVERSAL. They track package sessions, not money.
  • Report a PAYMENT with source: COMP apart from CASH, even though it counts as paid.
For “which orders were settled in cash last month”, GET /orders?paymentMethod=CASH is quicker, but it misses MIXED orders and orders not yet PAID. A cash order you later cancelled still appears, with status: "CANCELLED". See Summing the ledger.

Reference

Endpoints used in this guide

Errors and edge cases