Understanding Marketplaces, Channels, and Sellers in Mirakl

A marketplace represents a retailer or merchant on the Mirakl platform. Some marketplaces may be divided into smaller entities to accommodate regional distinctions. For example, Leroy Merlin may have marketplaces for the EU, Brazil, and South Africa. These marketplaces form the foundational entities that the Activation system interacts with, where typically, 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. While channels may represent regions, they can also be used for other segments like pricing strategies. For instance, the Leroy Merlin (EU) marketplace contains five channels: IT, FR, PT/ES, and two additional ones. The configuration of these channels and the association of sellers to them are managed entirely within Mirakl. We retrieve this data via API, without any control over its configuration.

A seller (also referred to as merchant) is equivalent to a client or customer on the Activation side of the system and is identified by a unique shopID.

Traditionally, each Activation client has one seller account on Mirakl, which serves as the link to their marketplace operations. For this setup, a client would have a single flow corresponding to a specific Mirakl marketplace. This setup looks something like this:

However, in some cases, a client may choose to operate multiple seller accounts within the same Mirakl marketplace. This approach might be used to segment regions or other business reasons (like pricing, brand catalog segmentation). Each seller account would then be linked to different channels within the marketplace. As each account requires separate authentication, multiple Activation channels must be created for these scenarios, and the configuration might look like this:

In these cases, requirement fetching is contextualized for each Activation Channel (i.e., for each seller). The distinction between Activation Channels is determined by the authentication and credentials used in the API call.

Product category marked as deleted by the marketplace?

Marketplace Data Model Updates

Marketplaces regularly update their requirements and category trees, which define product types, categories, and the corresponding required or optional attributes for each category. This could be due to merging catalogs or operational updates on the marketplace side. As a result, a new catalog and a new identifier would be created but the requirement schema would not change much. The frequency of these updates varies across marketplaces. 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—handled at the channel catalog creation step—a previously available category or attribute may be removed or replaced with a new one. It’s important to regularly review these updates to ensure your product information remains aligned with the marketplace's requirements.

Mirakl-based marketplaces can freely modify their category structures and family IDs. This flexibility leads to differences in how changes are interpreted by our system.

Example 1: Dynamic Family IDs

Some marketplaces, like Leroy Merlin, use dynamic family IDs that depend on the category tree's 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.

For our system:

1. The old family ID is flagged as deleted.
2. The new family ID is treated as a new family.

Impact:
Even though the family looks the same in the Mirakl back-office (no change in properties), our system interprets it as a new entity due to the ID change.

Example 2: Static Family IDs

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

• In this case, even if the category's position in the tree changes, the family is not flagged as deleted because the ID stays consistent.
• Our system only cares whether a family is a "leaf" in the tree (i.e., it has no subcategories).

Result:
Position updates do not affect family detection, ensuring continuity in the data.

Understanding Family Detection and Updates in Mirakl-Based Marketplaces

Our system determines if a family (a group of related products) is deleted by comparing the new list of families fetched from Mirakl with the current list stored in our database. This process ensures we stay updated with any structural changes to the marketplace's category tree.

How Deleted Families Are Detected?

• Each family is identified by its Mirakl-defined ID.
• If a family ID exists in the database but is missing from the latest list fetched from Mirakl, it is considered deleted.
• Deleted families are flagged in the system, and you can see a callout in the UI if any action is required.

We fetch the full list of families during each synchronization, ensuring our data reflects the latest updates.

What to do when this happens?

If a product category is not available anymore, Activation now displays a message next to the existing catalog (referring to the deprecated category name).

Because it it impossible for Activation to determine what the new category should be, it cannot migrate your content automatically. Therefore, you must remap the catalog (as well as all related attributes) to one of the newly available product types. To do so, using the catalog duplication feature, you can create the new catalog and duplicate from the existing one by selecting the family in the list that still matches what you want, (because in practice, the deleted family has moved in the category tree, and remains the same, with the same name). You can use the mapping of the deprecated catalog (from the catalog creation modal dropdown), this way you don't have to remap each attribute in the catalog. 

Takeaways

1. Dynamic IDs (based on tree structure) may cause families to appear as deleted and recreated when their positions change.
2. Static IDs ensure stability, as families are not flagged as deleted when moved.
3. You should be aware of these differences, especially when working with dynamic marketplaces like Leroy Merlin.
4. You might need to remap catalogs when families become deleted

If you encounter flagged families that seem unchanged, check whether their ID or tree structure has been updated in the marketplace. This ensures you're interpreting the flags correctly.