Returns and disputes

The problem#

A return is the one marketplace operation that touches everything at once. It changes order state, the payment amount, the commission charged and how much the seller is owed. If the money has already gone out, it adds a fifth thing: the need to pull part of it back.

The chain of effects#

It is worth writing out, because every link you forget comes back as a discrepancy in money.

Minimum version#

• A return request as its own entity, with items and quantities.
• A seller decision: accepted or rejected, with a reason.
• The refund tied to the request rather than standing alone.
• Returned quantity recorded alongside ordered quantity, never instead of it.

What not to build yet#

• Escalation to the platform with response deadlines and stages.
• Evidence uploads, photos and correspondence as a separate module.
• Automatic dispute resolution.
• Return labels and carrier integration.

Plan ahead#

A return concerns items, not orders#

This is the same decision as cancellation granularity in the order model chapter, and it carries the same price. Moving from whole orders to items requires recalculating values and commissions across history. The reverse direction is free.

Running totals rather than a state label#

Keep refunded and captured as sums, not as a status. Three partial refunds in a row is a normal situation and only numbers can describe it.

Settle who decides#

In a model where the seller sells, they decide whether to accept a return and the platform steps in only on a dispute. Where the platform sells, the decision is theirs from the start. That follows from chapter one and is not an interface choice.

Triggers#

• the first return of one item from an order containing several;
• the first return after a completed payout;
• the first dispute where buyer and seller say different things;
• a second partial refund on the same order;
• returns start needing a weekly review.

Next stage#

After the second trigger: linking the return to the payout, so the right amount can be reversed. After the third: a simple "in dispute" state and somewhere for an operator note, with no process and no deadlines. After the fifth: a request queue with filters, still without automatic decisions.

Common mistakes#

What works in practice#

A return here is an event that travels the whole chain in the table above, and every link has its own record. The hardest part was never returning the money to the buyer, it was the case where the funds had already reached the seller. Reversing part of a transfer requires knowing which payout covered which order, and that is the only reason the relationship has to exist from the start.

The dispute layer behaves the other way round. Disputes are rare and each one is different, so a simple state plus somewhere for a note carries most of the value, while a staged process with deadlines adds work faster than it adds order.

Checklist#

• A return request knows items and quantities, not just the order.
• Returned quantity is recorded alongside ordered quantity.
• Refunded amounts are running totals, not a state label.
• A return reduces commission proportionally.
• A return after a payout has a way back to the specific transfer.
• It is clear who decides whether a return is accepted.