Elbuz connects to your shop on a Mirakl marketplace (Leroy Merlin, Conforama, home24, Empik and others) by back office address and API key: it imports offers and orders, returns prices, stock and shipments.
When you need this:
- You sell on several Mirakl marketplaces: one template each, same mechanics.
- Unaccepted orders get canceled: Elbuz accepts new orders on every import.
- Prices and stock are calculated in Elbuz: the export sends them and lists new offers by barcode.
- You ship from your own warehouse: your status sends the tracking number, shipment or cancellation.
Where to start: copy the back office address and API key and paste them into a “Mirakl” import template.
What the Mirakl connection can do
- One connection for all Mirakl marketplaces: only the back office address and the key differ.
- Imports offers: name, brand, SKU, , price, stock and category.
- Orders with automatic acceptance: new orders are accepted on the marketplace, and the buyer's address is filled in on the next run.
- Prices and stock back to the marketplace: one file per run, with the result in the log.
- New offers: on existing marketplace product pages, by barcode.
- Shipment and cancellation: your order status sends the tracking number, shipment or cancellation to the marketplace.
What you need from the marketplace
You don't need to link an app: you paste the back office address and the key that the marketplace itself gives you. The “Connection” card has five fields; the first two are required.
1
Seller back office address2
Marketplace list3
Shop API key- Seller back office address — filled in automatically when a marketplace is picked from the list.
- Marketplace list — the dropdown opened by “Pick from list”, with Leroy Merlin selected.
- Shop API key — created in the marketplace back office under My user settings.
| Template field | What to enter |
|---|---|
| Marketplace seller back office address | The address you use to sign in to the seller back office. Required |
| Shop API key | The key from the seller back office. Required |
| Shop ID (if the key has several shops) | The shop number. Needed only if one key opens several shops |
| Offer condition code, default 11 (new) | The condition of your offers on the marketplace (a code from the marketplace's list of conditions; 11 means new). The import doesn't use it; the export for this marketplace takes it (export) |
| Lead time to ship, days (default 2) | How many days you take to ship an order. Also passed to the export for this marketplace |
Back office address
Open the marketplace seller back office and copy the whole address from the browser address bar. Elbuz cuts off the path after the domain and adds https:// if it's missing.
Some marketplaces are already in the app: the “Pick from list” button under the field shows Leroy Merlin, Conforama, BUT, Maisons du Monde, Vente-unique (all France), home24 (Germany), ePrice (Italy) and Empik Marketplace (Poland). The selected row is filled into the field, and you can edit it by hand.
The “Pick from list” button appears once the template has been saved. For a marketplace that isn't on the list (La Redoute, Decathlon, Castorama, Carrefour, MediaMarkt, PCComponentes and so on), enter the address from the browser.
API key
You create the key in the seller back office: your name → My user settings → API Key. You don't need Mirakl Connect for this: Elbuz works with the marketplace back office directly. A new key cancels the previous one, so after creating it, replace the key in both the import template and the export template.
After pasting the address and key, wait for “All changes saved” (the check uses saved values) and click “Test connection”. Elbuz requests the shop details and replies “Connection works. Mirakl ‹address› — ‹shop name› #‹number›”. If the shop isn't open on the marketplace, its state follows the number in brackets. A wrong key gives “Connection failed: HTTP 401: …”.
In a new template, “Active” and “Orders” are already on: within 5 minutes of saving the key, Elbuz starts fetching orders for the last 30 days and accepting them on the marketplace. Elbuz maps the marketplace statuses to yours by itself, by name; what came in and how it was mapped is shown in the template's “Order statuses” window. Want to check first? Clear “Orders”.
The methods Elbuz uses are described on the Mirakl Developer Portal, in the Seller API section for the Mirakl Marketplace platform.
What goes into the product card
Elbuz pulls the list of your offers on the marketplace, in pages of 100, and saves each one to the base catalog as a product card.
| Mirakl offer data | Product field in Elbuz |
|---|---|
| product name | Name |
| brand | Manufacturer |
| your offer code (shop SKU) | SKU |
| product EAN (or GTIN, UPC) | Barcode |
| offer price | Price |
| original price of a discount, if it's higher than the price | Old price |
| quantity | Quantity |
| active or not | Status: an active offer means an enabled product |
| category name | Category, found by name or created |
An offer has no description, photos or specifications, so they don't come into the card from Mirakl. The “Photo”, “Attributes” and other checkboxes don't affect a Mirakl template; only “Products” and “Orders” do. An offer without a category goes into the service category “Products - mirakl”, which is created disabled and excluded from exports (service categories).
1
Products2
Orders- Products — the offer catalog is imported from the marketplace.
- Orders — new marketplace orders are imported and accepted.
What a repeat run overwrites
A repeat import finds its card by the offer code this template stored last time, and a card without that link by name. The run changes the card it finds as follows:
| What the run does | Fields |
|---|---|
| Always overwrites | quantity, the “enabled” flag |
| Overwrites if the marketplace sent a non-empty value | name, manufacturer, SKU, barcode, price, old price |
| Leaves alone | description, photos, specifications |
To stop the run from touching a card at all, turn on the “Do not update” switch in it (the “Import protection” section); to protect only prices, use “Fixed Price”. An offer that wasn't in the run stays in the catalog with its last price and stock.
How orders arrive and get accepted
An order is saved as an unposted “Customer order” document. The first import takes orders from the last 30 days. After that, Elbuz takes orders changed since the date in the “Import orders from date (YYYY-MM-DD)” field of the “Advanced” block, with a 12-hour margin. An existing order is recognized by its number and updated, not duplicated.
The document gets the order number, creation and change dates, the buyer's name, phone and email, the delivery and billing addresses, the delivery and payment methods, the delivery cost, the currency and the line items. The document total includes delivery. If an order has several lines, canceled and refused lines don't go into the document.
Automatic acceptance
An order waiting for your confirmation (status WAITING_ACCEPTANCE) is accepted on the marketplace by Elbuz, with all its lines, during the same import. Stock in the warehouse isn't checked. Such an order goes into the document with the marketplace status SHIPPING.
If acceptance fails, the log shows a red line “Mirakl: order ‹number› was not accepted automatically — ‹reason›”, and the order is still imported in its current status. The next import tries again: Elbuz checks orders waiting for acceptance every time, whatever the last import date. If the marketplace keeps refusing, accept the order in its back office.
The marketplace treats an accepted order as confirmed by you. If the product is out of stock, cancel the order with a status mapped to CANCELED (shipment and cancellation) or in the marketplace back office.
Why a new order has no address
Some marketplaces show the buyer's address and phone only after the order is accepted. In that case the document is created without them, and the next import fills in the empty fields, both in the document and in the contact card. A repeat import doesn't overwrite fields a manager has already filled in or corrected.
Order statuses
Elbuz maps the marketplace status to yours by itself — by code or name; an unrecognized one becomes “New”. To refine the mapping, use the “Order statuses” button in the “Related settings” card of the import template: enter the Mirakl code in the “Code (name) on site (API)” column next to your status.
1
Schedule setup2
Order statuses- Schedule setup — the catalog schedule; orders are fetched every 5 minutes by the shared task.
- Order statuses — opens the mapping of marketplace statuses to yours.
| Mirakl code | What it means |
|---|---|
WAITING_ACCEPTANCE | Waiting for the seller to accept |
SHIPPING | Accepted, waiting to be shipped |
SHIPPED | Shipped |
RECEIVED | Received by the buyer |
CLOSED | Closed |
CANCELED | Canceled |
REFUSED | Refused |
1
Code (name) on site (API)2
Mirakl status codes- Code (name) on site (API) — the column where you enter the marketplace order status code.
- Each of the seven Mirakl statuses (WAITING_ACCEPTANCE, SHIPPING, SHIPPED, REFUSED, RECEIVED, CLOSED, CANCELED) is matched to one of your order statuses.
The same mapping works in the other direction too: the export sends to the marketplace a status mapped to SHIPPED or CANCELED. If a cell has several comma-separated codes, the first one goes to the marketplace.
A repeat import changes your status only if the marketplace status has changed since last time or nobody has changed the document status since the import. What happens to a posted order and its reservation is covered in importing orders via API.
How prices and stock go back to the marketplace
The reverse direction is a separate export template of the same type, with two fields: “Marketplace back office address” and “Shop API key”. Shop ID, condition code and lead time to ship come from the import template for the same marketplace (matched by back office address). Without an import template: no Shop ID, condition 11 (new), 2-day lead time.
If you sell on several Mirakl marketplaces, create a pair of templates for each. Product links are separate per marketplace: a product linked to one marketplace goes to another as a new offer by barcode.
1
Marketplace back office address2
Shop API key3
Description language- Marketplace back office address — the seller back office address of the Mirakl marketplace, copied from the browser address bar.
- Shop API key — the key created in the marketplace back office under your user settings.
- Description language — the language in which product descriptions are sent.
The export updates products linked to offers, so first import the catalog from the marketplace once. Without the “Publish new products” checkbox, an unlinked product is skipped with no line in the log. What goes to the marketplace:
- Price: the number from the export template, with two decimal places, no less than zero. Elbuz doesn't convert currencies: prices in the filtered set must be in your marketplace shop's currency.
- Stock: the product quantity, no less than zero.
- Condition and lead time to ship: from the “Offer condition code” and “Lead time to ship” fields of this marketplace's import template.
- Which products: set by the export template's filtered set, as for other channels.
Why the result doesn't come right away
Mirakl takes changes not one offer at a time but as one file per run, and processes it for a few minutes. Elbuz sends the file and waits about a minute for the result. If it doesn't get one, the marketplace processes the file without Elbuz, and the log keeps a “…still being processed…” line.
| What's in the log | What it means |
|---|---|
| “Mirakl: file ‹number› sent, lines: N” | The file went to the marketplace |
| “Mirakl: file ‹number› is still being processed (‹state›), result on the next run” | A minute wasn't enough; the marketplace processes the file without Elbuz |
| “Mirakl: file ‹number› processed — succeeded: N, errors: M” | The file's result |
| “Mirakl: "name" (code) rejected: reason” | The marketplace rejected a line; the reason is in the marketplace's words |
| “Mirakl: prices and stock — succeeded: N, errors: M” | The run summary |
The summary counts only lines whose result has already arrived. A zero right after “still being processed” isn't a failure, just waiting. The export sends products that stay in the filtered set on every run, so a product fixed after a rejection goes with the next file.
Elbuz can't remove offers: a product that drops out of the filtered set simply stops being updated. To stop selling, export zero stock or remove the offer in the marketplace back office.
New offers by barcode
With the “Publish new products” checkbox, Elbuz lists an offer for a product that has none on the marketplace yet. The offer attaches to an existing marketplace product page by EAN, so the product needs a barcode of at least 8 digits. Elbuz doesn't create product pages on Mirakl: if no page has that EAN, the marketplace rejects the line.
1
Products2
Publish new products3
Orders- Products — sends prices and stock for the products already offered on the marketplace.
- Publish new products — creates offers on marketplace products matched by barcode.
- Orders — sends shipment with the tracking number and cancellation to the marketplace.
- Offer code: the product SKU. With no SKU, or an SKU longer than 40 characters, the product ID in Elbuz.
- No barcode: the line “Mirakl: product "…" has no barcode (EAN), offer not created”, and the product counts as an error.
- While the marketplace processes a new offer, the product isn't included in the next files; the log shows “Mirakl: new offers still being processed by the marketplace: N”.
- Published: the line “Mirakl: offer "name" (code) published”; the product is linked to the offer.
- Rejected: the link is removed, and the next run tries to list the product again.
Shipment, tracking number and cancellation
The “Orders” checkbox in the export template sends two events from your Mirakl orders to the marketplace:
| Your status is mapped to | What Elbuz sends |
|---|---|
SHIPPED | The tracking number (if filled in) and shipment confirmation |
CANCELED | Order cancellation |
The mapping comes from the “Order statuses” window of the import template, so you don't need to set it up separately in the export. The export works with the orders of the import template that has the same marketplace address.
Tracking number: the “Delivery service: number” field in the document's “Delivery” card (expand “More fields”). The carrier comes from the “Delivery types” button of the import template if a marketplace carrier code is mapped there; otherwise Elbuz sends the delivery service name from the document. If the number field is empty, the marketplace gets the shipment without a tracking number.
Each event is sent once: after sending, Elbuz stores the new marketplace status, and a repeat run leaves the order alone. Orders already shipped, received, closed, canceled or refused on the marketplace aren't sent either. The log shows lines “Mirakl: order ‹number› → SHIPPED” and the summary “Mirakl: order statuses sent: N, errors: M”.
You can mark an order as shipped while it's in SHIPPING status, and cancel it while the marketplace allows it. Otherwise the log shows the line “Mirakl: order ‹number› → SHIPPED not sent — HTTP 400: …” with the marketplace's explanation.
Scheduled updates
Mirakl doesn't send instant notifications, so Elbuz fetches and accepts orders by itself every 5 minutes if “Orders” is checked in the template and the key is filled in. This is done by the shared “Marketplace orders” task in the “Job schedule” window, where you can also change the interval. The catalog isn't imported in this pass, and orders also picked up by the template's own schedule aren't duplicated.
The catalog is updated by the template's own schedule — the “Schedule setup” button in the “Related settings” card. Set it to run rarely, for example at night: while the catalog is running, the orders pass is skipped until the next one. The marketplace takes a few minutes to process an export file, so running the export more often than it can process the file makes no sense.
The marketplace limits the number of requests. When a request is refused over the limit, Elbuz waits and retries up to three times. If that doesn't help, the log shows “Mirakl: marketplace request limit exceeded, try again later — …”. This isn't a key error: just run the template later.
The “Active” / “Disabled” badge takes the template off the schedule and out of automatic order fetching (disable a template). The export is a separate template with its own switch.
If a run breaks off
- The catalog is written in batches of 500 offers: whatever got saved is updated, the rest keeps the old data.
- Orders are saved in one go after all pages are read; the date for the next batch moves only after saving, so a retry picks up the same interval. Orders already accepted aren't accepted again.
- Export: the marketplace processes a sent file without Elbuz; the next run sends prices and stock again.
A retry is safe. General rules: if a run breaks off.
Scenarios
Move the marketplace catalog into Elbuz
What to turn on. Fill in “Marketplace seller back office address” and “Shop API key”, click “Test connection” after “All changes saved”, and keep “Products” in the “Select data to import” card.
What you get. Each offer becomes a card with a name, brand, SKU, barcode, price, stock and category. Add the description and photos in Elbuz or from another source.
Accept orders and ship from Elbuz
What to turn on. In the import template: the “Orders” checkbox, the mapping via the “Order statuses” button (at least SHIPPING, SHIPPED, CANCELED); orders need no schedule — they arrive by themselves every 5 minutes. In the export template with the same address: the “Orders” checkbox.
What you get. New orders are accepted on the marketplace automatically, and the buyer's address appears on the next run. A manager enters the tracking number in “Delivery service: number” and sets the status mapped to SHIPPED; the next export sends the shipment.
The marketplace as a channel for a catalog you manage in Elbuz
What to turn on. Run the import once with the “Products” checkbox: it links cards to offers. After that, keep only “Orders” in the import template, otherwise the catalog run will overwrite price and stock with the marketplace's figures. In the export template: “Products”, plus “Publish new products” if needed.
What you get. Prices and stock of linked products go to the marketplace as a file, and products with a barcode but no offer are listed on existing marketplace product pages.
What to do when the marketplace won't send or accept data
| What you see | Why | What to do |
|---|---|---|
| “Connection failed: HTTP 401: …” | The key was copied incompletely, deleted in the back office, or belongs to another marketplace | Create the key again and paste it together with the address of the same marketplace (API key) |
| “Mirakl: enter the marketplace back office address and the shop API key” | The address or key is empty | Fill in both fields (what you need from the marketplace) |
| “Mirakl: marketplace request limit exceeded, try again later — …” | The request limit is still exhausted after three retries | For the orders pass, increase the interval of the “Marketplace orders” task; for the catalog, run it less often (schedule) |
| “Mirakl: order ‹number› was not accepted automatically — …” | The marketplace refused acceptance | The next import tries again. If the line keeps coming back, accept the order in the marketplace back office (acceptance) |
| “Mirakl: product "…" has no barcode (EAN), offer not created” | A new offer attaches to a marketplace product page by EAN | Fill in a barcode of 8 digits or more in the product (new offers) |
| “Mirakl: "…" (…) rejected: …” | The marketplace rejected a file line: no product page with that EAN, an unacceptable price and so on | Fix the cause given in the line; the export sends the product again |
| You changed the price, but the marketplace still shows the old one | The file is still being processed or waiting for the next run | Find the “…still being processed…” line in the log and check the price in the marketplace back office a few minutes later (file result) |
| “Mirakl: order ‹number› → SHIPPED not sent — HTTP 400: …” | The order on the marketplace is in the wrong state: not yet accepted or already closed | Check the order state in the marketplace back office (shipment) |
| You changed the status, but nothing went to the marketplace | The status isn't mapped to SHIPPED or CANCELED, the export has no “Orders” checkbox, or it has a different marketplace address |
Check the mapping in the import template and the checkbox in the export template (shipment) |
FAQ
My marketplace isn't on the address list. Can I connect it?
Yes, if it runs on Mirakl. Copy the seller back office address from the browser address bar (back office address).
Can I turn off automatic order acceptance?
No, the Mirakl order import always accepts orders waiting for acceptance. If you don't want that, clear the “Orders” checkbox and accept orders in the marketplace back office (acceptance).
Why doesn't the order have the buyer's address?
The marketplace provides it after acceptance. The next import fills in the address and phone (address).
Why don't products from Mirakl have a description and photos?
An offer doesn't contain them, and Elbuz imports offers. Add the description and photos in Elbuz or from another source (what gets imported).
Does Elbuz create new product pages on the marketplace?
No, only offers on existing product pages, by barcode. Create the new product page in the marketplace back office, and the export will then attach an offer to it (new offers).
My catalog prices are in hryvnias. What goes to the marketplace?
The same number, with no currency conversion. Prices in the export template's filtered set must be in the marketplace shop's currency (export).
Where to find it and who has access
- Menu
- Directories → Operations → Data import → new template of type “Mirakl (Leroy Merlin, Conforama, home24…)”
- Other entry points
- Directories → Operations → Data export: a template of the same type for prices, stock and statuses
- Access right
- the “Import” window in “Group permissions”
- Have ready
- the marketplace seller back office address and the shop API key
One template = one marketplace. If you sell on both Leroy Merlin and Conforama, create two templates with different addresses.
Related topics
- If you need the general import mechanics (schedule, broken-off runs, service categories): data import overview.
- If a manager handles orders in Elbuz and it matters what a run overwrites: importing orders via API.
- If you also sell on Cdiscount or Kaufland: connecting Cdiscount, connecting Kaufland.
