Mirakl Seller API

Mirakl Seller API

This connector uses the Mirakl Marketplace Platform (MMP) shop API, the same REST API on every marketplace that runs on Mirakl. Each marketplace operator has its own Mirakl instance, so one install covers one marketplace: install the connector once per marketplace you sell on (for example once for Leroy Merlin and once for Conforama) and give each install a name that says which one it is.

Setup (about 5 minutes per marketplace)

1. Sign in to the marketplace's seller back office (the Mirakl portal the operator gave you).
2. Copy the address of the portal without any path into MIRAKL_URL. The connector adds /api itself, so do not paste it. Addresses of common marketplaces:
   • Leroy Merlin (ADEO): https://adeo-marketplace.mirakl.net
   • BUT: https://but-prod.mirakl.net
   • Conforama: https://conforama-prod.mirakl.net
   • home24: https://home24.mirakl.net
   • Maisons du Monde: https://maisonsdumonde-prod.mirakl.net
   • Vente-unique: https://venteunique-prod.mirakl.net
   • ePrice: https://marketplace.eprice.it Other operators work the same way, also those on their own domain: use the address of the seller back office you sign in to.
3. Click your user name in the top right corner, open My user settings and the API Key tab, and generate a key (or copy the existing one). Paste it into MIRAKL_API_KEY. The key is sent as is in the Authorization header, without Bearer. Generating a new key invalidates the old one, so any other tool using it stops working.
4. Only if your user manages several shops on this marketplace (common on home24 and Vente-unique): set MIRAKL_SHOP_ID to the shop to work on (shown in the back office and in mirakl_get_account). Without it Mirakl uses your default shop.
5. Install and run mirakl_get_account.

Order workflow: a new order waits in WAITING_ACCEPTANCE. mirakl_accept_order accepts (or refuses) every line; after the customer is debited the order moves to SHIPPING. Then mirakl_update_tracking stores the carrier and tracking number (carrier codes come from mirakl_list_carriers) and mirakl_ship_order confirms the shipment (SHIPPED). Later states are TO_COLLECT, RECEIVED, CLOSED, REFUSED and CANCELED. Use mirakl_list_orders with order_state_codes=WAITING_ACCEPTANCE for the daily to-do list and has_incident=true for open incidents; mirakl_resolve_incident closes an incident on one order line once it is solved. Documents attached to orders (delivery notes, labels, customer invoices) are listed by mirakl_list_order_documents.

Writes: confirm first. mirakl_accept_order, mirakl_update_tracking, mirakl_ship_order, mirakl_resolve_incident, mirakl_accept_return, mirakl_receive_return, mirakl_update_offers, mirakl_reply_thread, mirakl_create_order_thread and mirakl_import_products act on the live marketplace. Before each call, show the user what will change (order id and lines, tracking number, offer SKU with the old and new price or stock, the message text and recipients) and wait for a yes. Refusing an order line cancels it for good. No tool here refunds, cancels orders or moves money; do that in the back office. mirakl_import_offers can delete offers (REPLACE mode deletes every offer missing from the file), so it is installed switched off.

Updating offers (prices and stock): mirakl_update_offers (OF24) replaces the whole offer. Every field you leave out is reset: a missing quantity becomes 0, a missing discount or description is deleted. Always read the offer first (mirakl_get_offer or mirakl_list_offers with sku) and send it back complete with only the intended change: shop_sku, product_id and product_id_type (from product_references), state_code, price, quantity, leadtime_to_ship, logistic_class (its code), min_quantity_alert, description, discount, all_prices, available_started / available_ended (read as available_start_date / available_end_date) and any offer_additional_fields. Leave update_delete empty or update. The call returns an import_id; the change is applied asynchronously, so check it with mirakl_get_offer_import before reading the offer again. Condition codes for state_code come from mirakl_list_offer_conditions, logistic class codes from mirakl_list_logistic_classes.

File imports: mirakl_import_products (P41) and mirakl_import_offers (OF01) take the URL of a CSV, XLSX or XML file in the operator's format; the connector downloads it and uploads it to Mirakl. Track them with mirakl_list_product_imports / mirakl_get_product_import and mirakl_list_offer_imports / mirakl_get_offer_import.

Returns: mirakl_list_returns (RT11) lists return requests. Where the operator lets the shop decide, mirakl_accept_return accepts or refuses one in WAITING_ACCEPTANCE and mirakl_receive_return confirms the goods arrived. Refunds stay in the back office.

Messages: mirakl_list_threads lists conversations (filter with entity_type=MMP_ORDER and entity_id=<order id> for one order; Mirakl refuses entity_id without entity_type), mirakl_get_thread reads one with its messages, mirakl_reply_thread answers (recipient CUSTOMER or OPERATOR) and mirakl_create_order_thread opens a new conversation on an order. Reason codes for topics come from mirakl_list_reasons; leave its locale empty unless you know the marketplace has that language (an inactive locale answers 400).

Money: mirakl_list_invoices (IV01) lists the operator's accounting documents and mirakl_list_transactions (TL02) the transaction lines (sales, commissions, refunds, payouts). On marketplaces with Enhanced Seller Invoicing IV01 returns no new documents; use mirakl_list_document_requests (DR11) and the transactions then.

Reference lists: mirakl_list_channels (country sites), mirakl_list_carriers, mirakl_list_shipping_zones, mirakl_list_shipping_methods and mirakl_list_logistic_classes change rarely; read them once per conversation.

Pagination: orders, offers, invoices and product imports page with max (at most 100) and offset. Threads, returns, transactions, document requests and offer imports return a next_page_token; pass it as page_token to get the next page (all other filters are then ignored) until it is missing.

Dates are ISO 8601, e.g. 2026-10-01T00:00:00Z; Mirakl answers in UTC.

Rate limits: Mirakl limits each API separately and the operator can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, mirakl_get_account and the reference lists about once a day. A 429 carries a Retry-After header with the seconds to wait; do not retry in a loop.

Errors: 401 means the key is wrong or belongs to another marketplace, 403 that your user lacks the right for this action, 404 that the order, offer or thread does not exist for this shop (or that MIRAKL_URL is not a Mirakl instance), 400 a wrong parameter or an order in the wrong state (the message names it, e.g. ORDER_INVALID_STATE).