Mirakl marketplace 3PL integration
ShipFlow for Mirakl
Many retailers run their marketplace on Mirakl. A seller on one of those marketplaces connects its own seller account to the warehouse that ships for it: orders awaiting acceptance become warehouse orders and are accepted, shipments and partial shipments go back with tracking, and offer quantities follow available stock. This page is written for sellers and for the warehouse team setting a connection up.
What the connection does
- The client connects from its warehouse's ShipFlow portal with its Mirakl seller API key and the marketplace's instance URL. ShipFlow checks the key against the marketplace before the connection is saved; a refused key saves nothing.
- Every ten minutes ShipFlow reads orders awaiting acceptance and orders to ship. Each becomes a warehouse order under the marketplace's order id, with the commercial id as the reference, the customer's shipping address and the shipping method the operator named. Lines are matched to warehouse items by the offer SKU, then by barcode, then by the connection's item links; anything that cannot be matched is held for a person, never guessed.
- When the warehouse order is created from an order awaiting acceptance, ShipFlow accepts every line in Mirakl. A client can switch automatic acceptance off; the order is then imported and flagged so someone accepts it in Mirakl before the operator's deadline.
- When the warehouse ships the whole order, ShipFlow sends the tracking and confirms the shipment. When part of the order ships, ShipFlow creates a Mirakl shipment for the lines and quantities that left and confirms that shipment; the rest follows when it ships. Partial shipments need the operator to have multi-shipment switched on for the marketplace; if it is not, the update is recorded as failed with that reason and nothing is lost.
- When available stock changes for an item on the connection, ShipFlow updates that offer's quantity. Stock is never read from Mirakl into the warehouse. Sending anything back can be switched off by the warehouse for the whole connection; while it is off, every outbound update is logged as skipped.
- Every poll, every acceptance, every shipment and every quantity update is a line in the run log the client and the warehouse both see, with the marketplace's answer when one failed.
What the client provides
| Item | Where to find it in Mirakl |
|---|---|
| Seller API key | The client's own key, one per seller user. In the Mirakl seller portal open the user menu at the top right and choose API key; generate one if none exists. The key is typed into the ShipFlow portal once, stored encrypted and never shown again. |
| Marketplace instance URL | The address the client uses to sign in to the seller portal, usually https://<operator>-prod.mirakl.net. Every marketplace runs its own instance, so the URL is entered per connection. |
| Shop ID | Only when one seller account covers several shops on the same marketplace. Settings, then Shop information, in the seller portal. Otherwise ShipFlow reads it from the account. |
The key is sent to the marketplace as the Authorization header on every call, over TLS, and is stored encrypted in the warehouse's ShipFlow tenant. If the marketplace ever rejects it, the connection is marked reconnect required on the client's card and in the warehouse's view; entering a current key clears it, and item links, the shipping map and history are kept.
Setup steps
Connecting runs three steps, each recorded with its result and shown on the connection's card with a Retry setup button:
- Seller account. The key is checked and the shop name and id are read. A failure here refuses the connection.
- Carrier list. The operator's carriers are copied to the connection's carrier map. The client pairs each Mirakl carrier code with a warehouse carrier; an unpaired carrier still ships, reported to Mirakl by name with a tracking link.
- Offers. The shop's offers are counted to confirm the offers API answers for this shop, so quantity updates will be accepted.
Shipping method names the operator sends land on the connection's shipping map, where the client pairs them with the warehouse's carrier and service. New orders keep coming in while methods are unpaired unless the warehouse asks for them to be held.
Seller API calls used
| Mirakl call | Endpoint | When ShipFlow uses it |
|---|---|---|
A01 | GET /api/account | On connect and on every test: proves the key and reads the shop name and id. |
SH11 | GET /api/shipping/carriers | On connect: the operator's carrier list is copied to the connection's carrier map so the client can pair each Mirakl carrier code with a warehouse carrier. |
OF21 | GET /api/offers | On connect: counts the shop's offers so the setup steps show the offers API answers for this shop. |
OR11 | GET /api/orders | Every poll (10 minutes by default): orders in WAITING_ACCEPTANCE and SHIPPING updated since the last poll, plus orders CANCELED since then. |
OR21 | PUT /api/orders/{order_id}/accept | After a WAITING_ACCEPTANCE order is created in the warehouse: every line accepted. Rejecting a held order from the portal sends the same call with every line refused. |
OR30 | GET /api/orders/refunds | Every poll: refund requests waiting on the seller are recorded as held items. Nothing is refunded from the warehouse. |
OR23 | PUT /api/orders/{order_id}/tracking | When an order ships complete: carrier code from the carrier map, or the carrier name and tracking link when unmapped, and the tracking number. |
OR24 | PUT /api/orders/{order_id}/ship | Right after the tracking call: the order is confirmed shipped. |
ST11 | POST /api/shipments | When part of an order ships: one shipment with the lines and quantities that left and the tracking. |
ST24 | PUT /api/shipments/ship | Right after the shipment is created: it is confirmed shipped. |
OF24 | POST /api/offers | When available stock changes for an item on the connection: the offer quantity for that shop SKU. |
Nothing else is called. ShipFlow does not create or edit offers, prices, products, messages or invoices, and reads no customer data beyond the ship-to on orders assigned to the warehouse.
Cancellations and refund requests
An order cancelled on the marketplace cancels the warehouse order while nothing has been picked. Once picking has started the cancellation is recorded as rejected with that reason, the order ships, and the seller settles it with the operator.
A customer's refund request is different: it is a money decision, so ShipFlow never acts on it. Each request appears in the client's Orders waiting list with the quantity, item, amount and Mirakl's reason, stays there through any retry, and is closed from the portal once the seller has decided it in Mirakl. No refund, no cancellation and no stock movement happens from the warehouse side.
Support
Sellers are supported by their warehouse first; the warehouse is supported by 3PL TechFlow at support@3pltechflow.com. See also ShipFlow for Shopify, the privacy policy and the security overview.