Selling cash on delivery
Orders and the COD flow
How a cash-on-delivery order moves from creation to the customer's door, and which steps your integration can take.
The life of an order
Most Ordexs orders are paid in cash when the parcel arrives. Between the order and the money, the merchant's team calls the customer to confirm, a courier picks the parcel up, and the courier reports back.
pending ──► confirmed ──► preparing ──► shipped ──► delivered
│ │ └──────► returned
│ └─► scheduled / attempt_1…3 / waiting / double
└──────────► cancelled| Status | Set by | Means |
|---|---|---|
pending | Ordexs | New, not yet confirmed with the customer. |
confirmed | The team or your integration | The customer confirmed: ready to send to a courier. |
scheduled | The team or your integration | Confirmed for a later date (scheduled_for). |
attempt_1, attempt_2, attempt_3 | The team or your integration | The customer didn't answer the first, second, third call. |
waiting | The team or your integration | On hold, for example waiting for stock. |
double | The team or your integration | A duplicate of another order. |
cancelled | The team or your integration | Won't be sent. |
preparing, shipped, delivered, returned, deleted | The courier | Set from the courier's tracking. Can't be set through the API. |
New statuses may be added. Treat one you don't know like pending.
Creating an order
POST /v1/orders creates an order exactly as the store's own checkout would. You send what was ordered and where it goes; the store does the rest:
- prices every line from the variant's current price (you never send a price);
- applies the
discount_codeand the offers inoffer_ids(up to 4), if any, after checking each one still qualifies (see Offers and discounts); - prices delivery from
delivery.mode(anddelivery.courier_id, if you chose one fromGET /v1/delivery/rates); - checks and reserves stock, and refuses with
out_of_stockif there isn't enough.details.linesnames each short line (line_item_index,variant_id,requested,available_quantity,preorder_possible), so you can offer the customer what is left; - gives it the next order number (
ORD-00042) and puts it in the merchant's Orders page.
shipping_address.region takes the region's code (16), its ISO code (DZ-16) or its name as a customer would write it (Alger, Algiers, الجزائر; one typo is tolerated). GET /v1/regions lists them. The order always stores the code.
Run the same body through POST /v1/orders/preview first to show the customer the exact total. A preview saves nothing, moves no stock and uses no number.
Orders you create carry source: "api" and your source_name, and the merchant sees them with an API badge. Set external_id to your own id so a retry can never create a second order (see Idempotency).
Order types
Besides a normal delivery, the dashboard's Create order makes three other kinds of order, and so does the API with type:
type | The courier… | Send |
|---|---|---|
delivery (default) | delivers line_items and collects the total | line_items |
exchange | delivers line_items and takes collect.lines back | line_items, collect, usually total (the price difference) |
pickup | only collects collect.lines from the customer | collect |
cash_collection | collects an amount, no goods | total |
An exchange can name what comes back from an earlier, delivered order (collect.original_order_id and each line's line_item_id), so the returned goods are tracked against it and can go back into stock when they arrive. Or describe them freely, like line_items.
{
"type": "exchange",
"customer": { "name": "Yacine Benali", "phone": "0551234567" },
"shipping_address": { "region": "16", "city": "Bab El Oued", "address1": "12 rue Ali Boumendjel" },
"delivery": { "mode": "home" },
"line_items": [{ "variant_id": "var_…", "quantity": 1 }],
"collect": {
"original_order_id": "ord_…",
"lines": [{ "line_item_id": "li_…", "quantity": 1 }]
},
"total": "0"
}The order carries its type, the order it exchanges (exchange_of) and what is collected (collect).
Prices set by hand
By default the store prices every line, applies its offers and discount codes, and prices delivery. Like the dashboard's Create order, you can also:
- add a custom line that isn't in the catalogue:
{ "title": "Gift wrap", "quantity": 1, "unit_price": "200.00" }; - set a catalogue line's price with
unit_price; - set the delivery fee with
shipping_feeand what the courier collects withtotal.
An order with any of these is priced exactly as you send it: offers and discount codes don't apply (discount_code is refused). Without total, the total is the lines plus delivery.
Changing the lines
PATCH /v1/orders/{id} with line_items replaces the order's lines, like Edit items on the order card. Stock follows: removed units come back, and added units must be available (or coming, for a pre-order), else out_of_stock. The total is recalculated unless you also send total; shipping_fee changes the delivery fee. On an order already with a courier, see below.
Pre-orders
When the shelf is empty but a delivery is on its way to the merchant, send "preorder": true. Like the dashboard's Pre-order switch, each line may then take units from the variant's incoming delivery (up to what is coming), and the order is marked preorder: true so the team knows to wait for the goods. Products the merchant set to allow pre-orders take them even without the flag. Without either, an empty shelf is out_of_stock.
Create and send in one call
Add "ship": {} to send the order to the courier right after creating it, like the dashboard's Upload after creating. It needs the shipping:write scope, and uses the order's courier unless you pass "ship": { "courier_id": "cour_…" }. The order is created first, so a courier refusal never loses it: the answer is the order (now shipped, with its tracking code) plus shipment, or, when the send failed, ship_error with the usual error object. Send it again later with POST /v1/orders/{id}/ship. See Shipping and tracking.
Orders that need a check
If the city you send doesn't match one of the region's cities, the order is still created, with needs_review: "city_unmatched". The merchant's team confirms the address before the order can go to a courier, and an order.needs_review webhook is sent. Once they save it, needs_review returns to null.
To avoid it, send a city name from GET /v1/cities. See Addresses and countries.
Changing an order
| You want to | Call | Allowed |
|---|---|---|
| Fix the customer, address, note or metadata | PATCH /v1/orders/{id} | Any time; with a courier, see below |
| Confirm, reschedule, record a missed call | POST /v1/orders/{id}/status | The statuses in the table above marked "your integration" |
| Cancel | POST /v1/orders/{id}/cancel | Until the order is with a courier |
| Send it to the courier | POST /v1/orders/{id}/ship | Confirmed orders not yet with a courier; see Shipping |
| Leave a message for the team | POST /v1/orders/{id}/notes | Always |
Once an order is with a courier, changes come back as 409 invalid_state_transition: from that point the courier's tracking drives it. Every change your key makes is recorded in the order's history (GET /v1/orders/{id}/history) as made by your key, so the merchant always knows who did what.
Merged orders
A customer who orders twice can end up with one parcel, in two ways. Both apply only to cash-on-delivery orders that are not yet with a courier, paid or archived.
- The customer adds to their order. At checkout, a shopper whose earlier order hasn't been confirmed yet can add the new items to it. No new order is created: the earlier order gets the extra lines, its
subtotal,discountandtotalchange, and you receiveorder.updated. - The team merges two orders. On the order card, the team can merge another open order of the same customer into the one they keep. The kept order gets the lines and keeps its own address and delivery fee (
order.updated). The merged order is deleted: you receiveorder.status_changedandorder.cancelledfor it (itsstatusreadscancelledand itsnoteends withMerged into ORD-…), and after thatGET /v1/orders/{id}returns404.
Working an order
The order card's everyday actions:
| You want to | Call |
|---|---|
| Give orders to a teammate, or take them back | POST /v1/orders/assign with order_ids (up to 100) and member_id (or null). GET /v1/team_members lists who can be assigned. Needs orders:assign. |
| Archive or bring back | POST /v1/orders/archive with order_ids and archived |
| Log a call, SMS or WhatsApp, and how the call went | POST /v1/orders/{id}/contacts, then PATCH …/contacts/{contact_id} with the outcome |
| Schedule for a date | PATCH /v1/orders/{id} with scheduled_for: the status becomes scheduled |
| Change the courier it will go to | PATCH /v1/orders/{id} with courier: { courier_id, shipping_fee? } |
| Delete a note your key wrote | DELETE /v1/orders/{id}/notes/{note_id} |
Everything your key does shows in the order's history under the key's name, so the team knows an app did it.
Payment
payment.method is cod (cash on delivery), card (paid in full online) or card_deposit (a deposit paid online by card, the rest in cash at the door). payment.status is unpaid, pending (the shopper chose card and hasn't finished paying), partially_paid (deposit received) or paid. payment.amount_paid is what was already paid online and payment.amount_to_collect is what the courier collects in cash. payment.card_discount is the store's discount for paying by card (already inside discount and total). Check payment.method rather than assuming cash; more methods may be added.
Changing an order already with a courier
PATCH /v1/orders/{id} works on an order whose parcel the courier already has, the way saving the order card does: the courier gets the change first, and it is saved in Ordexs only if the courier accepts it. A refusal is courier_rejected with the courier's own words, and nothing changes on either side, so Ordexs and the courier never disagree about where a parcel goes or how much it collects.
What a courier accepts on a parcel it has:
| Courier | Can change |
|---|---|
| DHD, Ecotrack couriers, Ecom-DZ | Everything: name, phones, address, region and city, products, amount, note |
| Yalidine, Guepex | Everything but the note |
| ZR Express | Name, main phone, address, region and city, products, amount, note (not the second phone) |
| Others | Nothing: cancel the shipment and send it again |
Only until the parcel is validated or picked up: after that the answer is invalid_state_transition, saying which. Email and metadata never reach the courier and can always change. Scheduling or moving the order to another courier needs the shipment cancelled first. The order's history notes that the change went to the courier.
