{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Sync price and stock","description":"Find answers to your technical questions and learn how to integrate Mirakl products.","lang":"en-US","siteUrl":"https://developer.mirakl.com/","keywords":"mirakl, documentation, api","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"sync-price-and-stock","__idx":0},"children":["Sync price and stock"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide shows you how to consume ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/webhooks/webhook/webhooks/pricestockupsertevent"},"children":["PriceStockUpsertEvent"]}," events end to end."," ","This is the continuous, high-frequency stream of price and stock changes for offers that are already live:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Receive the event."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deduplicate and validate it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Read the action of each field."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Apply the changes in the right order, and never let a stale update win."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Push the result to your channel in batches, not one call for each event."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Follow it, and the price and the available quantity of a live offer stay accurate on the channel under real load, without oversell and without exhausting the channel's rate limits."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"business-context","__idx":1},"children":["Business context"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once an offer is live, its ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["pricing"]}," and its ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["available stock"]}," are what change most often."," ","They also matter most at the moment a buyer decides to purchase."," ","Stock moves every time the seller makes a sale, restocks, or rebalances a warehouse."," ","Prices move with promotions, repricing rules, and currency changes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRICE_STOCK_UPSERT"]}," is how every one of those changes reaches the channel."," ","It is the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["highest-frequency and highest-stakes flow in this domain"]},"."," ","The frequency is high because a busy store emits a steady stream of updates."," ","The stakes are high because a buyer sees at once what you get wrong."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The two failure modes are concrete:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Oversell."]}," ","A buyer purchases units the seller no longer has, so the order is cancelled later."," ","This happens when the stock on your channel lags behind reality, because updates were dropped, applied out of order, or delivered too slowly."," ","It is a bad buyer experience, a lost sale, and, on many channels, a seller penalty or a suppressed listing."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Stale price."]}," ","A price change that does not land makes the seller sell too cheaply and lose margin, or too expensively and lose the sale."," ","Both cases are silent for the seller: the listing looks correct in Mirakl Connect, but the channel shows something else."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Handling this flow correctly, fast enough, in order, and idempotently, is what keeps the channel's view of an offer up to date."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/catalog-flow"},"children":["Catalog flow"]}," defines the offer lifecycle and the feedback channel this guide builds on."," ","The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/getting-started/concepts-and-glossary"},"children":["Concepts and glossary"]}," defines the standard price, the discount price, and the stock breakdown against the legacy inventory."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-to-use-this","__idx":2},"children":["When to use this"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Handle ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRICE_STOCK_UPSERT"]}," for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ongoing price and stock changes to an offer that is already active"]}," on the channel."," ","It is the steady-state event for price and stock."," ","Once you have reported an offer as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OFFER_ACTIVE"]},", Mirakl Connect stops sending offer creations for it and sends every later price or stock change as a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRICE_STOCK_UPSERT"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You also receive it ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["before"]}," an offer is active."," ","It is the first event Mirakl Connect sends when a seller selects a product, on the assumption that the offer is already live on the channel."," ","That case is not a steady-state update, and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When not to use this"]}," below covers it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Mirakl Connect ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["always emits ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRICE_STOCK_UPSERT"]}," for active offers, and you cannot disable it."]}," ","Unlike ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OFFER_UPSERT"]},", the channel's catalog configuration does not gate it, and there is no toggle for it."," ","If an offer is active, its price and stock changes flow to you."," ","Treat that as a fact when you design your connector: you cannot opt out of this stream, so build it to absorb the stream at volume."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The event also has ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["use_case"]}," field."]}," ","There is no distinction between a creation and an update here, as there is for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OFFER_UPSERT"]},"."," ","Every ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRICE_STOCK_UPSERT"]}," carries the offer's current price and stock as an update in place, never a choice between a creation and an update."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When not to use this."]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRICE_STOCK_UPSERT"]}," does not create an offer."," ","It never carries the descriptive product data or the offer definition that you need to build one."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OFFER_UPSERT"]}," carries the creation of an offer, the move to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OFFER_ACTIVE"]},", and the price and stock the offer launches with."," ","Read ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/catalog/create-and-update-offers"},"children":["Create and update offers"]}," for everything before the offer is active."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Receiving a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRICE_STOCK_UPSERT"]}," for an offer that is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not yet active is expected"]},", not an error."," ","It is Mirakl Connect's initial probe when a seller first selects a product, sent on the assumption that the offer is already live on the channel."," ","The right response is not to create the offer from this event."," ","Report the offer's true status through feedback, either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OFFER_DOES_NOT_EXIST"]}," or the product's status."," ","That is what makes Mirakl Connect send the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/webhooks/webhook/webhooks/offerupsertevent"},"children":["OfferUpsertEvent"]},", or the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/webhooks/webhook/webhooks/productupsertevent"},"children":["ProductUpsertEvent"]},", that creates it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the same reason, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["do not read this stream as a sign that an item is progressing."]}," ","It keeps flowing for items whose offer status you never reported, and for offers you reported as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTION_REQUIRED"]},"."," ","Neither of them will ever receive a creation attempt."," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/catalog/report-feedback#what-your-report-triggers"},"children":["What your report triggers"]}," sets out which statuses move an item forward."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":3},"children":["How it works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Mirakl Connect emits price and stock changes as they happen."," ","A transport delivers them."," ","Your connector deduplicates them and applies each event to a working state for each offer."," ","Then, on a schedule rather than once for each event, it drains that state to the channel in batches."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The rhythm that matters here is the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["burst"]},": many events for many products arrive close together."," ","The correct shape is to absorb them quickly, then reconcile to the channel efficiently."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","align":"center","diagramType":"mermaid","diagramSource":"sequenceDiagram\n box rgb(219,234,254) Mirakl\n participant P as Mirakl Connect\n end\n box rgb(209,250,229) Middleware\n participant T as Transport\n participant I as Channel Connector\n end\n box rgb(254,240,199) Channel\n participant C as Channel\n end\n\n Note over P: An active offer's price or stock changes\n P--)T: PRICE_STOCK_UPSERT (bursts, many per product_id)\n T--)I: Deliver events (at-least-once, ordered per product_id)\n I->>I: Deduplicate on envelope id\n I->>I: Apply per-field action_type into a per-offer working state\n Note over I: Serialize per product_id, newer event time wins within a key\n\n loop On a schedule, not per event\n I->>I: Drain state, collapse to the latest value per product_id\n I->>C: One batched update (many SKUs, one call)\n alt Channel accepts\n C-->>I: Applied\n else Channel rejects a SKU\n C-->>I: Rejected, for example a price below a channel floor\n I->>P: updateStoreCatalogItems (offer_diagnostics for the seller)\n end\n end\n","diagramHtml":"","diagramHtmlDark":""},"children":["sequenceDiagram\n box rgb(219,234,254) Mirakl\n participant P as Mirakl Connect\n end\n box rgb(209,250,229) Middleware\n participant T as Transport\n participant I as Channel Connector\n end\n box rgb(254,240,199) Channel\n participant C as Channel\n end\n\n Note over P: An active offer's price or stock changes\n P--)T: PRICE_STOCK_UPSERT (bursts, many per product_id)\n T--)I: Deliver events (at-least-once, ordered per product_id)\n I->>I: Deduplicate on envelope id\n I->>I: Apply per-field action_type into a per-offer working state\n Note over I: Serialize per product_id, newer event time wins within a key\n\n loop On a schedule, not per event\n I->>I: Drain state, collapse to the latest value per product_id\n I->>C: One batched update (many SKUs, one call)\n alt Channel accepts\n C-->>I: Applied\n else Channel rejects a SKU\n C-->>I: Rejected, for example a price below a channel floor\n I->>P: updateStoreCatalogItems (offer_diagnostics for the seller)\n end\n end\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Three properties of this flow shape everything below:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Delivery is at-least-once, and ordered only for each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]},"."]}," ","The same event can arrive twice, and events for different SKUs can overtake one another."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Forwarding each event straight to the channel does not scale"]},", because the volume is high."," ","The value is in buffering the events, collapsing them to the latest state for each offer, and exporting in batches."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["One offer can produce several events for one change"]},", when the channel prices or stocks per sub-channel."," ","Read ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#offers-priced-and-stocked-per-sub-channel"},"children":["Offers priced and stocked per sub-channel"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"offers-priced-and-stocked-per-sub-channel","__idx":4},"children":["Offers priced and stocked per sub-channel"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A channel can declare that its prices and its stock are per sub-channel, instead of once for the store."," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/catalog-configuration#price-and-stock-lifecycle"},"children":["Price and stock lifecycle"]}," holds the declaration, and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/stores#sub-channels"},"children":["Sub-channels"]}," holds the list a store carries."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Three things change for your connector."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Mirakl Connect sends one event for each pair of offer and sub-channel."]}," ","A store with three sub-channels produces three events for one price change, and each event names its sub-channel in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sub_channel"]}," block."," ","Read that block first, and apply its values to the sub-channel it names."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Several events now share one ordering key."]}," ","The partition key stays the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]},", so the events of one offer arrive in order across its sub-channels."," ","Key your working state on the pair of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sub_channel.code"]},", and not on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]}," alone."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The stock breakdown moves into the block."]}," ","When the stock is per sub-channel, the store-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stock"]}," arrives as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IGNORE"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sub_channel.stock"]}," carries the breakdown."," ","Stock has no store-level fallback, so a connector that reads the store-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stock"]}," alone sees no quantity at all."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sub_channel"]}," block holds four fields:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]},": the sub-channel this event applies to."," ","It is the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," your connector declared for that sub-channel on the store."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["standard_price"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discount_price"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stock"]},": the same three dimensions as at the store level, each one with its own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_type"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["per_store_default"]}," the channel declared decides what the store-level prices mean next to the block."," ","Under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNSUPPORTED"]}," they arrive as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IGNORE"]},", and under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REQUIRED"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OPTIONAL"]}," they carry the store's default price."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-by-step","__idx":5},"children":["Step by step"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-receive-the-event","__idx":6},"children":["1. Receive the event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You receive ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRICE_STOCK_UPSERT"]}," on the queue or the topic your subscription delivers to: AWS SQS, Google Pub/Sub, or Azure Service Bus."," ","The body is identical on all three, and it arrives in the standard event envelope: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["time"]},", and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," object with the price and stock payload."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"01jv299c9vvxkrjbq1cf58fn1v\",\n \"time\": \"2024-05-20T10:15:30.500Z\",\n \"type\": \"PRICE_STOCK_UPSERT\",\n \"data\": {\n \"channel_id\": \"001\",\n \"store_id\": \"2005\",\n \"product_id\": \"SKU_123456\",\n \"inventory\": {\n \"action_type\": \"UPDATE\",\n \"quantity\": 500,\n \"delivery_partner\": { \"name\": \"__self__\" }\n },\n \"stock\": {\n \"action_type\": \"UPDATE\",\n \"breakdown\": [\n { \"type\": \"SELLER_WAREHOUSE\", \"warehouse\": { \"id\": \"WH_PARIS\" }, \"quantity\": 300 },\n { \"type\": \"SELLER_WAREHOUSE\", \"warehouse\": { \"id\": \"WH_LYON\" }, \"quantity\": 200 }\n ]\n },\n \"standard_price\": {\n \"action_type\": \"UPDATE\",\n \"price\": { \"currency\": \"EUR\", \"amount\": 29.99 }\n },\n \"discount_price\": {\n \"action_type\": \"UPDATE\",\n \"price\": { \"currency\": \"EUR\", \"amount\": 24.99 },\n \"start_date\": \"2024-05-20T10:15:30.500Z\",\n \"end_date\": \"2024-06-20T10:15:30.500Z\"\n },\n \"offer_attributes\": [\n { \"type\": \"TEXT\", \"id\": \"label\", \"value\": \"My first SKU\" }\n ],\n \"identifiers\": [\n { \"type\": \"GTIN\", \"value\": \"1234567890123\" }\n ]\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Key fields in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_id"]}]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["store_id"]}]},": the channel and the seller store this offer belongs to."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]}]},": the product reference, also called the SKU."," ","It identifies the offer within the store, it is the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["partition key"]}," for the ordering (step 4), and it is the identifier you report feedback against (step 6)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stock"]}]},": the quantity for each location, which is the model to build against."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inventory"]}]}," is the legacy aggregated form, kept for backward compatibility (step 3)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["standard_price"]}]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discount_price"]}]},": the two prices, each with an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_type"]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ currency, amount }"]}," value."," ","Both are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," on this event (step 2)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offer_attributes"]}]},": the channel-specific attributes, each one typed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TEXT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NUMERIC"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BOOLEAN"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LIST"]},"."," ","This field is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["present on every ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRICE_STOCK_UPSERT"]}]}," (step 2)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifiers"]}]},": the standard product codes, such as a GTIN."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sub_channel"]}]},": the price and the stock of the one sub-channel this event applies to."," ","It is present only when the channel prices or stocks per sub-channel, and it is omitted otherwise."," ","Read ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#offers-priced-and-stocked-per-sub-channel"},"children":["Offers priced and stocked per sub-channel"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Acknowledge the message on your queue once you have stored the event."," ","A message you leave unacknowledged returns to the queue, and you receive it again."," ","Read ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/receiving-events#acknowledging-a-message"},"children":["Acknowledging a message"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-deduplicate-then-read-each-fields-action_type","__idx":7},"children":["2. Deduplicate, then read each field's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_type"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Delivery is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["at-least-once"]},", so the same event arrives more than once from time to time."," ","Before you act, deduplicate on the envelope ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", a ULID that identifies the event."," ","Make a repeat delivery a no-op."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Then read the payload as a set of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["independent actions, one for each field"]},", rather than as a single blob."," ","Each of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inventory"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stock"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["standard_price"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discount_price"]}," carries its own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_type"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UPDATE"]}]},": set this dimension to the value in the event."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}]},": clear this dimension."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IGNORE"]}]},": leave this dimension exactly as it is on the channel, because the event does not change it."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is why a single event can change one dimension and leave the others alone."," ","A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRICE_STOCK_UPSERT"]}," can carry ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["only a stock change"]},", with the stock as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UPDATE"]}," and the prices as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IGNORE"]},"."," ","It can carry ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["only a price change"]},", with the prices as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UPDATE"]}," and the stock as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IGNORE"]},"."," ","It can also carry ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["both"]},"."," ","A dimension you must not touch arrives as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IGNORE"]},", and because the price fields are optional on this event, it can also be absent."," ","The rule is the same in both cases: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["do not clear what the event did not ask you to change."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The natural ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}," case is the end of a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["discount price"]},"."," ","A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discount_price"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_type: DELETE"]}," clears the promotional price, and the standard price applies again."," ","A standard price, by contrast, is only ever set with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UPDATE"]}," or left unchanged with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IGNORE"]},", because an active offer always has a list price."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two field requirements on this event differ from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OFFER_UPSERT"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The prices are optional."]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["standard_price"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discount_price"]}," are not required fields on a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRICE_STOCK_UPSERT"]},"."," ","A change to the stock alone does not have to carry them at all."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offer_attributes"]}," is required."]}," ","Every ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRICE_STOCK_UPSERT"]}," carries the offer's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offer_attributes"]},", even when the event changes only the stock or the price."," ","Read them as the attributes' current state."," ","Do not treat their presence as a signal that the attributes changed."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Applying the same complete event twice must leave the offer in the same state as applying it once."," ","Honour the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_type"]}," of each field, and your handler stays idempotent on top of the deduplication store above."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-apply-the-stock-model","__idx":8},"children":["3. Apply the stock model"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The availability arrives in two forms in the same event, and only one of them is the model to build against:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stock"]}]}," is the current model."," ","It holds a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["breakdown"]}," of entries, one for each location, and each entry carries its own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quantity"]},"."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," of each entry says which of three kinds it is:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SELLER_CENTRALIZED"]}]},": stock that is not tied to a location, as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ type, quantity }"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SELLER_WAREHOUSE"]}]},": stock in a specific warehouse, as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ type, warehouse: { id }, quantity }"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FULFILLMENT_PARTNER"]}]},": stock held by a fulfillment partner, as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ type, partner: { id }, quantity }"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sum or map the entries to your channel's stock model, as the channel expects."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inventory"]}]}," is the legacy aggregated form."," ","It is a single ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quantity"]},", kept for backward compatibility."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Build against ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stock"]}]},", and treat ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inventory"]}," as the aggregated view that some existing integrations still consume."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stock"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inventory"]}," carry their own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_type"]},", so apply a stock change only when its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_type"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UPDATE"]}," (step 2)."," ","When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stock.action_type"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UPDATE"]},", the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["breakdown"]}," is the offer's complete, current set of quantities for each location."," ","Apply it as the offer's stock, not as a delta to add."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-preserve-per--product_id-ordering-and-guard-against-stale-writes","__idx":9},"children":["4. Preserve per-",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]}," ordering and guard against stale writes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two independent mechanisms keep a high-frequency stream correct."," ","You need both."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The ordering is guaranteed only for each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]},"."]}," ","Events that share a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]}," are delivered in order relative to one another."," ","There is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no ordering guarantee across different products"]},", so events for two SKUs can arrive in any order, and often in parallel."," ","In practice, keep the processing of one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sequential"]},", so that a later event for a SKU never overtakes an earlier one."," ","Process different SKUs ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["concurrently"]},", so that the throughput keeps up with the burst."," ","Do not force everything through one global queue."," ","That trades a correctness problem you do not have, because there is no cross-key ordering to preserve, for a throughput problem you cannot afford on the highest-frequency flow."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Guard every write with the event ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["time"]},"."]}," ","Because delivery is at-least-once, a duplicate or a retry of an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["older"]}," event can arrive after you have already applied a newer one."," ","Protect against it with a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["last-write-wins"]}," rule keyed on the envelope ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["time"]},"."," ","Apply an update to a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]}," only when its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["time"]}," is newer than the last update you applied for that SKU, and drop it otherwise."," ","Together with the per-",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]}," ordering and the deduplication on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," from step 2, this makes replays and out-of-order duplicates safe."," ","A stale event can never overwrite newer state."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guard is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["internal to your connector"]},", and it is keyed on the event's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["time"]}," field."," ","It is not a timestamp you send back to Mirakl Connect, and this domain has no anti-replay watermark that you attach to the calls you make."," ","The correctness story here is the envelope ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", the per-",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]}," ordering, and your own guard on the event time."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Key the guard on the pair of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sub_channel.code"]}," when the channel prices or stocks per sub-channel."," ","One change then produces several events that share a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]}," and carry the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["time"]},", so a guard keyed on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]}," alone keeps the first event and drops every other sub-channel."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"5-batch-and-throttle-toward-the-channel","__idx":10},"children":["5. Batch and throttle toward the channel"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The most important design choice on this flow is to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["decouple the consumption from the export."]}," ","Do not push one channel update for each event you receive."," ","Instead:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Absorb the events into a working state for each offer."]}," ","As events arrive, apply them (steps 2 to 4) to a durable record, keyed on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]},", of the offer's latest price and stock."," ","Key it on the pair of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sub_channel.code"]}," when the channel prices or stocks per sub-channel."," ","A burst of events for one SKU collapses into one current state."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Drain on a schedule, in batches."]}," ","On a cadence you control, take the offers whose state changed since your last export and send them to the channel in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["one batched update that covers many SKUs"]},", rather than one call for each SKU."," ","Ten changed offers become one channel call, not ten."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Drop the no-op events before you export."]}," ","An event whose price, discount, and stock are all ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IGNORE"]}," changes nothing."," ","Filter it out, so that it never produces an empty channel update."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry with rate-limit awareness."]}," ","Channels enforce their own rate limits."," ","Back off on the channel's throttling signals and retry with exponential backoff, so that a burst never turns into a wall of rejected calls."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because you collapse to the latest state for each offer before you export, the intermediate values within a burst never need to reach the channel."," ","You send where the offer ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ended up"]},", not every step it passed through."," ","That is what lets a high-frequency stream stay accurate and stay within the channel's limits."," ","For how to batch feedback and channel writes at scale, read ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/catalog/report-feedback"},"children":["Report feedback"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"6-surface-rejections-through-feedback","__idx":11},"children":["6. Surface rejections through feedback"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Most ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRICE_STOCK_UPSERT"]}," events need no reply."," ","You apply the change and move on."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The channel can still reject an update: a price below a channel floor, a quantity it will not accept, or a rule the offer now violates."," ","When that happens, do not let the rejection disappear into a log."," ","Surface it through the same ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/rest/connect/openapi3/product-feedback/updatestorecatalogitems"},"children":["updateStoreCatalogItems"]}," feedback operation, with an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offer_diagnostics"]}," message the seller can act on, exactly as for a blocked offer creation."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST https://miraklconnect.com/api/channel-platform/v1/channel-catalog/001/store-catalog-items/2005\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]},", the SKU, keys the item."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offer_diagnostics"]}," list is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["full-replace"]},": send the complete set of the offer's currently active problems, and send an empty list to clear them once you resolve the issue."," ","The mechanics of this operation are the same as in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/catalog/create-and-update-offers"},"children":["Create and update offers"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/catalog/report-feedback"},"children":["Report feedback"]},"."," ","Use them here, so that a rejected price or stock change does not become an invisible gap between the channel and Mirakl Connect."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"complete-example","__idx":12},"children":["Complete example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A realistic burst: three ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRICE_STOCK_UPSERT"]}," events for two offers, arriving close together, and one offer changes twice."," ","Both offers are already ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OFFER_ACTIVE"]}," on channel ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["001"]}," for store ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2005"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["1. The burst arrives."]}," ","In quick succession you receive three events."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Event A"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKU_123456"]}," is restocked."," ","The stock is updated, and the prices are left alone."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"01jv299c9vvxkrjbq1cf58fn1v\",\n \"time\": \"2024-05-20T10:15:30.500Z\",\n \"type\": \"PRICE_STOCK_UPSERT\",\n \"data\": {\n \"channel_id\": \"001\",\n \"store_id\": \"2005\",\n \"product_id\": \"SKU_123456\",\n \"inventory\": { \"action_type\": \"UPDATE\", \"quantity\": 500 },\n \"stock\": {\n \"action_type\": \"UPDATE\",\n \"breakdown\": [\n { \"type\": \"SELLER_WAREHOUSE\", \"warehouse\": { \"id\": \"WH_PARIS\" }, \"quantity\": 300 },\n { \"type\": \"SELLER_WAREHOUSE\", \"warehouse\": { \"id\": \"WH_LYON\" }, \"quantity\": 200 }\n ]\n },\n \"standard_price\": { \"action_type\": \"IGNORE\" },\n \"discount_price\": { \"action_type\": \"IGNORE\" },\n \"offer_attributes\": [ { \"type\": \"TEXT\", \"id\": \"label\", \"value\": \"My first SKU\" } ],\n \"identifiers\": [ { \"type\": \"GTIN\", \"value\": \"1234567890123\" } ]\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Event B"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKU_777888"]}," gets a new list price."," ","The stock is left alone."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"01jv299d2xk8m4p0r7t6y5w3qs\",\n \"time\": \"2024-05-20T10:15:31.000Z\",\n \"type\": \"PRICE_STOCK_UPSERT\",\n \"data\": {\n \"channel_id\": \"001\",\n \"store_id\": \"2005\",\n \"product_id\": \"SKU_777888\",\n \"inventory\": { \"action_type\": \"IGNORE\" },\n \"stock\": { \"action_type\": \"IGNORE\" },\n \"standard_price\": { \"action_type\": \"UPDATE\", \"price\": { \"currency\": \"EUR\", \"amount\": 49.99 } },\n \"discount_price\": { \"action_type\": \"IGNORE\" },\n \"offer_attributes\": [ { \"type\": \"TEXT\", \"id\": \"label\", \"value\": \"Second SKU\" } ],\n \"identifiers\": [ { \"type\": \"GTIN\", \"value\": \"9876543210987\" } ]\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Event C"]},": a wave of sales drops the stock of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKU_123456"]}," again."," ","This event is newer than event A."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"01jv299e7bn1c9h5f2d8g6k4za\",\n \"time\": \"2024-05-20T10:15:31.200Z\",\n \"type\": \"PRICE_STOCK_UPSERT\",\n \"data\": {\n \"channel_id\": \"001\",\n \"store_id\": \"2005\",\n \"product_id\": \"SKU_123456\",\n \"inventory\": { \"action_type\": \"UPDATE\", \"quantity\": 460 },\n \"stock\": {\n \"action_type\": \"UPDATE\",\n \"breakdown\": [\n { \"type\": \"SELLER_WAREHOUSE\", \"warehouse\": { \"id\": \"WH_PARIS\" }, \"quantity\": 280 },\n { \"type\": \"SELLER_WAREHOUSE\", \"warehouse\": { \"id\": \"WH_LYON\" }, \"quantity\": 180 }\n ]\n },\n \"standard_price\": { \"action_type\": \"IGNORE\" },\n \"discount_price\": { \"action_type\": \"IGNORE\" },\n \"offer_attributes\": [ { \"type\": \"TEXT\", \"id\": \"label\", \"value\": \"My first SKU\" } ],\n \"identifiers\": [ { \"type\": \"GTIN\", \"value\": \"1234567890123\" } ]\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["2. Your connector acts."]}," ","In order:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Acknowledge each message on the queue."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deduplicate on the envelope ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},"."," ","All three ids are new, so record them and continue."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Group the events by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]},"."]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKU_123456"]}," owns events A and C, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKU_777888"]}," owns event B."," ","Process the two SKUs concurrently, and process A and C for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKU_123456"]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["in order"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKU_123456"]},":"]}," both A and C update the stock and leave the prices as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IGNORE"]},"."," ","A sets the stock to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["300 + 200"]},"."," ","C has the newer ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["time"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["31.200Z"]}," against ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["30.500Z"]},", and sets the stock to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["280 + 180"]},"."," ","Under last-write-wins keyed on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["time"]},", C wins, so the working state ends at ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["460 units, 280 in Paris and 180 in Lyon"]},"."," ","If a duplicate of event A arrived now, its older ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["time"]}," would fail the guard and you would drop it, so it could not restore the stale value of 500 units."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKU_777888"]},":"]}," event B leaves the stock as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IGNORE"]}," and sets the standard price to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["49.99 EUR"]},"."," ","The offer's stock on the channel is untouched."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["3. You export once, in a batch."]}," ","On your export schedule, and not once for each event, you drain the two changed offers and send the channel ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["one batched update"]}," that covers both SKUs: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKU_123456"]}," at 460 units, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKU_777888"]}," at 49.99 EUR."," ","Three events for two products became a single channel call."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["4. The outcome."]}," ","The channel shows ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKU_123456"]}," with 460 available units and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKU_777888"]}," priced at 49.99 EUR."," ","Your working state superseded the intermediate state of 500 units before it ever reached the channel, so you never published a stale quantity and you never opened an oversell window."," ","If the channel had rejected either change, you would report it against that SKU with an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offer_diagnostics"]}," message (step 6), so that the seller could act."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-mistakes","__idx":13},"children":["Common mistakes"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"forwarding-every-event-to-the-channel-one-at-a-time","__idx":14},"children":["Forwarding every event to the channel one at a time"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What it looks like:"]}," the handler pushes a channel update the moment each event arrives, one synchronous channel call for each event received."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The failure:"]}," price and stock is the highest-frequency flow, so a burst of events becomes a burst of channel calls."," ","You reach the channel's rate limits, the channel throttles or rejects the calls, the latency climbs, and the connector falls behind."," ","While it is behind, the stock on the channel is stale, which is exactly the oversell you wanted to prevent."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The fix:"]}," decouple the consumption from the export."," ","Absorb the events into a working state for each offer, collapse them to the latest value for each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]},", and drain on a schedule into batched channel updates that cover many SKUs at once."," ","Drop the no-op events, where every field is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IGNORE"]},", before you export, and retry with a backoff that is aware of the rate limits."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"mishandling-the-ordering-by-serializing-globally-or-reordering-within-a-key","__idx":15},"children":["Mishandling the ordering, by serializing globally or reordering within a key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What it looks like:"]}," either the connector pushes every event through one global lock or queue to be safe, or it fans the events out to workers with no attention to the SKU they belong to, so a later update for a SKU can be applied before an earlier one."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The failure:"]}," a single serial pipeline cannot keep up with a burst, so the throughput collapses, the connector falls behind, and the channel goes stale."," ","In the other case, an older event overwrites a newer one for the same SKU, and the channel shows a stale quantity, which is an oversell, or a stale price."," ","Nothing signals that it went wrong."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The fix:"]}," serialize the processing ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["for each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]}]},", and run different SKUs concurrently."," ","The ordering is guaranteed only for each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]},", never across keys, so there is no global order to preserve and no reason to pay for one."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"treating-a-missing-or-ignore-field-as-clear-this-value","__idx":16},"children":["Treating a missing or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IGNORE"]}," field as \"clear this value\""]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What it looks like:"]}," the handler reads an absent price field, or an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_type"]}," of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IGNORE"]},", as an instruction to remove the value."," ","Or, the other way round, it treats ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}," as a no-op."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The failure:"]}," an event that carries only a stock change, with the prices as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IGNORE"]},", wipes the offer's price on the channel, so the offer becomes mispriced or unsellable."," ","Or a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discount_price"]}," set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}," is skipped, so an expired promotion keeps running."," ","Both failures are silent, and both land on the buyer."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The fix:"]}," honour the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_type"]}," of each field."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IGNORE"]}," means leave the current value on the channel untouched."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UPDATE"]}," means set it."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}," means clear it, so a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discount_price"]}," set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}," ends a promotion and the standard price applies again."," ","A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRICE_STOCK_UPSERT"]}," can carry only the stock, only the prices, or both, and the dimensions it does not change arrive as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IGNORE"]}," or are absent."," ","Note that this is the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["opposite"]}," of the feedback operation you call, which is full-replace."," ","On an event you receive, a field you were not sent is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," a cleared field."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"applying-updates-without-a-stale-write-guard","__idx":17},"children":["Applying updates without a stale-write guard"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What it looks like:"]}," the handler writes whatever it received last to its store and to the channel, with no check on how old the event is."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The failure:"]}," because delivery is at-least-once, a duplicate or a retry of an older event can arrive ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["after"]}," you applied a newer one."," ","With no guard, that stale event overwrites the current stock with an out-of-date quantity."," ","The channel then shows more units than exist, and an oversell window stays open until the next event happens to correct it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The fix:"]}," guard each write with the event's envelope ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["time"]},"."," ","Apply an update for a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]}," only when its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["time"]}," is newer than the last one you applied for that SKU, which is last-write-wins, and drop it otherwise."," ","Together with the per-",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_id"]}," ordering and the deduplication on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", this makes replays and out-of-order duplicates safe."," ","The guard is internal to your connector and keyed on the event's own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["time"]},"."," ","It is not a timestamp you send back to Mirakl Connect."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related","__idx":18},"children":["Related"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/catalog-flow"},"children":["Catalog flow"]},": the lifecycle states and the feedback channel this guide relies on."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/getting-started/concepts-and-glossary"},"children":["Concepts and glossary"]},": the standard price, the discount price, the stock breakdown against the legacy inventory, and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_type"]}," of each field."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/catalog/create-and-update-offers"},"children":["Create and update offers"]},": how an offer is created and reaches ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OFFER_ACTIVE"]}," before any ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRICE_STOCK_UPSERT"]}," flows."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/catalog/report-feedback"},"children":["Report feedback"]},": every status value, the event each pair of statuses triggers, and how to batch the export and report the statuses and diagnostics at scale."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/receiving-events#ordering-per-destination"},"children":["Ordering per destination"]},": the transports that deliver events, AWS SQS, Google Pub/Sub, and Azure Service Bus, and their ordering options."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/webhooks/webhook"},"children":["Event APIs reference"]},": the full payload schema for ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/webhooks/webhook/webhooks/pricestockupsertevent"},"children":["PriceStockUpsertEvent"]}," and every other event."]}]}]},"headings":[{"value":"Sync price and stock","id":"sync-price-and-stock","depth":1},{"value":"Business context","id":"business-context","depth":2},{"value":"When to use this","id":"when-to-use-this","depth":2},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Offers priced and stocked per sub-channel","id":"offers-priced-and-stocked-per-sub-channel","depth":2},{"value":"Step by step","id":"step-by-step","depth":2},{"value":"1. Receive the event","id":"1-receive-the-event","depth":3},{"value":"2. Deduplicate, then read each field's action_type","id":"2-deduplicate-then-read-each-fields-action_type","depth":3},{"value":"3. Apply the stock model","id":"3-apply-the-stock-model","depth":3},{"value":"4. Preserve per- product_id ordering and guard against stale writes","id":"4-preserve-per--product_id-ordering-and-guard-against-stale-writes","depth":3},{"value":"5. Batch and throttle toward the channel","id":"5-batch-and-throttle-toward-the-channel","depth":3},{"value":"6. Surface rejections through feedback","id":"6-surface-rejections-through-feedback","depth":3},{"value":"Complete example","id":"complete-example","depth":2},{"value":"Common mistakes","id":"common-mistakes","depth":2},{"value":"Forwarding every event to the channel one at a time","id":"forwarding-every-event-to-the-channel-one-at-a-time","depth":3},{"value":"Mishandling the ordering, by serializing globally or reordering within a key","id":"mishandling-the-ordering-by-serializing-globally-or-reordering-within-a-key","depth":3},{"value":"Treating a missing or IGNORE field as \"clear this value\"","id":"treating-a-missing-or-ignore-field-as-clear-this-value","depth":3},{"value":"Applying updates without a stale-write guard","id":"applying-updates-without-a-stale-write-guard","depth":3},{"value":"Related","id":"related","depth":2}],"frontmatter":{"seo":{"title":"Sync price and stock"}},"lastModified":"2026-08-28T13:10:01.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/content/product/connect-channel-platform/developer-guide/catalog/sync-price-and-stock","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}