Ordexs API v1 Get an API key

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
StatusSet byMeans
pendingOrdexsNew, not yet confirmed with the customer.
confirmedThe team or your integrationThe customer confirmed: ready to send to a courier.
scheduledThe team or your integrationConfirmed for a later date (scheduled_for).
attempt_1, attempt_2, attempt_3The team or your integrationThe customer didn't answer the first, second, third call.
waitingThe team or your integrationOn hold, for example waiting for stock.
doubleThe team or your integrationA duplicate of another order.
cancelledThe team or your integrationWon't be sent.
preparing, shipped, delivered, returned, deletedThe courierSet 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_code and the offers in offer_ids (up to 4), if any, after checking each one still qualifies (see Offers and discounts);
  • prices delivery from delivery.mode (and delivery.courier_id, if you chose one from GET /v1/delivery/rates);
  • checks and reserves stock, and refuses with out_of_stock if there isn't enough. details.lines names 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:

typeThe courier…Send
delivery (default)delivers line_items and collects the totalline_items
exchangedelivers line_items and takes collect.lines backline_items, collect, usually total (the price difference)
pickuponly collects collect.lines from the customercollect
cash_collectioncollects an amount, no goodstotal

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_fee and what the courier collects with total.

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 toCallAllowed
Fix the customer, address, note or metadataPATCH /v1/orders/{id}Any time; with a courier, see below
Confirm, reschedule, record a missed callPOST /v1/orders/{id}/statusThe statuses in the table above marked "your integration"
CancelPOST /v1/orders/{id}/cancelUntil the order is with a courier
Send it to the courierPOST /v1/orders/{id}/shipConfirmed orders not yet with a courier; see Shipping
Leave a message for the teamPOST /v1/orders/{id}/notesAlways

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, discount and total change, and you receive order.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 receive order.status_changed and order.cancelled for it (its status reads cancelled and its note ends with Merged into ORD-…), and after that GET /v1/orders/{id} returns 404.

Working an order

The order card's everyday actions:

You want toCall
Give orders to a teammate, or take them backPOST /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 backPOST /v1/orders/archive with order_ids and archived
Log a call, SMS or WhatsApp, and how the call wentPOST /v1/orders/{id}/contacts, then PATCH …/contacts/{contact_id} with the outcome
Schedule for a datePATCH /v1/orders/{id} with scheduled_for: the status becomes scheduled
Change the courier it will go toPATCH /v1/orders/{id} with courier: { courier_id, shipping_fee? }
Delete a note your key wroteDELETE /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:

CourierCan change
DHD, Ecotrack couriers, Ecom-DZEverything: name, phones, address, region and city, products, amount, note
Yalidine, GuepexEverything but the note
ZR ExpressName, main phone, address, region and city, products, amount, note (not the second phone)
OthersNothing: 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.