This guide explains how Mirakl-powered marketplaces are structured in Akeneo Activation, and how to handle common scenarios such as connecting your seller account, deleted product categories, and authentication errors.

Understanding marketplaces, channels, and sellers in Mirakl

In Akeneo Activation, a marketplace represents a retailer or merchant on the Mirakl platform. Some marketplaces are divided into smaller entities to accommodate regional distinctions. For example, Leroy Merlin may have separate marketplaces for the EU, Brazil, and South Africa. Each marketplace corresponds to a unique API endpoint with its own configurations.

A channel refers to a distribution segment within a marketplace, often used to represent different sales segments. Channels may represent regions or other segments such as pricing strategies. For instance, the Leroy Merlin (EU) marketplace contains five channels: IT, FR, PT/ES, and two additional ones. Channel configuration and the assignment of sellers to channels are managed entirely within Mirakl. Activation retrieves this data via API.

A seller (also referred to as a merchant) is the entity operating on the marketplace, and corresponds to a client in Activation. Each seller is identified by a unique shopID.

Traditionally, each Activation client has one seller account on a given Mirakl marketplace. This setup creates a single Activation channel flow for that marketplace:

The diagram above shows the standard setup: one Activation channel connected to one Mirakl marketplace via a single seller account (shopID).

In some cases, a client may operate multiple seller accounts within the same Mirakl marketplace—for example, to segment by region, brand, or pricing strategy. Each seller account requires separate authentication, so a separate Activation channel must be created per shopID:

The diagram above shows a multi-seller setup: two Activation channels, each connected to the same Mirakl marketplace but authenticating with different seller accounts (shopIDs) and separate credentials.

In this setup, requirement fetching in Activation is scoped per Activation channel (i.e., per seller). The distinction between Activation channels is determined by the authentication credentials used in each API call.

Connect to a Mirakl-based channel in Activation

To connect Activation to a Mirakl-powered marketplace, you need the following credentials from your Mirakl seller account:

• Marketplace URL — the base URL of the Mirakl marketplace API
• Client ID — your Mirakl API client identifier
• Access token — an OAuth access token for authenticating API requests
• Refresh token — an OAuth refresh token used to renew the access token when it expires

To set up the connection in Activation:

1. In Activation, go to the Channels tab.
2. Find the Mirakl-powered channel you want to connect to and click Add this channel.
3. Enter the required credentials: marketplace URL, client ID, access token, and refresh token.
4. Save the connection. Activation will use these credentials to fetch marketplace requirements and push product data to the retailer.

Product category marked as deleted by the marketplace

Marketplace data model updates

Mirakl-powered marketplaces regularly update their requirements and category trees, which define product types, categories, and the corresponding required or optional attributes for each category. These updates may result from merging catalogs or operational changes on the marketplace side, and the frequency varies: some Mirakl-powered marketplaces update their data model weekly, whereas Amazon typically refreshes its templates every 6 to 12 months.

When a marketplace updates its requirements, a previously available category or attribute may be removed or replaced with a new one. Review these updates regularly to ensure your product information stays aligned with the marketplace's requirements.

Mirakl-based marketplaces can freely modify their category structures and family IDs. This leads to differences in how Activation interprets those changes.

Example 1: Dynamic family IDs

Some marketplaces, like Leroy Merlin, use dynamic family IDs that depend on the category tree structure.

• The family ID is based on the tree path, separated by |.
• Example: CAT1|SUBCAT2|FINALCAT
• When a family is moved within the tree (e.g., from SUBCAT2 to SUBCAT3), its ID changes.

When this happens, Activation:

1. Flags the old family ID as deleted.
2. Treats the new family ID as a new family.

Even though the family appears unchanged in the Mirakl back office, Activation interprets it as a new entity because the ID changed.

Example 2: Static family IDs

Other marketplaces use static family IDs (e.g., 123456) that remain the same regardless of the family's position in the category tree.

• When the category's position in the tree changes, the family is not flagged as deleted because the ID stays consistent.
• Activation only flags a family as deleted if it no longer appears as a leaf node in the category tree (i.e., it is no longer selectable as a product type).

For marketplaces using static IDs, position updates do not affect family detection, ensuring continuity in your catalog data.

Understanding family detection and updates in Mirakl-based marketplaces

Activation determines whether a family (a group of related products) is deleted by comparing the list of families fetched from Mirakl against the list currently stored in Activation.

How deleted families are detected:

• Each family is identified by its Mirakl-defined ID.
• If a family ID exists in Activation but is absent from the latest list fetched from Mirakl, it is flagged as deleted.
• Activation displays a callout in the UI next to the affected catalog when this occurs.

Activation fetches the full list of families during each synchronization to reflect the latest marketplace updates.

What to do when a product category is deleted

If a product category is no longer available, Activation displays a message next to the existing catalog, referencing the deprecated category name.

The screenshot above shows the Activation catalog list with a warning displayed next to a catalog whose Mirakl product category has been deleted by the marketplace.

Because Activation cannot determine which new category should replace the deleted one, it cannot migrate your catalog automatically. You must remap the catalog manually. To minimize remapping effort, use the catalog duplication feature:

1. In Activation, go to the Catalogs tab of the affected channel.
2. Click Create Catalog.
3. In the catalog creation modal, select Copy initial mapping from an existing catalog and choose the deprecated catalog as the source.
4. Select the replacement family from the dropdown. In practice, the deleted family has moved to a new position in the category tree but retains the same name—identify it by name in the list.
5. Attribute mappings shared with the deprecated catalog are copied automatically. Remap any attributes that differ.

Takeaways

1. Dynamic IDs (based on tree structure) may cause families to appear as deleted and recreated when their positions in the tree change.
2. Static IDs ensure stability, as families are not flagged as deleted when moved within the tree.
3. When working with dynamic marketplaces like Leroy Merlin, monitor the Activation UI for deleted-family notifications after each synchronization.
4. Use catalog duplication to minimize remapping effort when a family is deleted.

If you encounter flagged families that appear unchanged, check whether their ID or tree structure has been updated in the marketplace to interpret the flag correctly.

Troubleshooting

401 error after a product export

If you receive a 401 error after launching a product export in Activation, the Mirakl access token has expired. To resolve this, re-authenticate your Mirakl connection in Activation by updating the connection credentials with a new access token. This restores the authentication and allows Activation to resume exporting products to the marketplace.