Data model

Six entities cross the boundary between Mirakl Connect and a channel: Channel, Store, Product, Offer, Order, and Return. They recur in almost every API call and event.

Each entity below is described by four things:

• its identity, which is how you reference it,
• its owner, which is the source of truth,
• a summary of its lifecycle,
• where it is documented in depth.

• Identity: a channel identifier, channel_id.
• Owner: Mirakl Connect. A channel is reference data that Mirakl registers and configures, so your connector reads it but does not create it.
• Lifecycle: long-lived and relatively static. A channel is set up once, and the stores, the offers, and the orders that belong to it then reference it.
• Documented in: Get access.

• Identity: a store is identified within its channel, by a channel_store_id under a given channel_id.
• Owner: the seller. Mirakl manages the store data, and your connector keeps the store's representation on the channel in step with it.
• Lifecycle: your connector imports a store when the seller authorizes the channel, and it updates the store afterwards. It is enriched with store-level features, such as its business information and the store linking. Your connector reports a change to the store data with a call. It receives a change to a store-level feature, such as the link or the unlink, as an event. A store also carries the sub-channels the seller operates in, and your connector declares that list. A store's life ends in a closed state or in a revoked access, and no operation deletes it.
• Documented in: Stores.

• Identity: a product identifier, which is a universal code such as a GTIN or an EAN. Offers that sell the same product share it, and it is what groups them into one product. It is distinct from an offer's SKU, the product_id, which is the seller's own reference within one store.
• Owner: the seller's catalog, in Mirakl Connect. A product describes what is sold, independently of the price and the availability.
• Lifecycle: a product is created and updated in the catalog. Mirakl Connect emits each change as a product event, for your connector to publish to the channel. A product carries no price and no stock of its own, because those belong to its offers.
• Documented in: Catalog flow.

• Identity: its SKU, the stock-keeping unit. It is the seller's own reference for the item, carried as product_id, and unique within a channel_id and a store_id. Offers that sell the same product are grouped by a shared product identifier, a GTIN, not by this SKU.
• Owner: the seller. An offer is the sellable listing: it puts a product up for sale under a store, with its pricing and its available stock.
• Lifecycle: an offer is created and updated alongside its product. Its price and its stock change frequently, and Mirakl Connect emits them as their own events, because buyers act on these values at the moment of purchase and they must stay accurate.
• Documented in: Catalog flow.

• Identity: the order's identifier on the channel, channel_order_id. With its channel_id and its channel_store_id, it forms the order's global identifier in Mirakl Connect. On a store that has sub-channels, the sub_channel_code completes the identity, because two sub-channels can issue the same channel_order_id. An order line names the product by the seller's own reference on the channel.
• Owner: an order originates from a buyer on the channel. Mirakl Connect holds the canonical record once the order is registered. Your connector brings the orders in from the channel, and keeps their status in step in both directions.
• Lifecycle: an order is placed on the channel and submitted to Mirakl Connect. Order-action commands then drive it through the acceptance, the shipping, the documents, and a possible cancellation or refund. Mirakl Connect anonymizes the personal data on an order once the order is past its retention window. An order is the partition key for its own events, so Mirakl Connect delivers those events to you in order.
• Documented in: Orders.

• Identity: the return's identifier on the channel, channel_return_id, tied to the order it belongs to through channel_order_id.
• Owner: a return originates from a buyer's request on the channel. Mirakl Connect tracks it against the order. Your connector carries the returns and the associated refunds between Mirakl Connect and the channel.
• Lifecycle: a return is opened against an order. It then moves through the acceptance or the refusal, the acknowledgement of the reception, the tracking updates, the closing, and the associated refund. A command that your connector acts on and confirms drives each step.
• Documented in: Returns.

Every entity above has an identity in Mirakl Connect and an identity on the channel, and the two are not the same. To maintain the mapping between them is the responsibility of your connector, not of Mirakl Connect. When an event or an API response gives you a Mirakl identifier, your stored mapping is what lets you find the matching record on the channel, and the reverse.

One identifier in Mirakl Connect can also surface under two names, and the name depends on the domain, not on whether you call or you receive. A store's identifier is channel_store_id on the store operations, on the order and return calls, and on the order and return command events. The same identifier is store_id on the catalog events, on StoreManagementFeatureEvent, and on the catalog calls that take a store. They are the same identifier.

The entities above are grouped into three domains, the functional areas of the Channel Platform. Each domain documents the entities it owns in depth, and the business workflows you build against them.

How a store is brought into Mirakl Connect and kept current:

• how to create and update the stores,
• how to publish store-level features, such as the business information and the store linking,
• the account data of the channel, the seller, and the user that ties a store to a channel, documented in Channel authorization.

This is where the work begins. A store must exist and be linked before its products and its orders can flow.

Business use cases: the Channel authorization and Stores flows.

Read Stores.

Everything that makes a seller's products sellable on a channel.

The prerequisite is the taxonomy and the catalog configuration: the product types and the taxonomy rules that structure the catalog, and the configuration that declares which offer use cases a channel supports. They are documented in Catalog configuration and Taxonomy.

The rest is one continuous catalog workflow:

1. Create the product that describes what is sold.
2. Put an offer live against it.
3. Keep the price and the stock of that offer current.

The statuses the connector reports at each step drive what Mirakl Connect sends next, and what the seller sees in their catalog.

Business use cases: the Catalog flows.

Read Catalog flow.

The whole life of an order after a buyer places it, across two sub-parts:

• Orders and fulfillment: how to accept, ship, and cancel orders, the documents and the carrier information that go with the fulfillment, and the anonymization and the retention of the order data.
• Returns and refunds: how to accept or refuse a return, acknowledge its reception, track it, close it out, and issue the refund.

Business use cases: the Orders flows.

Read Orders and Returns.

• Integration overview: how these entities move across the REST and event boundary.
• Each entity's own section, Stores, Catalog flow, Orders, or Returns: the authoritative fields, statuses, and operations.
• Concepts and glossary: the vocabulary these entities are described with.