Mirakl’s API reference is large, and at first it looks like a wall of codes. Once you see the pattern, finding the right call takes seconds. This episode is a guided tour, from the operator’s side, which is where an Adobe Commerce integration usually sits.
The naming pattern
Every API has a short code: letters for the area, then a number. Offers start with OF, orders with OR, products with P, shops with S, and so on. The reference in your Mirakl instance lists them all. Learn the area letters, and you can guess where to look.
Two kinds of credentials
- Operator API keys act for the marketplace as a whole. Your Commerce integration uses one of these.
- Shop API keys act for one seller. Sellers’ own systems use these. Your integration should never need one.
The key goes in the Authorization header on every request. Mirakl's current docs mark the bare key as deprecated in favour of bearer tokens (a back-office access token or OAuth 2.0), but it still works. A safe first call is listing shops:
curl -s "https://<your-instance>.mirakl.net/api/shops?max=10" \
-H "Authorization: $MIRAKL_OPERATOR_KEY" -H "Accept: application/json"
The four flows that matter first
- Offers to the storefront. Pull offers (price, stock, seller) into Commerce so customers can see and buy them. Use the incremental exports, not full pulls, once you’re live.
- Orders to Mirakl. When a customer checks out, the operator creates the order in Mirakl, which splits it into one order per seller.
- Order updates back. Sellers accept, ship and sometimes refuse. Your platform polls or receives these updates and shows them to the customer.
- Shops. Seller details for display: name, rating, shipping and return policies.
Read the API reference in your own instance, not a copy. Versions and options differ.
Habits that save time
- Log the request and response for every call in staging. Mirakl’s error messages are usually precise; you just have to keep them.
- Use the date filters on list calls, and store the last sync time on your side.
- Respect the documented rate limits, and back off on 429 responses, waiting as long as the
Retry-Afterheader says.
What’s next
Episode 3 is the big one: one customer order becoming several seller orders, and deciding which system owns each status.
