First sync

By this point you should have a connection with status Connected and refreshed reference data — categories, product attributes, offer fields, offer states and reason codes. This page walks through the smallest end-to-end flow: map a few categories, map the must-have attributes, send a small batch of products to the marketplace, then turn on the stock and order syncs.

All the pages mentioned below are reached from the Dashboard (the page you land on when you click Mirakl in the Catalogues group of the main sidebar). The Dashboard’s Quick Start card has a tile for every page; this guide names the specific tile for each step.

Step 1 — Map at least one category

The marketplace rejects offers in categories you haven’t mapped to a Shopware category, so this is the first hard requirement.

1. From the Dashboard’s Quick Start card, click the Categories tile. This opens Mirakl → Mirakl Categories. The list shows the marketplace’s category tree (columns: Code, Name, Full Path, Level, Parent Code, Active, Connections).
2. Find a marketplace category you want to sell in (use the Name filter or the Filter by Connection sidebar filter to narrow down). Click the row to open the Category Details page.
3. Switch to the Mapping tab.
4. Pick the relevant marketplace in the Connection selector (it’s selected automatically if you only have one).
5. Click Add Category. In the Add Category Mapping dialog that opens, pick the matching Shopware Category and save. The mapping is stored immediately and applies to every product that lives in that Shopware category.

The mapping is marketplace-centric: one marketplace category can be mapped to several Shopware categories, all from the same marketplace-category detail page. You can map more categories later — the plugin won’t complain about unmapped ones until you try to send a product that belongs in one of them.

Tip

On large marketplaces (tens of thousands of categories), use the Bulk Edit button on the Mirakl Categories list to deactivate categories you’ll never sell in. Deactivated categories disappear from the Shopware-category-mapping dropdowns elsewhere in the plugin, which makes picking the right one much faster.

Step 2 — Map the required attributes

Each marketplace category has a set of attributes the marketplace marks as required. The plugin highlights them on the attribute mappings page.

1. From the Dashboard’s Quick Start card, click the Attribute Mappings tile. This opens Mirakl → Attribute Mappings.
2. Click Auto Map. A background task tries to match marketplace product attributes to Shopware fields, custom fields, property groups and categories by comparing names. Progress is shown in a modal.
3. Review the suggested mappings. Required attributes that the auto-map couldn’t resolve must be mapped by hand, or the marketplace will reject those products.
4. If your Shopware values for an attribute don’t line up 1-to-1 with the values the marketplace accepts, set up a Transformation on that row (see Mapping → Attributes for details).

You can re-run Auto Map any time — it skips attributes that already have a mapping for the selected connection, so it won’t overwrite anything you’ve edited by hand.

Step 3 — Send a small batch of products

Don’t push your whole catalogue on day one. Pick 5–10 representative products and watch the round-trip.

1. From the Dashboard’s Quick Start card, click the Catalog tile. This opens Mirakl → Product Catalog.
2. Use the sidebar filters (Status, Connection, Name, Product number, EAN / GTIN) to narrow the list down to a handful of products in the category you mapped in step 1.
3. Tick the checkbox on each row you want to send, then click Export Selected in the toolbar.
4. If you have more than one connection, the Select Connection dialog asks which marketplace this batch goes to. Pick the connection and click Continue.
5. A progress modal shows the background task. Each selected product is queued and its Export Status moves through Pending → Queued → Processing → Exported (or ends up in Retry or Error if something went wrong).

The marketplace processes the batch on its side; the marketplace’s per-product errors show up on the corresponding row’s Export Status once the marketplace finishes checking the upload.

For products the marketplace rejected, fix the cause (usually a missing required attribute, or a category the marketplace doesn’t accept your product type in) and trigger the export again.

Step 4 — Turn on stock sync

Once products are live on the marketplace, you want every stock change you make in Shopware to be pushed there automatically.

1. Open Mirakl → Settings → Sync Settings tab.
2. Make sure the stock sync is active (it’s on by default).
3. With the default settings, the plugin checks every 15 minutes whether any products had a stock change and pushes the new value to the marketplace.

You don’t need to wait the full 15 minutes for a one-off change — the plugin spots the stock change the moment it happens in Shopware and flags the corresponding offer, so the next scheduled run picks it up.

Step 5 — Turn on order import

To bring marketplace orders into Shopware, turn on order import on the connection.

1. The earliest date from which orders should be pulled is set on the connection — it was the choice you made in step 12 of the setup wizard, and you can change it later from the Edit Connection modal. Only orders newer than this date are imported (to avoid pulling years of history).
2. Make sure order import is active on Mirakl → Settings → Sync Settings tab (on by default).
3. With the default settings, the plugin checks the marketplace for new orders every 30 minutes, creates a Shopware order for each, and lists them on the Orders page (Dashboard’s Quick Start → Orders).
4. From the Shopware order, you can ship, refuse and message the customer in Shopware — the corresponding Shopware status changes are pushed back to the marketplace automatically (see step 10 of the setup wizard, Reverse Status Mapping).

The first time order import runs against a connection, it also kicks off automatic imports of message threads, documents, invoices and transaction logs for that marketplace — see the per-feature pages for details.

What’s next

• Catalog Export — generate the one-time CSV for the Mirakl mapping wizard (only needed at first setup).
• Catalog — ongoing catalogue management (Add to Catalog, Export Selected, status tracking).
• Order import — chained imports for messages, documents and invoices.
• Sync logs — where to look when something went wrong.
• Troubleshooting — common errors and how to resolve them.