This section describes how a catalog synchronizes between Mirakl Connect and the channel. It also describes the APIs and the events the connector must implement.
Two objects bring a product to sale:
- A product describes what is sold.
- An offer is a seller's sellable proposition for that product. It carries the price and the available stock under which a store puts the product up for sale on a channel.
The two objects are distinct, and each one has its own lifecycle. An offer always builds on a product that already exists on the channel. It cannot go live before that product exists.
A seller can synchronize a catalog to a channel only after the channel catalog is configured. Two configurations shape what the catalog flow can do, and both are covered separately:
- Catalog configuration: declares which offer use cases the channel supports.
- Taxonomy: registers the categories and the channel's product types. Mirakl Connect transforms products against them before it creates them on the channel. Your connector registers the taxonomy, and Mirakl then activates it in the Catalog Transformer. That activation is not self service, and no product is transformed before it.
The flow runs through four stages, and each stage depends on the one before it:
- A product is created on the channel. It describes what is sold, and it must exist before any offer can attach to it.
- An offer is created against it. The offer carries the seller's price, stock, attributes, and identifiers for that product.
- The offer goes active. It is live and visible on the channel, and a buyer can purchase it.
- Price and stock are kept current for as long as the offer sells.
This order is the dependency order. It is not the order Mirakl Connect runs the stages in. Most sellers list products that already exist in the channel's catalog. Starting every item at product creation would repeat work the channel has usually already done. Mirakl Connect assumes instead that as much as possible is already in place, and it enters the workflow as late as it can. Read How synchronization begins.
Mirakl Connect drives this workflow as a feedback loop:
- Mirakl Connect sends your connector an event.
- Your connector acts on the channel.
- Your connector reports the resulting status back.
- Mirakl Connect uses that status to decide what to send next.
Your connector reports two statuses for each store catalog item: product_status and offer_status. It sends them with the updateStoreCatalogItems API, together with the diagnostics that explain them.
These two statuses are the only thing that tells Mirakl Connect whether a product exists, whether an offer is live, or whether something is blocked. They also drive what the seller sees for each product in their catalog. They do not drive it directly. Mirakl Connect derives a single state from them, and the seller sees that state. Your connector never reads that state, but everything it reports shapes it.
To integrate this feedback, read Report feedback. It covers every status value, the event each pair of statuses triggers, what the seller ends up seeing, and how to batch the export and re-report the outcomes the channel returns asynchronously.
When a seller adds a product to a channel catalog for the first time, Mirakl Connect assumes the offer is already live on the channel and sends a PriceStockUpsertEvent.
It then walks back toward product creation only as far as your connector's feedback forces it. Matching an offer to a product that is already on the channel is the shortest path, and most sellers take it.
The status your connector reports decides how far back Mirakl Connect must go:
- The offer is already there. You report
OFFER_ACTIVE. The offer is live, and no creation happens at all. This is the common case: the product already exists in the channel's catalog, and your offer matches it by its identifiers. - The offer is missing. You report
OFFER_DOES_NOT_EXIST. Mirakl Connect sends an OfferUpsertEvent to create the offer against the product already on the channel. - The product is missing. You report
PRODUCT_DOES_NOT_EXIST. Mirakl Connect sends a ProductUpsertEvent to create the product first, but only for sellers with Catalog Transformer enabled. Whether a product must be created at all depends on the channel. Some channels let an offer match an existing catalog entry by identifier, so no product creation is needed. Other channels require the product to exist before any offer can attach to it.
Do not assume the first event you receive for a product is a ProductUpsertEvent. It is usually a PriceStockUpsertEvent. This is not an error, and it is not a sign that your state is out of sync. Mirakl Connect is probing the shortest path.
Mirakl Connect walks the workflow forward in full, from product creation to price and stock, only when neither the product nor the offer exists yet.
The two statuses your connector reports move each item through the workflow like this:
Because synchronization begins optimistically, an item often enters partway along this workflow. An offer whose product already exists on the channel enters at OFFER_DOES_NOT_EXIST. An offer that is already live enters directly at OFFER_ACTIVE, and it skips the product states.
The two statuses are not independent fields. Report feedback specifies what each value means, how Mirakl Connect resolves the pair, and which combinations trigger nothing at all. Read it before you implement feedback.
Three events carry the workflow. Your connector must implement a consumer for each one and synchronize what it carries to the channel. Mirakl Connect picks between them from where the item stands in its lifecycle, which is the statuses your connector has reported. It does not pick from the data that changed.
| Event | Sent while | Carries | Gated by |
|---|---|---|---|
| ProductUpsertEvent | the product is not usable on the channel | the product type and the product's full descriptive attributes | Catalog Transformer, for each seller |
| OfferUpsertEvent | the offer must be created (OFFER_CREATION) or its definition has changed (OFFER_UPDATE) | the price, the stock, the attributes, and the offer's identifiers, but no product data | the channel's catalog configuration |
| PriceStockUpsertEvent | an offer exists on the channel, plus the initial probe | the offer's current price and available quantity | nothing, and you cannot disable it |
For the full payload of each event, refer to the Event APIs reference.
These guides walk each part of the workflow end to end:
- Create or update products: consume ProductUpsertEvent events to create or update products on the channel, including grouped variants, and report the product status back.
- Create and update offers: consume OfferUpsertEvent events to create and update offer definitions on the channel, then report the resulting offer status.
- Sync price and stock: consume PriceStockUpsertEvent events to keep an active offer's price and available quantity current, including the stock for each location.
- Report feedback: every status value, the event each pair of statuses triggers, what the seller sees as a result, and how to batch the export and re-report the outcomes the channel returns asynchronously.