Marketplace Order Statuses: Who Is the Source of Truth

Marketplace order statuses are public commitments your system makes about an order, and because events arrive late, twice, or never at all, the model has to settle who may write each state rather than which system is the source of truth.

The status is the one piece of information about an order that the buyer checks on their own, without asking you, and the one that the seller changes without asking you either. If you do not settle who has the right to write it, the random order in which messages arrive will settle it for you.

This article breaks down:

• Who is the source of truth for each state?
• Which 3 regimes handle a status reversal?
• How do you map foreign status vocabularies?
• What does one more visible status cost?

Key insights

• The source of truth for each state is a different party: the payment provider observes paid, the seller observes accepted, the carrier observes delivered, and the state that releases money is never written by the party that receives it.
• The three regimes for a reversal differ in what they cost: storing whatever arrived last contradicts itself in front of the buyer, blocking every backward move throws away the genuine reversals, and the workable one makes the visible state a computation that settles nine conflicts in ten on its own.
• Foreign status vocabularies map onto yours as a matrix: eight sources times twelve states is 96 mapping pairs, and an unknown code must never change the state, so you store the event and raise it into a queue.
• One more visible status costs 17 artifacts, counting three notification templates, three account labels, three help entries, and eight mapping rules, and a state you can set for most orders rather than all of them produces more questions than having no state at all.

Why is an order status a public commitment?

The moment you show a status to the buyer, it stops being a field in a database and becomes a sentence you said out loud. "Shipped" means "your parcel is on its way." Taking that sentence back is not a data correction.

It is withdrawing a promise, and you cannot withdraw one quietly, because the notification has already gone out.

And here is the problem you never see in a demo: events do not arrive in the order in which they happened. Three independent mechanisms produce that.

1. A message can be late

The seller's system recorded the shipment in the morning, but its queue stalled for two hours.

2. A message can arrive twice

The queues and event buses most integrations run on guarantee at least once delivery rather than exactly once.

The public documentation of large queueing services says it plainly: a copy of a message can be delivered more than once, messages are sometimes received out of order, and the ordering guarantee covers only messages tagged with a shared ordering key.

3. Two systems can write the same state

The seller's panel and the seller's integrator are two sources rather than one, and each has its own clock and its own retries.

4. The message may never arrive at all

The seller shipped the parcel, the buyer received it, and on the operator's side the order still sits in a pre-shipment state because a badly configured integrator never passed the tracking number, and that is what triggers the transition. So your model needs a rule for a state that has not changed for too long, and that rule has to raise the case into a queue instead of filling in the missing fact.

Sorting by event time will not save you. Clocks in different systems are never perfectly synchronized, and distributed computing has solved that for decades with a counter rather than a watch: order comes from a sequence number rather than from whatever time the sender happened to display.

Follow a single shipment. At 11:02 the seller's system sends "shipped" with a tracking number, but your system happens to be unresponsive.

At 11:05 a carrier scan arrives, which on your side means "out for delivery." At 11:09 the integrator retries and the "shipped" event from 11:02 finally lands. If your system stores whatever arrived last, a buyer looking at the screen at 11:10 sees the parcel go back from out for delivery to shipped.

Here is the distinction this whole article rests on: not every reversal is an error. A failed delivery, a shipment returned to the sender, a cancellation after the order was accepted are all genuine reversals, and you have to accept them.

What separates them from garbage is not the direction. It is the age of the event relative to the one that set the current state.

A model that blocks every backward move is just as broken as one that accepts every backward move.

Who is the source of truth for each order state?

"Let's pick one system as the source of truth for the order" sounds mature and is the wrong answer, because no single system observes all the facts an order is made of. Authority gets assigned separately for each state.

• Paid is observed by the payment provider.
• Accepted by the seller is observed by the seller and by nobody else, and what your clock does while the seller stays silent is a seller accepting or rejecting an order.
• Shipped is a physical event: a click in the panel means "I declared it," while a carrier scan means "the parcel exists and it is moving."
• Delivered is observed by the carrier.
• Canceled is observed by the operator and by the buyer, never by the seller alone.
• Returned is observed by whoever physically takes the goods back, so on a return to the seller's warehouse the authority goes back to them, and that is the only state where you give way on money.

Out of this comes a rule that operations practitioners state bluntly: the state that releases money is not written by the party that receives the money. In the rollouts we know, "delivered" is reserved for the operator and their own sources, even when the seller knows more about the shipment.

