Skip to content
P2Lab Mirakl

Connections

A connection represents a single Mirakl marketplace your shop sells on. Every piece of data the plugin manages — categories, attributes, offers, orders, invoices and logs — belongs to one connection. This lets you sell on several marketplaces from the same Shopware store while keeping each operator’s data cleanly separated.

What information a connection stores

Section titled “What information a connection stores”

When you add a connection in the wizard, you provide:

  • Connection Name — a label that helps you recognize this operator across the plugin (for example Marketplace EU or Marketplace UK).
  • Instance URL — the web address of the operator’s API, supplied by the operator (for example https://marketplace.example.com).
  • API Key — your seller API key, generated in the operator’s seller dashboard. Treat it like a password.
  • Shop ID — the numeric shop identifier the operator assigned to your seller account.
  • Sales Channel — the Shopware sales channel that will be used to create imported orders. Its currency, language and shipping methods are used for those orders, so it must match the operator’s region.
  • Default Offer State (optional) — the offer state used when a product is synced as a new offer and the product itself does not specify one. You can change this later in the Edit Connection modal or override it per product.

The plugin also stores several mappings per connection — order status mapping, document auto-upload mapping, variant name format and others. These are configured through dedicated dialogs in the row’s context menu after the connection has been created.

Where to manage connections

Section titled “Where to manage connections”

Open Mirakl → Settings → Connections to see all configured marketplaces. To create a new one, click the Add Connection button at the top of the list — this opens the setup wizard (13 steps).

Each row has a context menu (three dots on the right) with the following actions:

  • Edit — opens the Edit Connection modal, where you can change credentials and basic settings. The modal footer has additional buttons for Run Setup Wizard, Test Connection, Cancel and Save.
  • Run Setup Wizard — re-opens the wizard for an existing connection, starting from step 2 (Categories). Use this to refresh the operator’s reference data or redo your mappings.
  • Order Status Mapping — opens a dialog where you configure how each Mirakl order status maps to Shopware order, shipping and payment statuses.
  • Reverse Status Mapping — opens a dialog where you configure which Shopware status transitions trigger which Mirakl actions (accept, ship, refuse).
  • Document Auto-Upload — opens a dialog where you map Shopware document types to Mirakl document types for automatic upload.
  • Variant Name Format — opens a dialog where you customize how product variant names are built when sent to Mirakl.
  • Catalog Export — opens the Catalog Export page for this connection, where you can generate a CSV file of your products for the operator’s catalog mapping wizard.
  • Test Connection — sends a small test request to the operator using the saved URL and API key. The result updates the connection’s status (see below).
  • Delete — removes the connection and everything linked to it, after a confirmation dialog.

Connection statuses

Section titled “Connection statuses”

Each connection has one of three statuses, shown in the Status column on the list:

  • Connected — the most recent test request to the operator succeeded. Scheduled background tasks will run for this connection.
  • Disconnected — the connection has not been verified yet, or has been intentionally left in a non-running state. Scheduled tasks skip it. A new connection always starts in this state.
  • Error — the most recent test or sync request failed. Hover over the status (or open Edit Connection) to see the operator’s error message. Fix the credentials and click Test Connection to retry.

Only connections in the Connected state participate in scheduled background tasks. Leaving a connection in Disconnected or Error effectively pauses it — all historical data is kept and no syncs run.

The setup wizard does not wait for the test to finish before letting you continue. It saves the connection in Disconnected state, starts a quick test in the background, and moves on to step 2 (Categories). The test result appears on the connections list as soon as it completes.

Running several connections at once

Section titled “Running several connections at once”

You can connect to as many marketplaces as you have seller accounts for. Each connection keeps:

  • Its own copy of the operator’s reference data — categories, attributes, offer fields, offer states, reason codes. Refreshing one connection’s data does not affect any other.
  • Its own synchronization progress for every feature — offers, orders, messages, documents, invoices, transaction logs. Pausing one connection does not disturb the others.
  • Its own mappings. The same Shopware category “Shoes” can map to category 1234 on operator A and 5678 on operator B without any conflict.

Deleting a connection

Section titled “Deleting a connection”

Delete removes the connection and everything tied to it — mappings, the operator’s reference data, synchronization state. The Shopware orders themselves are kept, but their links back to Mirakl are removed: they will no longer receive status updates from the operator.

Delete a connection only when you are certain you no longer need its history. There is no undo.

Choosing the right sales channel

Section titled “Choosing the right sales channel”

The Sales Channel matters most for order import. Imported orders are created in the context of this sales channel, so its currency, language and shipping methods must make sense for the marketplace’s region. If you sell on a French operator, link a French sales channel.

The Default Offer State is independent of the sales channel — it is the fallback offer state used when a product is synced as a new offer without its own state. Set it in the Edit Connection modal or during wizard step 4.

To override it for a specific product, open the product (Catalogues → Products → select product) and go to the Specifications tab. In the Mirakl Marketplace section, for each configured connection there is a separate Offer State (connection name) dropdown. Pick a value to override; leave it empty to keep the connection’s default. The override is stored on the product, not on the connection, so different connections can have different overrides for the same product.

Section titled “Related”