Cash on Delivery looks simple from the outside: customer gets the package, customer pays the driver, order is "paid." Most systems model it exactly that way — a boolean on the order row flips from false to true and everyone moves on.
That's wrong, and it took a support ticket to notice why.
The money the driver collected isn't actually ours yet. It's sitting with the carrier until they run their settlement cycle and transfer it over — which, depending on the carrier, can be days or weeks later. During that whole window, "paid: true" is a lie. The order is fulfilled, sure. The cash isn't.
So we stopped treating it as a flag and started treating it as what it actually is: a receivable. An order moves from placed → COD pending (an open receivable on our books) → carrier payout → reconciled, and it's only "settled" once we've matched an actual payout from the carrier against that specific order's expected amount. If the carrier's payout comes in short, or an order's COD never gets matched to any payout, that's visible — not quietly absorbed into "paid: true."
It's a small modeling change but it matters most for exactly the stores that rely on COD heavily, where this isn't an edge case, it's most of the order volume. A boolean can't tell you if a carrier is underpaying you on 3% of orders every month. A reconciled ledger can.
Built this into StoreFlux (storeflux.store) — a backend-as-a-service for e-commerce. Curious how other people handle carrier-collected payments in their own systems — anyone doing something smarter than a straight ledger match?
Top comments (2)
The naming is the useful part, and not for tidiness: a receivable has an age and a boolean doesn't. The metric falls straight out — age of the oldest unmatched COD receivable, by carrier. That's the number that tells you a carrier stopped settling before any individual order looks wrong, and it can't be made green by restarting anything on your side.
On your question, the thing that'll bite you is that carrier payouts are net and batched, not per-order. So the match isn't order to payout, it's a subset of orders summing to one payout after fees, returns and adjustments. Solved as an amount-matching problem that's subset-sum, and in practice you don't solve it: you require a remittance file with order references and treat an unreferenced payout as an exception that a person looks at. If a carrier won't give you the file, you end up matching on amount and date with a tolerance, and the tolerance is exactly where your 3% underpayment hides. Worth knowing which of your carriers will send references before you design the matcher, because it decides whether this is a join or a reconciliation.
Second thing: give the receivable a terminal failure state with a reason, and an owner. Unmatched-forever is the default outcome otherwise, the list grows, and a list that only grows stops being read. Same as any queue nobody drains. Write-off with a reason code is less satisfying than a match and it's what keeps the open list meaningful.
This is absolute gold "join vs. reconciliation" hits the nail on the head.
Remittance vs. Subset-Sum: Spot on. Trying to solve net batch payouts without structured remittance files leads straight to underpayment leakage. We treat unreferenced bulk payouts as exception queues requiring human review rather than guessing with fuzzy math.
Terminal States & Ownership: Couldn't agree more on avoiding the "unmatched-forever" list. Giving receivables an explicit terminal state (written_off, short_paid, disputed) with reason codes and an assigned owner keeps the aging queue actionable.
Aging Metric: Tracked age of the oldest unmatched COD receivable by carrier is now sitting right at the top of our operational dashboard.
Really appreciate the deep domain insights here!