# Concepts and glossary

This page defines the shared vocabulary of the Mirakl Connect Channel Platform documentation.
It has two parts:

- The **[functional glossary](#functional-glossary)** is the business vocabulary: the actors, the entities that cross the boundary between Mirakl Connect and a channel, and the workflows they move through.
Read it to understand what Mirakl Connect models.
- The **[technical glossary](#technical-glossary)** is the integration mechanics: the authentication, the event contract, the delivery guarantees, and the payload fields your connector reads and writes.
Read it to understand how you build against Mirakl Connect.


## Functional glossary

The business domain: who the actors are, what entities they own, and how those entities move.

- **[Account Channel Platform](/content/product/account-channel-platform/rest/connector/openapi3)**: the separate contract that holds the store and consent operations, which are [sellerAccountStoreCreate](/content/product/account-channel-platform/rest/connector/openapi3/store/seller_account_store_create) and [sellerAccountStoreUpdate](/content/product/account-channel-platform/rest/connector/openapi3/store/seller_account_store_update).
The Mirakl Account host serves it, and the Channel Platform is everything else your connector calls.
- **[adjustment](/content/product/connect-channel-platform/developer-guide/orders#refunds-and-cancellations)**: a change recorded on an order line after the order.
It is either a refund, where money returns and the ordered quantity does not change, or a cancellation, where units are removed and the stock reservation is released.
Adjustments are append-only, so every order upsert carries the line's full adjustment history.
- **[anonymization](/content/product/connect-channel-platform/developer-guide/orders#data-retention-and-anonymization)**: the removal of an order's personal data once the order is past its retention window.
Your connector sets the date for each order with [updateAnonymizeAfterDate](/content/product/connect-channel-platform/rest/connect/openapi3/orders/updateanonymizeafterdate), and the removal is irreversible once that date passes.
- **[business information](/content/product/connect-channel-platform/developer-guide/stores#keeping-store-information-up-to-date)**: a store-level feature.
It is the business details your connector publishes with [upsertBusinessInformation](/content/product/connect-channel-platform/rest/connect/openapi3/store/upsertbusinessinformation), so that Mirakl Connect considers a store usable.
[StoreManagementFeatureEvent](/content/product/connect-channel-platform/webhooks/webhook/webhooks/storemanagementfeatureevent) reports it as the `business-information-sync` feature, with a status of `enabled` or `disabled`.
- **[carrier](/content/product/connect-channel-platform/developer-guide/orders#carriers)**: an entry in the list of shipping carriers a channel allows.
Your connector shares the list with [upsertCarriers](/content/product/connect-channel-platform/rest/connect/openapi3/carriers/upsertcarriers), as a full replacement, so that a shipment can name a carrier the channel supports.
- **[catalog configuration](/content/product/connect-channel-platform/developer-guide/catalog-configuration)**: the configuration that declares how offers behave on the channel, which is its offer attributes and the offer use cases it supports.
It shapes the offer alone, and the taxonomy shapes the product.
You apply it with [configureChannelCatalog](/content/product/connect-channel-platform/rest/connect/openapi3/catalog-configuration/configurechannelcatalog).
- **[Catalog Transformer](/content/product/connect-channel-platform/developer-guide/taxonomy#catalog-transformer)**: the Mirakl capability that transforms a seller's products into channel products, with the channel's registered taxonomy.
The seller's plan activates it, and sellers on the free plan do not have it.
It gates [ProductUpsertEvent](/content/product/connect-channel-platform/webhooks/webhook/webhooks/productupsertevent): Mirakl Connect attempts product creation only for sellers who have it.
For every other seller, an offer can go live only against a product that already exists on the channel.
- **[channel](/content/product/connect-channel-platform/getting-started/data-model#channel)**: an external marketplace or platform where sellers list their products and where buyers place orders.
Mirakl does not operate it.
- **Channel Platform**: the API and event surface of Mirakl Connect, which is the REST APIs your connector calls and the events it receives.
- **[connector](/content/product/connect-channel-platform/getting-started/integration-overview#where-your-connector-sits)**: the middleware an integrator builds and runs between one channel and Mirakl Connect.
The integrator owns it, and owns neither of the two platforms it connects.
- **[diagnostic](/content/product/connect-channel-platform/developer-guide/catalog/report-feedback)**: a description, readable by a human, of a problem that is currently active on an offer or a product.
Your connector reports it with the item's status, as a full-replace list.
It explains why an item needs action, so that a seller can fix it.
- **[discount price](/content/product/connect-channel-platform/developer-guide/catalog/sync-price-and-stock)**: an offer's promotional price, with its own start date and end date.
It applies instead of the standard price while it is in effect.
It is the one price field that is genuinely cleared: an `action_type` of `DELETE` ends the promotion, and the standard price applies again.
- **[feedback](/content/product/connect-channel-platform/developer-guide/catalog-flow#the-feedback-loop)**: the status and the diagnostics your connector reports back for each store catalog item, which are the offer status, the product status, and both diagnostics lists.
It closes the loop that Mirakl Connect acts on to decide what to send next.
- **[fulfillment](/content/product/connect-channel-platform/developer-guide/orders#the-order-and-its-lines)**: who ships an order, declared on the order as `FULFILLED_BY_SELLER` for the seller, or `FULFILLED_BY_PARTNER` for a fulfillment partner named by a code.
A fulfillment partner also names one kind of stock location, which is a separate use of the same words.
- **GTIN**: Global Trade Item Number, the most common type of product identifier.
An event carries it in the `identifiers` list.
- **integrator**: the party that builds and operates a connector.
It is the audience of this documentation.
- **Mirakl Connect**: the Mirakl product that sellers work in to reach buyers across many external sales channels, without a separate integration for each one.
Sellers manage their stores, their catalog, their offers, and their orders here.
It holds the canonical record of everything that crosses the boundary with a channel.
The Channel Platform is the API and event surface your connector builds against.
- **[offer](/content/product/connect-channel-platform/getting-started/data-model#offer)**: a sellable listing that puts one product up for sale under a store, with its pricing and its available stock.
Its SKU identifies it.
- **[offer attribute](/content/product/connect-channel-platform/developer-guide/catalog-configuration#offer-attributes)**: a value the channel needs on an offer that Mirakl Connect does not already hold, such as the condition of the item.
You declare each one in the `custom_attributes` of the catalog configuration, with an `id` of your own.
The offer events then carry the values in `offer_attributes`, each one typed `TEXT`, `NUMERIC`, `BOOLEAN`, or `LIST`.
- **[offer use case](/content/product/connect-channel-platform/developer-guide/catalog-configuration#offer-use-cases)**: the kind of operation an [`OFFER_UPSERT`](/content/product/connect-channel-platform/webhooks/webhook/webhooks/offerupsertevent) event carries, either `OFFER_CREATION` or `OFFER_UPDATE`.
The catalog configuration of a channel declares which offer use cases the channel supports, and that declaration is what allows Mirakl Connect to emit `OFFER_UPSERT` at all.
- **[order](/content/product/connect-channel-platform/getting-started/data-model#order)**: a purchase a buyer places on the channel.
It is registered with Mirakl Connect, and order-action commands drive it through the fulfillment.
- **[order action](/content/product/connect-channel-platform/developer-guide/orders/handle-order-action-events)**: an action Mirakl Connect requests on an order or on one of its returns, such as accept, ship, cancel, refund, upload a document, and the return steps.
Mirakl Connect requests it as a command, and your connector performs it and confirms it.
- **[order line](/content/product/connect-channel-platform/developer-guide/orders#the-order-and-its-lines)**: one product of an order, in a given quantity.
Its `channel_order_line_id` identifies it, and that id is unique across every order of the channel, not only within its own order.
Each line carries its own status and its own adjustments, so the lines of one order can sit at different stages.
- **[price](/content/product/connect-channel-platform/developer-guide/catalog/sync-price-and-stock)**: the amount attached to an offer, in two forms, a **standard price** and an optional **discount price**.
[PriceStockUpsertEvent](/content/product/connect-channel-platform/webhooks/webhook/webhooks/pricestockupsertevent) carries every later change, together with the stock, and the offer and product events carry the price an offer starts with.
A price changes frequently, because buyers act on it at the moment of purchase.
- **[product](/content/product/connect-channel-platform/getting-started/data-model#product)**: a catalog record that describes what is sold, independently of the price and the availability.
- **[product identifier](/content/product/connect-channel-platform/getting-started/data-model#product)**: the universal code that says what is sold, such as a GTIN or an EAN.
An event carries it in its `identifiers` list, and offers that sell the same product share it.
It is distinct from an offer's SKU, which is the seller's own reference within one store.
- **[product type](/content/product/connect-channel-platform/developer-guide/taxonomy#product-types)**: the category a product belongs to on the channel, and the attributes a product of that category must carry.
It is the channel's own identifier, and it reaches you as `product_type_id`.
You register one with [upsertProductType](/content/product/connect-channel-platform/rest/connect/openapi3/taxonomy/upsertproducttype), and a product is only ever created in a product type you registered.
- **[return](/content/product/connect-channel-platform/developer-guide/returns)**: a request from a buyer to send part or all of an order back.
It is tracked against the order, and it moves through the acceptance or the refusal, the reception, the tracking, the closing, and the refund.
- **[return line](/content/product/connect-channel-platform/developer-guide/returns#the-return-and-its-lines)**: one order line that is returned, in a given quantity and with a reason.
It names that order line by its `channel_order_line_id`.
- **seller**: a merchant who runs one or more stores that sell through Mirakl Connect.
The seller owns the store, product, and offer data that flows to the channel.
- **[SKU](/content/product/connect-channel-platform/getting-started/data-model#offer)**: stock-keeping unit, the seller's own reference for an item.
It is carried as `product_id`, and it is unique within a `channel_id` and a `store_id`.
It is the offer's identity, the partition key its events are ordered by, and the `id` you report feedback against.
It is not the product identifier, because offers that sell the same product are grouped by a shared GTIN, not by SKU.
- **standard attribute**: a field Mirakl Connect holds for every channel, as opposed to one you declare yourself.
Two separate closed sets carry this name, and they are not interchangeable:
  - In the [taxonomy](/content/product/connect-channel-platform/developer-guide/taxonomy#standard-attributes), `connect_standard_attributes` marks the product field that a channel attribute corresponds to.
There are eight: `PRODUCT_ID`, `CATEGORY`, `BRAND`, `TITLE`, `DESCRIPTION`, `IMAGE`, `GTIN`, and `VARIANT_GROUP_CODE`.
  - In the [catalog configuration](/content/product/connect-channel-platform/developer-guide/catalog-configuration#the-five-standard-attributes), `standard_attributes` lists the offer fields that an offer use case requires or accepts.
There are five: `ID`, `GTIN`, `STANDARD_PRICE`, `DISCOUNT_PRICE`, and `STOCK`.
- **[standard price](/content/product/connect-channel-platform/developer-guide/catalog/sync-price-and-stock)**: an offer's list price, the amount that applies when no discount price is in effect.
It is only ever set with `UPDATE` or left unchanged with `IGNORE`, because an active offer always has one.
- **[stock](/content/product/connect-channel-platform/developer-guide/catalog/sync-price-and-stock)**: the available quantity attached to an offer.
Like a price, it changes frequently and reaches your connector on [PriceStockUpsertEvent](/content/product/connect-channel-platform/webhooks/webhook/webhooks/pricestockupsertevent).
The current model is a `breakdown`, with one entry for each kind of stock: `SELLER_CENTRALIZED`, which is tied to no location, `SELLER_WAREHOUSE`, which names a warehouse, and `FULFILLMENT_PARTNER`, which names a partner.
The legacy aggregated form of the same figure is called **inventory**.
- **[store](/content/product/connect-channel-platform/developer-guide/stores#what-a-store-is)**: a seller's selling entity on a channel, identified by a channel store id under a channel id.
Products and orders belong to it.
Channels model it differently: some have their own store-like entity, and on channels that have none, the store is simply associated with the seller's channel account.
- **[store catalog item](/content/product/connect-channel-platform/developer-guide/catalog/report-feedback)**: the record for one store and one channel, keyed by the SKU of the offer, the `product_id`.
It carries the offer's status, and its product's status and diagnostics, for the feedback loop.
- **[store linking](/content/product/connect-channel-platform/developer-guide/stores#linking-stores-in-mirakl-connect)**: a store-level feature that activates a store's catalog and order flows.
The seller turns it on for one store in Mirakl Connect, and [StoreManagementFeatureEvent](/content/product/connect-channel-platform/webhooks/webhook/webhooks/storemanagementfeatureevent) reports it as the `store-linking` feature, with a status of `linked` or `unlinked`.
Unlinking the store deactivates those flows.
It is separate from the [channel authorization](/content/product/connect-channel-platform/developer-guide/channel-authorization), which is what brings a seller's stores into Mirakl Connect in the first place.
- **[store status](/content/product/connect-channel-platform/developer-guide/stores#the-stores-state)**: the condition of a store that a seller sees, which Mirakl Connect derives from the `state` and the `suspension_type` your connector reports.
There are five: `ONLINE`, `CLOSED`, `SUSPENDED`, `PENDING_APPROVAL`, and `ACCESS_REVOKED`.
Your connector never reports it.
- **[sub-channel](/content/product/connect-channel-platform/developer-guide/stores#sub-channels)**: a sales channel inside one channel, with its own currency.
A seller who sells on several of a channel's sales channels holds one store that carries one sub-channel for each of them.
Your connector declares the list on the store, with [upsertBusinessInformation](/content/product/connect-channel-platform/rest/connect/openapi3/store/upsertbusinessinformation).
Prices, stock, and orders can be per sub-channel, and products stay per store.
The store call names a sub-channel `id`, and every other call and event names the same value `sub_channel_code`.
- **[taxonomy](/content/product/connect-channel-platform/developer-guide/taxonomy)**: the channel's product format, registered in Mirakl Connect.
It has two parts, the **product types** and the **taxonomy rules**.
The Catalog Transformer transforms a seller's products against it.
- **[taxonomy rule](/content/product/connect-channel-platform/developer-guide/taxonomy#taxonomy-rules)**: a rule that redefines the requirement level of a product type's attribute when a condition holds.
Rules belong to the channel, and you register them with [createTaxonomyRule](/content/product/connect-channel-platform/rest/connect/openapi3/taxonomy/createtaxonomyrule).
A product type then references the ones it needs by their `id`, so register a rule before the product type that references it.


## Technical glossary

The integration mechanics: how you authenticate, how events reach you, what Mirakl Connect guarantees, and the fields you read and write.

- **[access token](/content/product/connect-channel-platform/developer-guide/authorization#generating-and-using-the-access-token)**: a short-lived OAuth2 token your connector obtains with its client credentials.
Present it on every REST call, in the header `Authorization: Bearer <access_token>`.
A call without a valid, unexpired token is rejected with `401`.
- **[action_id](/content/product/connect-channel-platform/developer-guide/orders/handle-order-action-events)**: the identifier Mirakl Connect puts on every command, and the key you report the outcome of that command against.
Persist it the moment the command arrives, because it is what ties the command you received to the status report you send back.
Reporting the same action twice is rejected with `ACTION_ALREADY_FINAL`.
- **[action_type](/content/product/connect-channel-platform/developer-guide/catalog/sync-price-and-stock)**: the instruction for each field on a catalog event you receive.
`UPDATE` sets the field, `DELETE` clears it, and `IGNORE` leaves it untouched.
It is why one event can change an offer's stock and leave its price alone.
It is also the reverse of the feedback operation you call, where a field you omit **is** a cleared field.
- **[ActionError](/content/product/connect-channel-platform/developer-guide/orders/handle-order-action-events#4-report-the-outcome)**: the outcome you report on an action that failed, which is a `code` from a bounded set and a `message` a human can read.
Report the most specific code that applies, and reserve `OTHER` and `UNEXPECTED` for the failures you genuinely cannot classify.
- **[at-least-once delivery](/content/product/connect-channel-platform/developer-guide/receiving-events#delivery-semantics)**: Mirakl Connect's guarantee that it delivers every event one or more times.
Duplicates are normal, and you must deduplicate them.
- **[channel_updated_at](/content/product/connect-channel-platform/developer-guide/orders/sync-orders-into-connect)**: the last time an order or a return was modified **on the channel**.
Mirakl Connect versions the upserts by it: it silently ignores an upsert whose `channel_updated_at` is older than the value it already stores.
This anti-replay guard is what stops a delayed or redelivered message from overwriting newer state, so the timestamp must be accurate and must move forward.
- **[client credentials](/content/product/connect-channel-platform/developer-guide/authorization#requesting-the-api-credentials)**: the client id and the client secret Mirakl issues to your connector.
You exchange them for an access token, through the OAuth2 client-credentials grant.
- **[command](/content/product/connect-channel-platform/getting-started/api-and-event-directory)**: an event Mirakl Connect sends you, which asks your connector to perform an action, such as to accept an order, create a shipment, or process a return, and to report the outcome back through a REST call.
- **[dead-letter queue](/content/product/connect-channel-platform/developer-guide/receiving-events#delivery-semantics)**: a holding area for messages that cannot be delivered.
The event delivery path does **not** provide one: it abandons the deliveries that exhaust their retries, and it does not park them for you to drain.
- **[destination](/content/product/connect-channel-platform/developer-guide/receiving-events#choosing-a-destination)**: the queue or the topic Mirakl Connect delivers your events to, which is AWS SQS, Google Cloud Pub/Sub, or Microsoft Azure Service Bus.
You choose one, you own it, and Mirakl registers it for you.
The event payload is identical on all three.
- **[event](/content/product/connect-channel-platform/developer-guide/receiving-events)**: an asynchronous notification of something that happened in Mirakl Connect.
Mirakl Connect delivers it to the destination you configure.
It is either a fact or a command.
- **[event envelope](/content/product/connect-channel-platform/developer-guide/receiving-events#the-event-envelope)**: the constant wrapper around every event, which holds `id`, `type`, `time`, and a `data` body.
It is identical across every destination.
- **[fact](/content/product/connect-channel-platform/getting-started/api-and-event-directory)**: an event Mirakl Connect sends you, which notifies your connector that something has happened, such as an updated product, or a price or stock change.
You owe nothing back to Mirakl Connect.
- **[idempotency](/content/product/connect-channel-platform/developer-guide/best-practices#idempotency)**: the property that handling the same event more than once, or repeating the same REST call, has no additional effect.
Every connector must have it.
- **[OAuth2 client-credentials grant](/content/product/connect-channel-platform/developer-guide/authorization#the-mechanism-oauth2-client-credentials)**: the OAuth2 flow in which your connector authenticates as itself, with a client id and a client secret, to obtain an access token.
No end user is involved.
- **[partition key](/content/product/connect-channel-platform/developer-guide/best-practices#ordering)**: the business key that events are ordered by, which is the offer's `product_id` for the catalog events, and the order for the order action events.
Events that share a key arrive in order, and there is no ordering guarantee across different keys.
- **[reconciliation](/content/product/connect-channel-platform/developer-guide/receiving-events#delivery-semantics)**: to recover missed or uncertain state proactively, rather than to rely on an event's redelivery.
- **[scope](/content/product/connect-channel-platform/developer-guide/authorization#scopes)**: a fine-grained permission that a token carries and an operation requires, such as `connect-channel-platform:orders:upsert`.
- **[state](/content/product/connect-channel-platform/developer-guide/stores#the-stores-state)**: what your connector reports about a store on the channel, on both store operations.
The values are `OPEN`, `CLOSED`, `SUSPENDED` with a `suspension_type`, and `ACCESS_REVOKED`.
The match is exact and it is case sensitive.
Mirakl Connect derives the **store status** a seller sees from it.
- **[store import token](/content/product/connect-channel-platform/developer-guide/channel-authorization#the-token)**: the token Mirakl Connect issues when a seller starts the consent process, and passes to your connector as the `token` query parameter.
It authorizes the one call that imports the seller's stores.
It expires, it works once, and it identifies the seller, so it is not the **access token** that authenticates the REST calls of your connector.
- **[sub_channel_code](/content/product/connect-channel-platform/developer-guide/stores#sub-channels)**: the code of the sub-channel a record belongs to, on the order payloads and on [PriceStockUpsertEvent](/content/product/connect-channel-platform/webhooks/webhook/webhooks/pricestockupsertevent).
It is optional everywhere it appears, and it completes the identity of an order: a `channel_order_id` alone no longer names one order once a store has sub-channels.
Send it on every call that names an order, so that Mirakl Connect resolves the right one.
- **[subscription](/content/product/connect-channel-platform/developer-guide/receiving-events#how-your-subscription-is-provisioned)**: the registration that makes Mirakl Connect deliver a set of event types to your destination.
The Mirakl Connect Partner Team creates it, so there is no self-service API for it, and it is registered separately for each environment.
- **[transport](/content/product/connect-channel-platform/developer-guide/receiving-events)**: the mechanism that carries an event to your connector, which is a queue or a topic.
The **destination** is the one you configure and Mirakl registers.
The envelope and the body are identical whichever transport carries them.
- **[upsert](/content/product/connect-channel-platform/developer-guide/best-practices#calls-you-make-upserts-are-idempotent-by-design)**: a write operation that creates an entity if it is new, or fully replaces it if it exists.
Upserts send complete state, and they are idempotent.
- **[windowed backoff](/content/product/connect-channel-platform/developer-guide/receiving-events#delivery-semantics)**: the retry schedule Mirakl Connect uses for the event deliveries that fail.
The retry intervals widen across an extended period, and then Mirakl Connect gives the delivery up.


## Related pages

- [Integration overview](/content/product/connect-channel-platform/getting-started/integration-overview): where your connector sits between Mirakl Connect and a channel, and the two directions of exchange between them.
- [Business use cases](/content/product/connect-channel-platform/developer-guide/business-use-cases): the flows required to integrate your channel, domain by domain.
- [API and event directory](/content/product/connect-channel-platform/getting-started/api-and-event-directory): the REST operations your connector calls and the events it receives, grouped by business domain.
- [Calling the APIs](/content/product/connect-channel-platform/developer-guide/calling-the-apis) and [Receiving events](/content/product/connect-channel-platform/developer-guide/receiving-events): the mechanics that the technical vocabulary above describes.
- [Catalog configuration](/content/product/connect-channel-platform/developer-guide/catalog-configuration) and [Taxonomy](/content/product/connect-channel-platform/developer-guide/taxonomy): the two halves of the catalog setup, and the full definition of the catalog vocabulary above.
- [Integration guide](/content/product/connect-channel-platform/developer-guide/authorization): the step-by-step guidance that uses this vocabulary, starting with the authorization.