Selling cash on delivery
Returns and cash
Parcels coming back and checking them in to stock, the cash couriers owe for delivered orders, and their payouts.
Returns
When a courier sends a parcel back, the order becomes returned and a return appears in GET /v1/returns. Stock doesn't move yet: the units are neither on the shelf nor sold until the box is opened.
stage | Means |
|---|---|
in_transit | On its way back. ready: true once the courier has it waiting to be picked up. |
received | Back in your hands: the courier reported the hand-back, or you said so. |
An exchange's collected items show up too (kind: "exchange", with the original_order_id it replaced).
- It arrived.
POST /v1/returns/{order_id}/receive, for couriers that don't report the hand-back themselves. - Check it in.
POST /v1/returns/check_insays what happened to each item:
{ "returns": [
{ "order_id": "ord_…", "lines": [ { "id": "li_…", "restock": 1, "write_off": 1, "reason": "damaged" } ] },
{ "order_id": "ord_…" },
{ "order_id": "ord_…", "all_as": "damaged" }
] }Without lines, every open item goes back to stock (or, with all_as: "damaged", is written off). A write-off needs a reason: damaged, missing, used, wrong_item or other. Restocked units appear in the stock history as order_returned. Up to 200 returns per call, all or nothing.
After the check-in, couriers that ask for it (the Ecotrack family) are told the parcels reached you, as the dashboard does. courier in the answer reports what they said; a courier that doesn't answer never undoes the check-in.
An order is never set to returned by hand: the courier decides it, exactly as in the dashboard.
Cash on delivery
The courier collects the cash and pays the store later. GET /v1/cod_balances shows, per courier, what it owes for delivered orders it hasn't paid for yet (outstanding) and what its payouts brought (paid, with the difference between what was received and what was expected). GET /v1/cod_orders?courier=yalidine lists those unpaid delivered orders, oldest first.
Payouts
When the courier pays, record it:
curl https://api.ordexs.com/v1/payouts \
-H "Authorization: Bearer $ORDEXS_KEY" \
-H "Content-Type: application/json" \
-d '{"courier":"yalidine","amount_received":"158400.00","reference":"VIR-2026-1012"}'Without order_ids, the payout covers every delivered order of that courier not paid for yet; with them, only those (each must be one). expected is their total and difference what the courier kept back or added. GET /v1/payouts/{id}/orders lists what a payout covered; deleting a payout puts its orders back to awaiting payment. Recording payouts needs the money:write scope.
