Payment Status
How Storefront tracks what was paid, refunded, credited and still due on an order — the meta.payment summary, cash on delivery, refunds, store credit and payment links.
Payment Status
Every Storefront order carries one summary of its payment in meta.payment: how it was paid, what was taken, what has been refunded or credited since, and what is still due. The server keeps it current when the payment is captured, when cash is collected, when the order is edited and when it is canceled. The console's payment line, the Storefront app's receipt and Navigator's cash to collect all read it.
The payment summary
meta.payment is returned with the order by GET /v1/orders/{id} and in the customer's order history (GET /storefront/v1/customers/orders):
{
"state": "partially_refunded",
"gateway": "stripe",
"method_label": "Card (Stripe)",
"total": 2150,
"amount_paid": 2450,
"amount_refunded": 300,
"amount_credited": 0,
"balance_due": 0,
"cod_amount": 0,
"currency": "USD",
"payment_link": null,
"store_credit_code": null,
"supports_partial_refund": true,
"adjustments": [
{ "type": "refund", "amount": 300, "gateway": "stripe", "reference": "re_3Q…", "reason": "Fries 2→1", "at": "2026-10-13T12:04:11+00:00" }
]
}Amounts are integers in the currency's minor unit (cents for USD).
| Field | Meaning |
|---|---|
state | One of the states below |
gateway, method_label | How the order was paid, e.g. stripe / Card (Stripe), qpay / QPay, cash / Cash on delivery |
total | The order's current total |
amount_paid | What was taken: the amount charged at checkout (plus any balance collected later), or for cash on delivery what the driver collected |
amount_refunded, amount_credited | Money returned as refunds and as store credit |
balance_due | Still owed after an edit raised the total of an order paid online |
cod_amount | The cash the driver collects |
payment_link | The link sent for a balance due, when one was created |
store_credit_code | The latest store credit code given for this order |
supports_partial_refund | Whether the gateway can refund part of a payment (Stripe can; QPay refunds whole payments) |
adjustments | Every change after checkout: type (refund, store_credit, charge, cod_update), amount, gateway, reference (refund id or credit code), reason, at |
Orders placed before Storefront v0.4.25 have no meta.payment until something changes their payment; apps should fall back to meta.gateway and the payload's cod_amount.
Payment states
| State | Meaning |
|---|---|
paid | Paid in full; nothing to collect |
to_collect | Cash on delivery not yet collected |
unpaid | Placed in the console as not paid yet |
balance_due | An edit raised the total and the difference hasn't been paid |
partially_refunded | Part of the payment was refunded or given as store credit |
refunded | Everything that was paid has been refunded |
Cash on delivery
A cash on delivery order is recorded as unpaid when it is placed: its transaction is pending with settlement status unpaid, and the payment state is to_collect. When the order is completed, the transaction is settled for the amount collected and the state becomes paid. Console orders placed as not paid yet are recorded the same way.
If an edit changes the total before the cash is collected, the cash to collect changes with it, and the driver sees the new amount.
Refunds
Refunds go back through the gateway that took the payment:
| Gateway | Refunds |
|---|---|
| Stripe | Any amount, as a partial refund of the PaymentIntent |
| QPay | Whole payments only: a refund is possible when everything that remains is refunded, for example when the order is canceled. Smaller amounts are given as store credit. |
| Others | Not supported; the money is given as store credit |
Store credit
Store credit is a single-use, fixed-amount promo code (CREDIT-XXXXXXXX) that only this customer can use, at the same store, for one year. It is created as a private promotion named Store credit for followed by the order's tracking number. The code is sent to the customer in the order_updated or order_canceled notification and shown on their receipt.
Balance due and payment links
When an edit raises the total of an order paid online, the difference becomes a balance due. Either the customer is sent a payment link — a Stripe Payment Link or a QPay invoice for the balance — or the driver collects it in cash, in which case the balance is recorded as paid when the order is completed.
When the customer pays through the link, the balance is recorded as paid by itself: QPay calls back GET|POST /storefront/v1/orders/balance-paid?order={public_id} when its invoice is paid, Stripe Payment Links are checked every five minutes by the scheduled storefront:check-balance-payments command, and the console's Check payment checks right away. Each confirms the payment with the gateway (the callback's body is never trusted), adds a charge adjustment, closes the link and sends the customer the order_balance_paid receipt.
In the Storefront app
The Storefront App shows a payment badge on the order, the receipt and the order history (Paid, To pay on delivery, Refunded, Partly refunded, Balance due), lists refunds, credits and cash still to collect, shows the store credit code, and offers Pay now when there is a payment link.
Order Messages
Message customers and drivers about an order from the Storefront console, live, with quick replies for orders and bookings, and handle wrong-address requests — plus the order chat API for customer apps.
Bookings
Sell bookable services in free time slots — set a booking's length and how many can book the same slot, book from the console, and read slots from the API in your app.