Selling cash on delivery
Shipping and tracking
Send orders to the store's courier, follow every parcel as the courier reports it, print labels, and test it all without a real parcel.
How shipping works on Ordexs
Each store connects its own courier accounts (ZR Express, Yalidine, DHD, Noest and others) in the dashboard. When an order is confirmed, someone presses Send to courier, or your integration calls the API: Ordexs registers the parcel with the courier and gets a tracking code back. From then on Ordexs reads the courier's tracking on a schedule and keeps the order up to date: shipped, delivered, returned, cash collected.
Through the API you get the same three things the dashboard has:
- Send an order:
POST /v1/orders/{id}/ship. - Follow it: the shipment object,
GET /v1/shipments?updated_since=…, or theshipment.updatedwebhook. - Print its label:
GET /v1/shipments/{id}/label.
The key needs shipping:write to send and cancel, shipping:read to read and print.
Sending an order
To create and send in one call, add "ship": {} to POST /v1/orders (see Orders). For an existing order:
curl -X POST https://api.ordexs.com/v1/orders/ord_9b1c2d3e4f5a4b6c8d7e6f5a4b3c2d1e/ship \
-H "Authorization: Bearer $ORDEXS_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"Ordexs builds the parcel exactly as the dashboard would: the products as the merchant names them on courier slips, the cash to collect, the delivery mode and desk, the order number as the courier's reference. The courier is the first of:
- the
courier_idyou send (an account fromGET /v1/delivery/rates); - the courier chosen at checkout;
- the store's routing rules;
- the store's default courier.
The answer is a shipment with its tracking_code, and the order moves to shipped.
When a send is refused
| You get | Because | What to do |
|---|---|---|
409 invalid_state_transition | The order is already with a courier, is cancelled, or waits for its address to be checked | Read the order. Cancel the old shipment to send again. |
409 idempotency_in_progress | Another request is sending this order right now | Wait a few seconds and read the order. |
422 courier_not_configured | No courier account matches | The merchant connects a courier or sets a default. |
422 courier_rejected | The courier refused the parcel; its own reason is in message | Fix what it names (often the phone or the address), then send again. The failed attempt is recorded and returned in details.shipment_id. |
503 upstream_unavailable | The courier didn't answer | Read the order: if it has a tracking code, the parcel exists. Otherwise retry later. |
Following a parcel
A shipment has two levels of progress:
statusis what to decide on:pending(registered, not picked up),in_transit,delivered,returned,cancelled,failed.stageis a finer reading of the courier's last report, for display:out_for_delivery,no_answer,postponed,at_desk,cash_collected,paid,returning,return_ready…
The cash on delivery has its own track in cod.status: delivered_unpaid (delivered, not collected yet), cash_collected (the courier holds the money), paid (the courier paid the merchant). events is the courier's own history of the parcel, in the courier's language.
To stay in sync, subscribe a webhook endpoint to shipment.created and shipment.updated; each update carries the old values in previous_attributes. Or poll GET /v1/shipments?updated_since=… (see Pagination and syncing).
Labels
GET /v1/shipments/{id}/label returns the courier's label as a file, usually a PDF, ready to print. Each call asks the courier, so fetch it when you print, not in a loop.
Before pickup: packed and validated
POST /v1/shipments/{id}/packmarks the parcel packed and waiting for the courier, like scanning it on the dispatch screen (packed_at).POST /v1/shipments/{id}/validatetells couriers that need this step that the parcel is ready (validated_at). Couriers without a validation step answerrequest_rejected.
Checking a parcel now
POST /v1/shipments/{id}/refresh asks the courier for the parcel's status now instead of waiting for the next scheduled check, like the order card's refresh button. The same cool-down as in the dashboard applies (it depends on the plan, and counts from the last check, including the send itself): too soon and you get rate_limited with the seconds to wait. Prefer the shipment.updated webhook; refresh is for a person asking "where is it right now?".
The customer's tracking page
Every order has a private tracking page on the store's address, in delivery.tracking_url (https://<store>.myordexs.com/track/<code>). Send it to the customer by SMS, WhatsApp or email: it shows each step of the delivery with its date and time, the courier's updates (failed attempts and their reason, new delivery dates, returns), the stop desk's address when the courier publishes it, and what is left to pay. From that page the customer can also ask the store for something ("I'm available", "call me later", "fix my address"), which arrives as a note on the order.
The link is the same before and after the order reaches a courier, and stays the same if the parcel is cancelled and sent again. It stops working 3 days after the order is delivered or returned (a cancelled order has no tracking page): the page then says the link has expired and shows nothing about the order, so don't send it after that. It is null in test mode, where stores have no storefront.
A courier Ordexs doesn't send to
If the merchant ships some parcels by other means, record the tracking number by hand with POST /v1/orders/{id}/tracking ({ "tracking_code": "…" }, or null to clear it). Nothing is sent to a courier.
Cancelling
POST /v1/shipments/{id}/cancel cancels the parcel at the courier while it is still pending. The order goes back to unsent (status: deleted, no tracking code) and can be sent again. Once the courier has picked the parcel up, it can only come back as a return.
Testing without a courier
With a test key, POST /v1/orders/{id}/ship never reaches a courier: it returns a simulated shipment with a TEST-… tracking code, and its label is a PDF marked TEST. Move it along as a courier would with the test helper:
curl -X POST https://api.ordexs.com/v1/test_helpers/shipments/shp_…/advance \
-H "Authorization: Bearer $ORDEXS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "status": "delivered", "cod_status": "cash_collected" }'The order follows exactly as it does live (delivered, returned…), and the same shipment.updated and order.status_changed webhooks go to your test endpoints. The helper refuses live keys.