This is not distrust of any particular company. It is design: the interest and the right to write cannot sit on the same side.

The money consequences of that state are settled in when an order counts as delivered.

Authority is more than a list of who writes, though. It is also a decision about what a write from an unauthorized source means.

You have three answers: ignore it, take it as a secondary signal that does not change the visible state, or route it to a human for review. A write ignored silently is the worst of the three, because the source believes it delivered the information and you do not have it.

And one exception that always has to exist: a manual override of the state by the operator, with a trail of who, when, and why. Without it, every integration failure ends in orders that hang forever.

Which 3 regimes handle a status going backwards?

Count the scale before you choose. 10,000 orders a month with an average of 6 status events per order is 60,000 messages.

If 0.5% of them arrive a second time or after a newer event, you have 300 disputed messages a month. If one in three of those really does reverse a state the buyer can see, that comes to 100 reversals, and if half of them end in a contact, that is 50 contacts, which at six minutes per contact is 5 hours of team time.

The work itself is not the problem. The problem is a hundred people a month who watched your system contradict itself.

The third column looks like overkill, and it is not, because it is the only regime in which the visible state is a computation rather than a stored value. Thirty items for review come from the rule settling nine conflicts out of ten on its own: 300 divided by 10.

Both sensible regimes depend on one thing you have to ask the vendor about directly. Every event has to carry its own identifier assigned by the sender.

Without it, a repeated message is a new transition rather than a duplicate. The public standard for this mechanism in HTTP interfaces says that repeating a request with the same key should return the result of the operation already performed instead of performing it a second time.

That is idempotency in full, and it costs one field.

How do you map foreign status vocabularies onto yours?

You have one status model, and everyone writes into it using their own names. Count that as a matrix.

Eight sources (the seller panel, four integrators, your order management system, the carrier feed, customer service) times twelve states is 96 mapping pairs, and every new state adds eight more rules.

There are three things in this matrix that you settle once and for good.

1. An unknown value needs a defined behaviour

External systems add new codes without warning.

A default of "pass it through" writes a state into your order that you cannot display; a default of "ignore it" loses the information quietly. The only defensible answer: do not change the state, store the event, raise it into a queue.

2. The vocabulary the buyer sees stays small and stays out of the integrations

The public standards for describing an order in commerce get by on eight values: in preparation, awaiting payment, in transit, ready for pickup, delivered, returned, canceled, problem.

Eight is enough for the buyer. A few dozen is what you need operationally.

3. Carrier statuses map onto your model

A carrier's vocabulary maps onto your states. It does not become them.

The market has not agreed here, and that is a fact about the market rather than a curiosity: some products in this class know a shipment's intermediate states and expose them as a closed vocabulary, while others know only "shipped" and "delivered" and will not let you add anything in between. What normalization looks like on the carrier side is carriers, labels and tracking.

What does one more visible status cost?

Count what one extra state shown to the buyer costs. A notification template in three languages is 3 texts, a label in the buyer's account in three languages is 3, the help center entry and the support script are 3, plus 8 mapping rules from the sources.

That is 17 artifacts for a single state, so 68 if you add four. This is the price nobody mentions when the team asks for "just one more status."

The second part of the price is worse. A state you cannot set reliably generates more questions than not having it at all.

If you show "parcel being packed" but you fill that field only for sellers on one integrator, then across the rest of the catalog the buyer sees a gap and asks. The practical rule: a state goes onto the storefront only once you can set it for every order rather than for most orders.

So separate the two sets. Visible states are public commitments, a handful of them, changed rarely and with the agreement of whoever owns customer service.

Operational states serve your processes and your queues, there can be dozens of them, and they promise nothing to anybody.

What do order statuses change about the rest of your build?

1. The status model is an integration contract rather than a setting

Adding a state after launch means a change at every seller integrator, so the question "what does this cost and who pays for it" gets asked before launch rather than after. Who logs into the panel and what the integrator handles instead is the seller panel.

2. Statuses feed counters, and counters feed sanctions

Before "time to ship" starts suspending accounts, it has to tell a missing shipment apart from a missing message about a shipment. Quality thresholds and the date you promise the buyer each have a chapter of their own.

3. Statuses trigger documents and money

Hanging off the transitions are the issuing of the sales document (who issues which invoice), the refund (who pays for a refund), and the commission on a refund (the commission on a refunded order). One €1,000 cart at a 12% commission is €120 for you and €880 for the seller.

