Skip to main content
All posts
July 4, 2025Β·2 min readΒ·Diogo Hudson

Returns are first-class

A return note is not a minus sign on a delivery. It's its own document, with its own posting flow, and the ledger cares about the difference.

Returns are first-class

Plenty of tools treat returns as edits on the original delivery. Back out a line, adjust the total, move on. It makes the dashboard simpler and the history impossible to reconstruct.

The edit-the-delivery approach has a superficial appeal. Why create a new document when the original delivery already has the line items? Just set quantity to zero on the returned items, adjust the totals, and pretend it never happened. The problem is that it did happen. The driver went to the customer site. The product was unloaded. Days or weeks later, part of it came back. Collapsing those events into a single edited record destroys the operational timeline and makes it impossible to answer basic business questions about return rates, customer behavior, and product quality.

A return note is its own document Quotery models ReturnNote as a peer of DeliveryNote. It has its own draft β†’ posted lifecycle, its own numbering (RN-YYYY-NNNN), its own items. Posting it increments on_hand and writes a RETURN row on the stock ledger. The parent quote's status does not change β€” per D8, a return does not roll the quote back.

This design has two consequences. First, the original delivery is immutable β€” once posted, its numbers are fixed. You can always see exactly what was shipped on which date. Second, the return is independently auditable. It has its own creation date, its own posting date, its own items and quantities. The time gap between delivery and return is captured naturally, not collapsed.

Why not reverse the delivery? Because the customer did not cancel the sale. They took delivery, decided they didn't want part of it, and sent some back. Commercially and legally, those are different events. Folding them confuses the audit trail and makes it hard to answer real questions like 'how much of what we shipped to this customer came back last quarter?'

The distinction matters for metrics. Return rate by customer is a leading indicator of satisfaction and fit. Return rate by product signals quality or description issues. Return rate by salesperson may indicate over-selling or miscommunication. If returns are folded into delivery edits, none of these metrics are computable β€” you've destroyed the data you need to improve the business.

Three fulfillment documents, one flow DeliveryNote, ReturnNote, and StockReceipt all share a draft β†’ posted state machine. The code paths differ only in which stock direction they push. DeliveryNote pushes stock out (decrease on_hand). ReturnNote pushes stock in (increase on_hand). StockReceipt pushes stock in from a supplier (increase on_hand, no parent delivery). Same pattern, different sign. The consistency reduces bugs and makes the system predictable.

How deliveries and returns actually work.

All posts
Short pieces on quoting, inventory, AI, and how small distributors ship a lot of stuff without the fuss.