Cash on delivery in Algeria: what developers need to model
How cash on delivery works in Algeria: the money flow, delivery and return fees, the deep-south surcharge, confirmation calls and a data model that holds up.
Around nine of ten e-commerce orders in Algeria are paid in cash at the door. COD is not a payment option you bolt on; it's the shape of the whole system, and it changes what your data model and your order flow need to handle.
The money flow
- You create the parcel with a
codAmount(integer DZD): what the driver collects. - The courier delivers, collects the cash, and later remits it to the merchant, minus fees, on the courier's payout schedule.
- If the customer refuses or never shows, the parcel comes back and the merchant pays a return fee and has recovered stock to restock or re-ship.
Model all three outcomes. The most common modeling mistake is treating
"shipped" as "sold": a COD order isn't revenue until it's delivered, and a
returned order is negative margin (return fee + handling + sometimes a
damaged product).
Fees: quote, don't hardcode
Delivery pricing varies by courier, by destination wilaya, sometimes by commune, by delivery type (home vs stop-desk), and over time. Hardcoded fee tables rot. Quote per order:
curl -X POST https://freeship.dzbuild.com/v1/rates \
-H 'Content-Type: application/json' \
-d '{
"courier": "yalidine",
"credentials": { "apiId": "…", "apiToken": "…" },
"query": { "fromWilaya": 16, "toWilaya": 31, "deliveryType": "home" }
}'{ "deliveryFee": 600, "returnFee": 250, "total": 600, "currency": "DZD" }Note the returnFee in the response. Your unit economics per wilaya are
margin × delivered_rate − returnFee × (1 − delivered_rate), and both numbers
in that formula vary by destination.
Who pays shipping is a per-courier detail with real consequences: Yalidine, for instance, adds its fee to what the driver collects unless you flag the order as free-shipping. Get it wrong and customers pay more at the door than your checkout showed, which is how you earn refusals. See the Yalidine guide.
The deep-south surcharge
The Grand Sud wilayas (Adrar, Tamanrasset, Illizi, Tindouf, Bordj Badji
Mokhtar, In Salah, In Guezzam, Djanet, Timimoun, Ouled Djellal and neighbors)
cost meaningfully more to serve and take longer on every courier.
GET /v1/wilayas marks them with isDeepSouth: true. If your checkout shows a
flat national shipping price, these orders lose money quietly; either quote
live rates or price the tier separately.
Confirmation before shipping
Because the customer commits nothing at checkout, Algerian stores confirm orders by phone (or WhatsApp) before creating the parcel. This single step is the strongest lever on delivered rate that exists.
For your integration this means: checkout should not create the shipment.
Store the order, confirm it, then call /v1/orders. Wiring parcel creation
directly into the checkout submit is the classic first-build mistake; you'll
ship to unconfirmed customers and eat the return fees. It also plays badly
with courier-side rules (see Maystro's same-day duplicate policy in the
Maystro guide).
Stop-desk: the COD risk reducer
deliveryType: "stopdesk" sends the parcel to the courier's office and the
customer collects it there. It's cheaper, faster, and the customer showing up
is self-selection: refusal rates drop. The trade-off is coverage (not every
commune has a desk) and friction for the customer. Offer both when you can and
let the rate quote price them honestly. POST /v1/desks gives you the desks to
offer, so the customer picks one instead of typing an address the courier has
to guess.
A data model that survives contact with COD
Minimum fields that earn their place, learned from running DZBuild:
statususing the canonical vocabulary, plus the raw courier status for support.cod_amount,delivery_fee,return_feecaptured at creation time (quotes change; your accounting shouldn't).confirmed_atand who confirmed: your delivered-rate reporting will want it.delivery_attemptedtimestamps: the call-back window (see statuses) is measured in hours.- A terminal-state check before any restock or refund logic: only
returnedrestocks, onlydeliveredbooks revenue.
Last updated on
Statuses
The fourteen parcel statuses dzship returns for every Algerian courier, with French and Arabic labels and the ones that need special handling.
Choosing a courier
Yalidine, ZR Express, Maystro, NOEST or an Ecotrack courier: coverage, stop desks, exchanges and API quality compared for Algerian stores.