# 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.


## How the entities relate

The diagram is a simplified overview.
It shows how the entities connect, not every field.

```mermaid
erDiagram
    CHANNEL ||--o{ STORE : hosts
    STORE   ||--o{ OFFER : lists
    PRODUCT ||--o{ OFFER : "sold as"
    STORE   ||--o{ ORDER : receives
    OFFER   }o--o{ ORDER : "ordered in"
    ORDER   ||--o{ RETURN : "may lead to"

    CHANNEL {
        string channel_id PK
    }
    STORE {
        string channel_store_id PK
        string channel_id FK
    }
    PRODUCT {
        string[] identifiers PK
    }
    OFFER {
        string channel_id PK
        string store_id PK, FK
        string product_id PK
        string[] identifiers FK
    }
    ORDER {
        string channel_id PK, FK
        string channel_store_id PK, FK
        string channel_order_id PK
        string sub_channel_code PK
    }
    RETURN {
        string channel_return_id PK
        string channel_order_id FK
    }
```

## The entities

### Channel

* **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](/content/product/connect-channel-platform/getting-started/prerequisite-resources).


### Store

* **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](/content/product/connect-channel-platform/developer-guide/stores).


### Product

* **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](/content/product/connect-channel-platform/developer-guide/catalog-flow).


### Offer

* **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](/content/product/connect-channel-platform/developer-guide/catalog-flow).


### Order

* **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](/content/product/connect-channel-platform/developer-guide/orders).


### Return

* **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](/content/product/connect-channel-platform/developer-guide/returns).


## A note on identifiers

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 domains

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.

### Stores

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](/content/product/connect-channel-platform/developer-guide/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](/content/product/connect-channel-platform/developer-guide/business-use-cases#channel-authorization) and [Stores](/content/product/connect-channel-platform/developer-guide/business-use-cases#stores) flows.

Read [Stores](/content/product/connect-channel-platform/developer-guide/stores).

### Catalog

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](/content/product/connect-channel-platform/developer-guide/catalog-configuration) and [Taxonomy](/content/product/connect-channel-platform/developer-guide/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](/content/product/connect-channel-platform/developer-guide/business-use-cases#catalog) flows.

Read [Catalog flow](/content/product/connect-channel-platform/developer-guide/catalog-flow).

### Orders

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](/content/product/connect-channel-platform/developer-guide/business-use-cases#orders) flows.

Read [Orders](/content/product/connect-channel-platform/developer-guide/orders) and [Returns](/content/product/connect-channel-platform/developer-guide/returns).

## Related pages

* [Integration overview](/content/product/connect-channel-platform/getting-started/integration-overview): how these entities move across the REST and event boundary.
* Each entity's own section, [Stores](/content/product/connect-channel-platform/developer-guide/stores), [Catalog flow](/content/product/connect-channel-platform/developer-guide/catalog-flow), [Orders](/content/product/connect-channel-platform/developer-guide/orders), or [Returns](/content/product/connect-channel-platform/developer-guide/returns): the authoritative fields, statuses, and operations.
* [Concepts and glossary](/content/product/connect-channel-platform/getting-started/concepts-and-glossary): the vocabulary these entities are described with.