The order model

The problem#

In a marketplace a buyer order is almost never one operational unit. Each seller packs separately, ships separately, cancels separately and gets paid separately. The question is whether that split should be visible in the data model, or whether it is enough for lines to know their owner.

Two models#

Minimum version#

• An order line knows its seller and has its own fulfilment state.
• Cancellation and refunds work at line level, not only on the whole order.
• Order state is derived from line states rather than set independently.
• The buyer sees one number, whatever the internal split.

What not to build yet#

• A distributed flow with compensations across services. At this scale that is complexity without a return.
• Your own state engine with configurable transitions.
• Automatic splitting of orders into parcels. The seller knows better how they pack.
• A history of every field change. State changes and money operations are enough.

Plan ahead#

Cancellation and refund granularity#

This is the hardest decision in the chapter to undo. If the model only allows cancelling a whole order, adding per-item cancellation means recalculating values, taxes and commissions on historical orders. The reverse direction is free.

Returned quantity apart from ordered quantity#

A partial return is not a change to the line quantity, it is separate information alongside it. Overwriting the quantity destroys what the buyer actually ordered, and every later settlement depends on that.

An order knows its own money#

Line value, tax, shipping cost and the commission charged belong on the order rather than being computed on every read. Reading from live data means last month report gives a different answer today.

Triggers#

• the first order where one seller has shipped and another has not;
• the first request to cancel a single item;
• the first partial refund;
• the first seller asking why they can see somebody else items on an order;
• settlement starts requiring grouping in every query.

Next stage#

After the first and fourth triggers together: splitting out the seller part of an order as its own entity, with its own state and its own view. After the fifth: the same thing, but driven by settlement rather than by the interface. Both lead to the same place, so if both are close, do not defer it.

Common mistakes#

What works in practice#

Splitting an order into the part belonging to each seller turned out to be the decision that unlocked everything that came later: settlements, payouts, refunds and transfer reversals. Each of those modules works on a ready-made unit instead of grouping lines every time.

I would not recommend it as the default starting point, though. That split earns its keep only once several sellers per order is the norm rather than the exception. Where an order almost always has one seller, line-level ownership is enough and much cheaper.

Checklist#

• An order line knows its seller and has its own fulfilment state.
• Order state is derived, not set.
• Cancellation and refunds work at item level.
• Returned quantity is separate information from ordered quantity.
• Money values are recorded on the order.
• A seller sees only their own items.