I’ve spent a good part of the last few years connecting commerce platforms to Mirakl. This series is for developers and architects meeting a marketplace for the first time. Episode 1 is the mental model. Get this right and everything else is plumbing.
TL;DR
- The operator runs the marketplace and owns the storefront, the customer and usually the payment.
- Sellers (Mirakl’s API calls them
shops) list offers and fulfil orders. - Mirakl sits in the middle: the shared catalogue, the offers, the order split and the money owed to each seller.
- A product is the thing. An offer is one seller’s price, stock and shipping terms for it.
Three roles
- The operator runs the marketplace. Usually that’s the retailer whose website the customer sees. The operator owns the storefront, the customer relationship and usually the payment.
- Sellers (Mirakl calls them shops; its newer documentation says stores, but the API still says
shops) list offers and fulfil orders. They work in their own back office or through their own systems connected by API. - Mirakl sits in the middle: it holds the shared catalogue, the offers, the order split and the money owed to each seller.
Products and offers are different things
A product is the thing: a specific pair of headphones, with its title, images and attributes. An offer is a seller’s promise to sell that product at a price, with a stock level and shipping terms. One product can have many offers from many sellers. Your storefront shows the product, then chooses which offer to sell, usually the best price or the best-rated seller.
Sellers don’t sell products. They sell offers on products.
Who owns which data
- Catalogue: the operator decides the structure. Sellers propose products, and the operator approves them.
- Offers, price and stock: the seller.
- The customer and payment: the operator.
- Fulfilment: the seller, through Mirakl.
- Commission and payouts: Mirakl calculates them; the operator pays out, or a PSP does it for them.
Why this matters for an Adobe Commerce build
Adobe Commerce was built around one merchant selling its own stock. A marketplace breaks that assumption in three places: products with several offers, carts with several sellers, and orders that split into one order per seller. Most integration trouble comes from forgetting one of these.
How this series works
It runs in two parts, like the App Builder series. Episodes 1 to 3 are the foundations: this mental model, reading the API codes, and the order lifecycle that every integration has to get right. After that it becomes a developer log: I build marketplace integration pieces step by step with Claude Code, and publish a post whenever a piece works, on what worked, where the AI was wrong and the code I verified.
The first thing I’ll build in the developer log is an offer sync: Mirakl offers, with their prices and stock, brought into Commerce so the storefront can show them. It’s the piece every marketplace storefront needs before a single order can happen.
What’s next
Episode 2 is about reading the API codes: how offers, orders and shops move between your platform and Mirakl, and how to find your way around the API reference.
