Connecting Mirakl

A Connection is the unit of integration in P2Lab Mirakl. It links one Mirakl marketplace to one Shopware sales channel and stores all the marketplace-specific data — categories, attributes, mappings, sync state — needed to keep them in sync. You can have several connections side by side, one per marketplace.

The plugin sets up a new connection through a 13-step wizard that guides you from credentials all the way to the first catalogue export. Optional steps can be skipped and configured later, and you can re-run the wizard against an existing connection to refresh its reference data without re-typing the credentials.

What you need from the marketplace

Instance URL — the marketplace’s seller API web address (for example https://marketplace.example.com). The marketplace gives you this once your seller account has been approved.
API Key — a long opaque string the marketplace generates in your seller dashboard (typically under My account → API key). Treat it like a password.
Shop ID — the numeric shop identifier the marketplace assigns to your seller account. You can see it in your seller portal profile.

You also need a Shopware Sales Channel that will own the imported orders.

Where to find the plugin in the admin

The plugin adds one entry to the main Shopware admin sidebar, under the Catalogues group, labelled Mirakl (blue shopping-bag icon). Clicking it opens the Dashboard.

The Dashboard’s Quick Start card has a tile for every page (Offers, Catalog, Orders, Categories, Attribute Mappings, Offer Field Mappings, Invoices, Transaction Logs, Logs, API Logs, Settings, …). Click Settings to open the Settings page, which has three tabs: Connections, Sync Settings and Options.

Until you have created your first connection, the Dashboard also shows a Setup Status section with linked steps (Configure Connection, Map Categories, Add Products to Catalog, …). Once the connection is set up, this section is replaced by a short Mirakl Integration description and you navigate exclusively through the Quick Start tiles.

Open the wizard

Open Mirakl → Settings → Connections and click Add Connection at the top of the list. The wizard opens at step 1.

You can re-open the wizard for an existing connection from its row’s context menu (three dots on the right) — pick Run Setup Wizard. This skips step 1 (credentials) and starts at step 2, so you can refresh the marketplace’s reference data and redo mappings without re-typing anything.

Step 1 — Connection

Enter your credentials and pick the target sales channel:

Connection Name — a label you’ll recognise, for example ManoMano FR. Use distinct names that include the marketplace name and the country, so they’re easy to tell apart in dropdowns elsewhere in the plugin.
Instance URL — paste the marketplace’s web address.
API Key — paste your seller API key (the field hides the value but you can copy it).
Shop ID — paste the numeric shop identifier.
Sales Channel — pick the Shopware sales channel that orders from this marketplace will be created in.

All five fields are required. The footer has two buttons:

Test Connection — sends a small test request using the URL and key (without saving) and reports either success or the marketplace’s error message.
Save & Continue — saves the connection (in Disconnected state), kicks off a test in the background and advances to step 2. A successful test changes the status to Connected; a failure changes it to Error. You don’t have to wait for the test — the result will appear on the connections list as soon as it’s ready.

Step 2 — Categories

The wizard kicks off a background task that pulls the marketplace’s full category tree (on large marketplaces this can be tens of thousands of entries) and links it to this connection. A progress bar shows how many items have been processed out of the total. When the task finishes you see:

N categories linked to connection — the total available after the refresh.
N new categories added — only shown when the refresh found previously unseen entries.

Click Next when the task is done.

Step 3 — Product Attributes

Same pattern as the previous step: a background task pulls every product attribute the marketplace defines (with allowed values and rules) and links them to the connection. When it finishes, it reports N product attributes linked to connection and N new attributes added.

Step 4 — Offer States

Pulls the offer state values the marketplace accepts (such as new or used-good). After the refresh, a Default Offer State dropdown appears — pick the value to use as the fallback when sending new offers (you can override it per product later). Your choice is saved when you click Next.

Step 5 — Reason Codes

Pulls the refusal and return reason codes the marketplace defines. These are not pre-mapped — they’ll be shown to you at the moment you refuse or process a return, so you can pick the right one.

Step 6 — Offer Fields

Pulls the offer field definitions the marketplace expects on each offer (price, stock, lead time, EAN, etc.). You’ll map these to Shopware fields in the next step.

Step 7 — Offer Field Mappings

Initial mapping between Shopware fields and Mirakl offer fields. Three buttons in the footer:

Skip — leave the connection without mappings; you can configure them later in Settings.
Apply Defaults — fill in a set of sensible default mappings. Already-existing mappings aren’t overwritten.
Import JSON — upload a mapping file previously exported from another shop’s connection. The wizard then reports how many mappings were imported, replaced, skipped, and how many fields couldn’t be found in this connection.

Step 8 — Auto-Map Attributes

The plugin can try to link marketplace product attributes to matching Shopware fields, custom fields, property groups and categories by comparing names. Three buttons in the footer:

Skip — configure attribute mappings manually later in Settings.
Import JSON — upload an attribute-mapping file previously exported from another shop. The wizard reports imported / replaced / skipped / missing counts.
Run Auto-Map — kicks off a background task with a progress bar. When it finishes, it reports how many new mappings were created, how many existing ones were linked, and how many attributes were skipped because no good match was found.

Step 9 — Order Status Mapping

Configure how marketplace order statuses map to Shopware order, shipping and payment statuses (for example, the marketplace’s Shipping status corresponds to a Shopware order in progress with shipping state Shipped). Sensible defaults are pre-filled. Pick — on any row to leave the matching Shopware status unchanged. The mapping is saved when you click Next.

Step 10 — Reverse Status Mapping

The other direction: which Shopware status changes trigger actions on the marketplace (accept, ship, refuse). For example, marking a Shopware order as Completed can trigger a ship confirmation on the marketplace. Pick — to disable a row. Saved when you click Next.

Step 11 — Document Auto-Upload

Decide which Shopware document types (invoice, delivery note, credit note, …) should be automatically uploaded to the marketplace whenever they’re generated:

A switch turns the whole feature on or off for this connection.
When the switch is on, a small editor lets you pair each Shopware document type with a Mirakl document type. Unpaired types aren’t uploaded.

Saved when you click Next.

Step 12 — Import Orders

Decide how far back to pull historical orders from the marketplace:

Import all historical orders — pulls everything the marketplace’s API will return.
Import orders from a specific date — a date picker; only orders created on or after that date are imported.

When you click Next, the chosen date is saved on the connection and an order-import job is started immediately. Messages for the imported orders are then pulled automatically in the background.

Step 13 — Catalog Export

The last step. The wizard tells you that:

The connection setup is complete.
To enable product imports on the marketplace’s side, you need to configure the Catalog Mapping in your Mirakl marketplace using a CSV with your products.
You upload the generated CSV in Mirakl under Settings → Catalog mapping → Use the mapping wizard.

Clicking Finish closes the wizard and takes you to the Catalog Export page for this connection, where you can generate the CSV.

Test the connection later

You can re-test the credentials at any time:

From the Connections list — the row’s context menu → Test Connection.
From the Edit Connection modal — the Test Connection button in the modal’s footer.

A successful test sets the status back to Connected; a failure sets it to Error and shows the marketplace’s error message in a notification.

Edit a connection later

From the row’s context menu, Edit opens a modal where you can change the Connection Name, Instance URL, API Key, Shop ID, Sales Channel and Default Offer State. The modal’s footer also has Run Setup Wizard (re-runs the wizard from step 2) and Test Connection shortcuts.

The per-feature settings that aren’t in the basic Edit Connection modal — Order Status Mapping, Reverse Status Mapping, Document Auto-Upload, Variant Name Format, Catalog Export — each have their own entry in the same context menu and open a dedicated dialog or page.

Several connections at once

You can connect to several Mirakl marketplaces from the same Shopware shop — each one with its own Instance URL, API Key, Shop ID and its own copy of the marketplace’s reference data. Mappings (categories, attributes, offer fields) are stored per Connection, so the same Shopware category can map to completely different marketplace categories on different connections without any conflict.

Next: first sync

Continue with First sync to send your first batch of products out.