Mirakl · Ep 3: who owns the order?

Section 1 of 6

TL;DR

  • The storefront takes the payment. The marketplace decides who fulfils.
  • One customer order becomes several seller orders. Design for that split from day one.
  • Give every status a single owning system, and write it down.

On a marketplace build, the question behind the most late-night calls isn’t about catalogue or pricing. It’s simpler: when a customer places an order, which system owns it? Get this wrong and every downstream integration inherits the confusion.

One order, many sellers

In Adobe Commerce, an order is one record with one status. On the marketplace, the same purchase becomes one order per seller, each with its own lifecycle: waiting for acceptance, waiting for payment, shipping, shipped, received, closed, and two early exits, refused and cancelled. Your integration has to hold both views at once, and the customer only ever sees one of them.

Decide which system owns each status before you write a single line of sync code.

Every status needs an owner

StatusOwnerWhy
Payment authorisation and captureThe storefrontThat’s where the payment provider lives. By default, capture waits until sellers accept
Acceptance and refusalThe seller, through the marketplace
Shipping and trackingThe seller, through the marketplace
The customer-facing statusThe storefrontDerived from the seller orders
RefundsBothThe marketplace records them per seller. The storefront moves the money

Put this in a table in your design document, and make every sync job respect it. When two systems both think they own a status, you get orders stuck in loops.

Design for partial everything

Partial acceptance, partial shipment, partial refund. A three-seller order where one seller refuses an item is normal, not an edge case. If the customer’s order page can’t show “two of three sellers have shipped”, your support inbox will show it for you.

The sync points that break first

  1. Capture timing. If you capture before acceptance and a seller refuses, you’re refunding money you shouldn’t have taken.
  2. Polling gaps. Order updates fetched by date range miss changes if your clock and the marketplace’s disagree. Overlap the windows and de-duplicate.
  3. Cancellations from the customer. Decide whether a customer can cancel after a seller accepts, and which system enforces it.
  4. Refund rounding. Shipping and commission split across sellers rarely divide evenly. Agree the rounding rules with finance early.

A pattern that works

Keep a small mapping table in Commerce: one row per seller order, with its marketplace ID, its status and the last time you saw it change. Derive the customer-facing status from those rows with one function. Everything else (emails, the account page, support tools) reads that function, never the raw statuses.

What’s next

That’s the end of the foundations. From here the Mirakl series becomes a developer log: building integration pieces step by step with Claude Code, starting with the sync points above.

Written by Vishwas Bhatnagar

Technical Architect. Adobe Commerce, marketplaces and AI-assisted engineering.

More about me →

More