Disclosure: I work on 24hTrack, a multi-carrier package tracker. The patterns below apply whatever you build on.
Most post-purchase code treats a shipment as a line that moves one way: label created, in transit, out for delivery, delivered. That model is fine until the order is cash on delivery, and then it quietly produces wrong answers for a large part of the world.
Cash on delivery is ordinary across the Gulf, much of Africa and a lot of South-East Asia. GFS Express, one of the networks carrying Chinese e-commerce into that region, lists local operations in Saudi Arabia, Bahrain, Jordan, Kuwait, Oman, Qatar, Azerbaijan, Georgia and South Africa, and sells cash collection to merchants as a product with weekly remittance. If your buyers are there, a meaningful share of your orders are only paid for at the doorstep.
Four things that break.
1. "Delivered" stops meaning "paid"
On a prepaid order those two collapse into one event. On COD they are different facts arriving from different systems: the scan from the carrier, the money from a remittance file days later. If your fulfilment logic recognises revenue on a delivery scan, COD will overstate it, and every refusal becomes a correction you have to find by hand.
2. The reverse path is a normal path, not an error
A COD buyer can simply decline at the door. Tracking records that as a failed attempt and then a return - the same two statuses you get when nobody was home. Carriers rarely tell you which it was. If your code treats returned as an exception to alert on, COD markets will drown you in alerts for transactions that worked exactly as designed. Model it as an outcome with a reason you may never learn, not as a failure.
3. Amounts are not in tracking data, and you should not synthesise them
Carriers publish scans: a status, a time, often a place. They do not publish what the recipient owes. Every so often someone asks us to show the COD amount on a tracking page. We can't, and neither can anyone else reading the same feeds - the number lives in the order, not in the shipment. If your UI implies otherwise, you have invented a figure a customer will act on.
4. Duty is a second, unrelated money event
Import duty and VAT are billed by the carrier or the post, usually ahead of delivery, usually by SMS or email with a link. It can land on a fully prepaid order. It is not COD and it is not collected the same way. Conflating them produces support answers that are confidently wrong.
Where the wrong answers actually surface
Not in your dashboard - in the "is this a scam?" ticket. Buyers in COD markets are also the buyers most targeted by doorstep payment fraud, and they cannot tell your legitimate collection apart from it. The cheap mitigation is boring and entirely on your side: state the COD amount in the order confirmation, in the buyer's currency, in a line they can find on a phone at the door. Everything a scammer cannot replicate - a matching order, a receipt, payment to the courier rather than a link - then becomes checkable in ten seconds.
A small data detail while you are in there
When you normalise scans, do not assume the location is a field. Several carriers write it into the text:
Riyadh, Parcel picked up from customs
If you render a location column from event.location alone, those rows look placeless, and your "we have no location for this parcel" branch fires on a parcel whose city is sitting in the first eight characters of the description. Read the words before you declare the field empty.
None of this needs a new vendor. It needs the shipment model to have two axes - where the goods are, and whether the money moved - instead of one.
If you would rather not build the tracking half: 24hTrack detects the carrier from the number across 3,200+ carriers, is free on the web with no sign-up, syncs to Google Sheets at no cost, and has a REST API plus an MCP server (npm i 24htrack-mcp) for AI agents. The open guide and transit-time data are on GitHub.
FAQ
Can a tracking API tell me the cash-on-delivery amount?
No. Tracking feeds carry statuses, timestamps and sometimes locations. The amount lives in the order record, not in the shipment, so any tracking tool showing you a figure is reading it from somewhere other than the carrier.
How do I distinguish a refused COD parcel from a missed delivery?
Usually you cannot from the scans alone - both appear as a failed attempt followed by a return. Carry your own signal instead: a COD flag on the order plus the remittance file, and treat an unpaid return on a COD order as a refusal until proven otherwise.
Is cash on delivery the same as paying customs duty?
No. COD is the price of the goods, collected for the seller. Duty is tax, billed by the carrier or post, and it can appear on an order that was already paid in full.
Which carriers use cash on delivery?
It is a service sold to merchants rather than a property of a carrier, and it is common wherever the market expects it. GFS Express is one example that advertises collection with weekly payout to the seller.
Top comments (0)