↑↓ selectEnter openEsc close

    1. Elbuz
    2. European marketplaces

    How to connect Mirakl to Elbuz: Leroy Merlin, Conforama, home24 with one template

    8 min readUpdated

    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

    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.

    Mirakl import template, Connection card with a marketplace picked from the list
    1Seller back office address
    2Marketplace list
    3Shop API key
    1. Seller back office address — filled in automatically when a marketplace is picked from the list.
    2. Marketplace list — the dropdown opened by “Pick from list”, with Leroy Merlin selected.
    3. Shop API key — created in the marketplace back office under My user settings.
    Template fieldWhat to enter
    Marketplace seller back office addressThe address you use to sign in to the seller back office. Required
    Shop API keyThe 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 dataProduct field in Elbuz
    product nameName
    brandManufacturer
    your offer code (shop SKU)SKU
    product EAN (or GTIN, UPC)Barcode
    offer pricePrice
    original price of a discount, if it's higher than the priceOld price
    quantityQuantity
    active or notStatus: an active offer means an enabled product
    category nameCategory, 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).

    Select data to import card with only Products and Orders checked
    1Products
    2Orders
    1. Products — the offer catalog is imported from the marketplace.
    2. 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 doesFields
    Always overwritesquantity, the “enabled” flag
    Overwrites if the marketplace sent a non-empty valuename, manufacturer, SKU, barcode, price, old price
    Leaves alonedescription, 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.

    Related settings card with schedule and status buttons
    1Schedule setup
    2Order statuses
    1. Schedule setup — the catalog schedule; orders are fetched every 5 minutes by the shared task.
    2. Order statuses — opens the mapping of marketplace statuses to yours.
    Mirakl codeWhat it means
    WAITING_ACCEPTANCEWaiting for the seller to accept
    SHIPPINGAccepted, waiting to be shipped
    SHIPPEDShipped
    RECEIVEDReceived by the buyer
    CLOSEDClosed
    CANCELEDCanceled
    REFUSEDRefused
    Order statuses window with Mirakl status codes in the site code column
    1Code (name) on site (API)
    2Mirakl status codes
    1. Code (name) on site (API) — the column where you enter the marketplace order status code.
    2. 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.

    Mirakl export template form: the Connection card with the help text, back office address, shop API key and description language
    1Marketplace back office address
    2Shop API key
    3Description language
    1. Marketplace back office address — the seller back office address of the Mirakl marketplace, copied from the browser address bar.
    2. Shop API key — the key created in the marketplace back office under your user settings.
    3. 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 logWhat 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.

    The «What to export» card of the Mirakl export template with Products, Publish new products and Orders ticked
    1Products
    2Publish new products
    3Orders
    1. Products — sends prices and stock for the products already offered on the marketplace.
    2. Publish new products — creates offers on marketplace products matched by barcode.
    3. 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 toWhat Elbuz sends
    SHIPPEDThe tracking number (if filled in) and shipment confirmation
    CANCELEDOrder 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

    Common problems
    What you seeWhyWhat 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

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free