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
| Status | Owner | Why |
|---|---|---|
| Payment authorisation and capture | The storefront | That’s where the payment provider lives. By default, capture waits until sellers accept |
| Acceptance and refusal | The seller, through the marketplace | |
| Shipping and tracking | The seller, through the marketplace | |
| The customer-facing status | The storefront | Derived from the seller orders |
| Refunds | Both | The 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
- Capture timing. If you capture before acceptance and a seller refuses, you’re refunding money you shouldn’t have taken.
- Polling gaps. Order updates fetched by date range miss changes if your clock and the marketplace’s disagree. Overlap the windows and de-duplicate.
- Cancellations from the customer. Decide whether a customer can cancel after a seller accepts, and which system enforces it.
- 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.
