Shipping Mappings

When you ship a Mirakl order from Shopware, the operator expects a carrier code alongside the tracking number — “DHL”, “GLS”, “DPD” or whatever the operator-side list calls it. Shopware doesn’t natively know about Mirakl’s carrier list, so the plugin needs a mapping: this Shopware shipping method → that Mirakl carrier code.

This page is where you define those mappings.

Where to find it

From the Dashboard, open the Quick Start card and click the Shipping Mappings tile. This opens the Shipping Mappings page.

What you see

The grid lists every mapping you’ve defined. Columns:

Column	Meaning
Shipping method	The Shopware shipping method this mapping applies to.
Scope	Either Global (all connections) or Per-connection with a specific Mirakl connection picked.
Countries	If the mapping is restricted to specific countries, they show here.
Default	Whether this is the default fallback for shipping methods that have no specific mapping.
Created	When the mapping was added.

The sidebar has filters:

• Shipping method — free text.
• Default — show only default fallbacks.
• Scope — filter by Global vs Per-connection.
• Connections — filter by Mirakl connection.
• Countries — filter by destination country.

How matching works

When the plugin needs to report a shipment to Mirakl, it walks the mappings in this order:

1. Per-connection mapping matching this connection, this shipping method and the order’s destination country.
2. Per-connection mapping matching this connection and this shipping method (any country).
3. Global mapping matching this shipping method.
4. Default fallback — whichever mapping has the Default flag set.

The first match wins. If nothing matches and no fallback is defined, the plugin can’t push the ship confirmation — set up a Default fallback to avoid that.

Per-row actions

• Edit — modify the mapping (shipping method, scope, countries, carrier code).
• Delete — confirmation: “Are you sure you want to delete this mapping?”

The toolbar Create button opens a blank mapping form.

Tips & gotchas

Tip

Add a Default fallback mapping first thing — a single global row marked Default with the carrier you ship with most often. Then add overrides for specific shipping methods or countries as needed.

Caution

The carrier codes must match the operator’s list exactly. Different Mirakl operators publish slightly different lists — check the operator’s documentation or the Carriers reference data on their panel before saving a mapping.

Note

Mapping the scope to Per-connection is useful when different operators on different Mirakl connections expect different carrier codes for the same Shopware shipping method (e.g. operator A wants “DHL”, operator B wants “DHL_EXPRESS”).

Related

• Order state sync — when ship confirmations reach the operator
• Order import — orders arrive with the operator’s chosen shipping zone
• Connections — per-connection settings