If 2% of 10,000 monthly orders close on a state set by a timer rather than by a fact, that is 200 orders times €880, so €176,000 moved before anything was confirmed.

Reversing a state after the accounting period has closed is no longer a reversal. It is a correction (corrections and credit notes).

How do you check the status model with a vendor?

Ask about a screen and a specific case rather than a feature list.

1. List every order state and mark which ones the buyer sees. If those two sets are the same set, you are buying somebody else's operational model as your own message to customers.
2. Who has the right to write each of them, per state and not per role. You care most about "delivered" and "canceled."
3. Send the same message twice. Does one transition appear, or two? What is the key: the event identifier or the payload?
4. Send an event older than the current state. You want to see the third option: the event stored without changing what is displayed, plus an item in a review queue. You do not want to see a silent overwrite.
5. What does the system do with a status value it does not recognize?
6. Show the transition history of a single order, with event time, write time, source, and user. Ask how many months that history is kept.
7. Does adding an intermediate state require a change on the side of the seller integrators? If it does, this is a project and not a setting.
8. Does a manual reversal of a state undo the consequences (the payout hold, the notification), or does it only change a field?

Which mistakes do operators make about order statuses?

1. One source of truth for the whole order

The consequence: either you trust the seller on the state that releases their money, or you ignore the carrier on a state you do not observe yourself.

2. Status as a field instead of a transition history

The consequence: in a dispute you cannot reconstruct who wrote the state and when, and without that you can neither hold the integrator to account nor defend your decision to the seller.

3. No event identifier

The consequence: every retry on the sender's side is a new transition, and duplicates look like real changes in your reports.

4. Ordering events by somebody else's clock

The consequence: a systematic error that grows with the number of sources and that you will not see, because each event on its own looks correct.

5. The trap of the reversible field and the irreversible consequence

You reverse the state in the database in ten seconds, but the email to the buyer has already gone out, the seller's SLA counter has already moved, and the payout has already started. The consequence: you fix the data, and you are left with effects the data does not describe.

So for every state, write down explicitly what it triggers and what happens to that on a reversal.

What do you still have to settle about your own status model?

This article does not settle what you promise the buyer about dates, how to accept and reject orders, when "delivered" becomes a money event, or how to normalize carrier shipment statuses. Those are four separate decisions that either feed this model or follow from it.

This article does not go into the law. What you owe the buyer when a state turns out to be untrue, and what you have to show them, is who delivers the buyer's rights; who is liable for the goods is whether you are an intermediary or a seller.

This article does not know your distribution of event delays. What percentage of messages arrive late on your platform, and from which sources, is a measurement on your own traffic.

All the numbers above are openly hypothetical and serve the arithmetic rather than a forecast.

The claim here is narrower and independent of those answers: a status where you cannot say who has the right to write it is not information about the order. It is a trace of the last message that happened to arrive.

Summary: Who decides what an order status says?

Whoever observed the fact, state by state. Picking one system as the source of truth for the whole order sounds mature and fails on the first shipment, because no single system sees everything an order is made of.

Events make it harder: they arrive late, twice, or never, so the visible state has to come from a rule about which event is newer rather than from whichever message landed last. That rule is also what separates a genuine reversal, like a failed delivery, from the garbage of a retry overtaking a newer event.

And every state you show the buyer is a promise with a price: 17 artifacts to build it and a stream of questions if you can only set it for part of your catalog.

Ask a vendor to send the same shipment event twice, out of order, and show you what the buyer sees. Building a marketplace where the visible status is computed from events that carry their own identifiers?

Talk to us about the build.

Frequently asked questions on marketplace order statuses

Who should be the source of truth for order statuses?

The source of truth for order statuses is assigned per state rather than per system. The payment provider observes payment, the seller observes acceptance, the carrier observes delivery, and the operator keeps cancellation.

The one rule that holds across all of them: the state that releases money is not written by the party that receives the money.

What should happen when an order status goes backwards?

An order status going backwards has to be judged by the age of the event rather than by its direction. A failed delivery, a return to sender, and a cancellation after acceptance are real reversals you have to accept.

A retry carrying an older event is not, and a model that blocks every backward move is as broken as one that accepts them all.

How many order statuses should a buyer see?

A buyer needs about eight statuses, and your operation needs several dozen. Public standards for describing a commercial order get by on in preparation, awaiting payment, in transit, ready for pickup, delivered, returned, canceled, and problem.

Keep the operational states out of that list: they serve your queues and promise nothing to anybody.