- Ten units were ordered. Ten were shipped.
- The original order is still true.
- If the platform simply edits the original quantity until the screen “looks right”, it destroys the story that procurement, the supplier and accounting need to understand.
- That was the client problem on a B2B marketplace built with Medusa.
The client problem
Ten units were ordered. Ten were shipped. The buyer opened the parcel and found eight correct items, one damaged item and one entirely different product.
The original order is still true. It records the commercial commitment. The delivery is also true. It records what physically happened. The claim and its resolution create a third truth: what the supplier agreed to replace, cancel, collect or write off.
If the platform simply edits the original quantity until the screen “looks right”, it destroys the story that procurement, the supplier and accounting need to understand.
That was the client problem on a B2B marketplace built with Medusa. We created a delivery-claim journey beside the order. Buyers report missing, damaged, wrong or other item problems against delivered quantities. Sellers resolve each item through replacement or cancellation, with a physical return where required. The platform then derives the effective commercial view while preserving the original order lines and the claim history.
The goal is not to hide that something went wrong. It is to make the correction explainable.
Keep order truth and exception truth separate
An order line answers: what did the buyer purchase?
A delivery claim answers: which delivered units did not satisfy that purchase, why, and what should happen next?
Overwriting the line quantity mixes those questions. A future invoice reviewer might see nine units and assume nine were ordered. A supplier might lose the evidence that a tenth unit was shipped and later written off. A replacement could appear to be an ordinary extra purchase.
We use Medusa's claim and order-change foundations to give the exception its own identity. The claim links to the order, affected line items and subsequent return or replacement actions. Metadata records the buyer's issues, seller, lifecycle status and later resolution.
The original line remains the historical purchase. A derived item view can exclude written-off or returned quantities and include delivered replacement lines when documents or accounting need the effective commercial outcome.
History remains history; current obligation is calculated from it.
Let buyers claim only delivered, unresolved quantities
A buyer should not be able to claim arbitrary order lines or quantities.
The request workflow loads the order, verifies customer ownership and checks every selected line. Claim quantities must be positive whole numbers. The same line cannot appear twice in one request. A submitted line identifier must belong to that order.
Most importantly, maximum claimable quantity is calculated from the line's delivery and exception history:
claimable = delivered − written off − return requested − return received
The value never falls below zero. If the buyer asks to claim more than that maximum, the request is rejected with a specific reason.
This prevents repeat claims from silently stacking over the same units. It also allows a later claim against a delivered replacement after the previous cycle has reached the necessary terminal state.
The platform gives the buyer a real remedy without turning the claim form into an unrestricted order editor.
Name the problem the buyer experienced
The implemented buyer reasons are deliberately concrete:
- missing item;
- damaged item;
- wrong item;
- other.
Each claimed line carries its quantity, reason and optional note. The workflow translates damaged goods into the native production-failure reason used by the underlying claim primitive while retaining the buyer-facing meaning in the claim context.
Reason matters because it constrains the resolution.
A missing item cannot be physically returned. A wrong item may justify sending a different replacement variant, but that alternate-variant exchange requires the original physical item to come back. A damaged item may be replaced like for like, returned or written off depending on the seller's decision.
The model does not attempt to represent every conceivable customer-service dispute. It defines the delivery exceptions this procurement journey supports and gives them enforceable rules.
Require one seller decision for every claimed item
The seller resolves the claim line by line.
For each issue, the accepted resolution is either replace or cancel. The seller also states whether a physical return is required and, for a valid wrong-item replacement, may select an alternate replacement variant.
Every claimed item must be resolved exactly once. Missing decisions, duplicate decisions and unsupported resolution values are rejected before the workflow changes the order.
This produces a clear plan rather than one vague claim status. One damaged line can be replaced, another can be cancelled, and the seller can require return only where it makes operational sense.
The resolution also remains seller-scoped. The workflow verifies that the authenticated seller owns the order and that the claim is currently awaiting vendor review. A cancelled or already-progressed claim cannot be resolved again through the same path.
The seller has authority over its claim, not over somebody else's order history.
Translate each decision into physical operations
“Replace” and “cancel” are commercial words. The platform must translate them into stock and order operations.
If an item requires return, the claim requests a return at the seller's resolved location. If no return is required, the original affected quantity becomes a write-off and contributes to an offsetting credit amount.
Replacement decisions add outbound claim items linked back to the source line. Their metadata identifies them as claim replacements rather than ordinary order additions. The inventory preparation step resolves the replacement variants and creates reservations at the vendor location.
For a genuinely missing item, the workflow can restore the missing unit to inventory before reserving the replacement. That may seem counter-intuitive until the accounting is made explicit: the original fulfilment reduced stock, but the buyer says the unit never arrived and the claim model writes off the commercial line. The inventory adjustment and replacement reservation express the chosen operational correction.
Each consequence follows the reason and resolution instead of being inferred later from a final quantity.
Keep replacement lines recognisable
A replacement should appear in the order journey without pretending it was part of the original basket.
The claim adds outbound line items with metadata linking each one to its source item and claim. A like-for-like replacement can retain the original title and unit price. An approved alternate variant carries its own identity.
That relationship supports several later questions:
- Has the replacement been delivered?
- Which original issue produced this line?
- Can the purchase order be validated yet?
- Should the replacement appear in the effective item view?
Purchase-order validation checks that required returns have been received and replacement items have been delivered before the order can progress. The platform does not treat the seller's resolution as proof that the physical remedy has already happened.
This distinction is crucial. “We will replace it” is a commitment. “The replacement was delivered” is a later event.
Derive the effective commercial quantity
Medusa retains written-off and returned quantities on the original line for auditability.
For current procurement documents and accounting, the platform derives an adjusted quantity:
adjusted quantity = original quantity − written off − return received
The value is bounded between zero and the original quantity. The derived item can expose the original, adjusted and removed quantities as a claim adjustment. Delivered replacement lines remain separate and can be included as the remedy.
This lets different views answer different questions honestly.
The historical order still shows what was bought. The claim shows what failed and how it was resolved. The adjusted commercial view shows what remains payable or documentable after resolved write-offs and returns.
No one needs to infer all three meanings from a single mutated number.
Recalculate accounting without erasing the event
A resolved claim can change the payable commercial total.
The platform derives item value from claim-adjusted quantities, then adds shipping and tax and subtracts discounts. Where vendor tax is rate-based, it can be recalculated against the adjusted taxable subtotal.
The claim workflow synchronises the purchase-order accounting total with a reason and claim reference. When the no-return resolution creates a write-off, an order credit line records the offset against the claim.
These operations do not make the claim disappear into a new order total. They connect the financial effect to the exception that caused it.
That matters when accounts payable asks why the validated amount differs from the original purchase order. The answer is not “somebody edited the order.” It is “this delivery claim removed these units and introduced these replacement obligations.”
Reopen tax and invoice work when the basis changes
A previously reviewed tax or supplier invoice can become stale after a claim.
The resolution workflow reopens vendor tax where the commercial basis changed. It preserves prior tax context needed for a later replacement calculation rather than treating the old value as current.
When tax is reopened, the platform clears stale active supplier-invoice state through the invoice-replacement mechanism. The supplier or reviewer can then establish a document that reflects the claim-adjusted transaction.
This is a strong example of why claims cannot live only in customer-service notes. A delivery exception can affect inventory, order lines, tax, invoice evidence and payment validation.
The workflow coordinates those consequences while preserving each domain's responsibility. Resolving a claim does not itself claim that the replacement invoice is received or the payment is settled. It makes the existing evidence visibly stale and opens the correct next work.
Preserve claim lifecycle and repeat claims safely
A claim moves through meaningful states.
The buyer request begins in vendor review. The vendor's accepted plan becomes vendor resolved. Required return receipt and replacement delivery can remain outstanding. Purchase-order validation later completes eligible resolved claims.
If the buyer reports a problem with a delivered replacement, a new claim cycle may begin after the previous cycle has satisfied its terminal conditions. The request workflow closes the prior cycle where appropriate rather than rewriting it or adding a second active interpretation over the same issue.
Order and list responses summarise active, resolved and completed claim states for buyers and operators. Cancelled and unrelated native claims are not counted as active marketplace delivery work.
This creates history that can be read sequentially: original order, first issue, chosen remedy, physical completion and any later exception.
Why Medusa was the right foundation
Medusa supplied order lines, claims, returns, order credits, reservations and workflow primitives. The client needed those primitives connected through a precise delivery-exception policy.
We added buyer reasons, claimable-quantity rules, seller ownership, per-line resolution, replacement identity, inventory preparation and claim-adjusted commercial views. We then connected tax, invoice and purchase-order validation to the same claim lifecycle.
That is the value of an extensible commerce engine. The project did not need a customer-service database beside commerce or destructive edits inside the order. The exception could become a first-class commerce workflow whose physical and financial effects remain traceable.
Medusa holds the transactional foundations. The architecture expresses what this business means by a resolved delivery problem.
A practical delivery-claim checklist
Before adding claims to a B2B order journey, define these contracts:
- Which delivery problems can the buyer report?
- Which delivered quantities remain claimable?
- How are previous write-offs and returns subtracted?
- Can one line be selected twice in a request?
- Who may open and who may resolve the claim?
- Which resolution types are supported?
- When is a physical return impossible or mandatory?
- Can a wrong item be replaced by another variant?
- How are replacement lines linked to original items?
- Which inventory location receives returns and supplies replacements?
- What stock adjustment follows a missing-item decision?
- How is payable quantity derived without overwriting original quantity?
- Which credit, tax and invoice states become stale?
- What must physically happen before purchase-order validation resumes?
- When may a later claim cycle begin?
These answers turn “contact support” into an auditable commerce capability.
The broader lesson
The client did not need the order screen edited until the problem disappeared.
They needed the platform to preserve what was ordered, record what went wrong and make the remedy part of the transaction.
We kept the original lines, constrained buyer claims to delivered unresolved quantities and required the seller to resolve every issue through replacement or cancellation. The workflow coordinates returns, write-offs, replacement reservations, credits, tax and invoice review. A derived commercial view explains the adjusted result without rewriting history.
That creates a better buyer experience and a stronger accounting story.
When delivery goes wrong, a commerce platform should not erase the past. It should explain how the business moved from the original commitment to a fair resolution.