Skip to content
Products
/
Connect Channel Platform
/
/
Concepts and glossary

Concepts and glossary

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

  • The 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 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: the separate contract that holds the store and consent operations, which are sellerAccountStoreCreate and sellerAccountStoreUpdate. The Mirakl Account host serves it, and the Channel Platform is everything else your connector calls.
  • adjustment: 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: 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, and the removal is irreversible once that date passes.
  • business information: a store-level feature. It is the business details your connector publishes with upsertBusinessInformation, so that Mirakl Connect considers a store usable. StoreManagementFeatureEvent reports it as the business-information-sync feature, with a status of enabled or disabled.
  • carrier: an entry in the list of shipping carriers a channel allows. Your connector shares the list with upsertCarriers, as a full replacement, so that a shipment can name a carrier the channel supports.
  • 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.
  • 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: 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: 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: 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: a description, readable by a human, of a problem or a piece of information that is currently active on an offer or a product. Your connector reports it with the item's status, as a full-replace list. A product diagnostic can carry a severity: ERROR, WARNING, or INFO. It explains why an item needs action, so that a seller can fix it, or it gives information.
  • discount price: 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: 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: 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: 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: 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: the kind of operation an OFFER_UPSERT 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: 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: 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: 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: the amount attached to an offer, in two forms, a standard price and an optional discount price. 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: a catalog record that describes what is sold, independently of the price and the availability.
  • product identifier: 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: 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, and a product is only ever created in a product type you registered.
  • return: 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: 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: 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, 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, 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: 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: the available quantity attached to an offer. Like a price, it changes frequently and reaches your connector on 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: 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: 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: 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 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, which is what brings a seller's stores into Mirakl Connect in the first place.
  • store status: 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: 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. 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: 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: 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. 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: 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: 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: 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: 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: Mirakl Connect's guarantee that it delivers every event one or more times. Duplicates are normal, and you must deduplicate them.
  • channel_updated_at: 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: 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: 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: 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: 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: 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: the constant wrapper around every event, which holds id, type, time, and a data body. It is identical across every destination.
  • fact: 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: 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: 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: 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: to recover missed or uncertain state proactively, rather than to rely on an event's redelivery.
  • scope: a fine-grained permission that a token carries and an operation requires, such as connect-channel-platform:orders:upsert.
  • 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: 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: the code of the sub-channel a record belongs to, on the order payloads and on 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: 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: 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: 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: 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.