Report statuses and feedbacks

Mirakl Connect learns what an item's state is on the channel only when your connector reports it. This page covers the three steps of that report:

1. Export products and offers to the channel.
2. Capture the item's state on the channel, from your export and from what the channel changes on its own.
3. Report the statuses and the diagnostics of each item through updateStoreCatalogItems.

An export is the common trigger for a report, and it is not the only one. An item lives on the channel after you export it, so its state can change with no export from you.

Mirakl Connect holds no independent view of what is on the channel. Everything it knows about an item comes from the statuses your connector reported last, and it chooses the next event from them. It never observes the channel, so a change the channel makes on its own reaches it through your report alone.

The status you report is also what the seller sees. A seller who works in Mirakl Connect does not watch your connector run, and does not read the channel's API responses. They see one state for each item: the offer is live, or it is blocked with a reason.

So an accurate report advances the item, and a partial report stops it. An offer you exported and never reported stays where it was, so Mirakl Connect keeps waiting for the outcome and the seller sees no reason for the delay. A rejection you logged and never reported reaches nobody who can fix it. A report that states what happened to a creation Mirakl Connect never started leaves the item outside every creation rule, and PriceStockUpsertEvent keeps arriving for it.

Feedback is the pair of statuses plus the diagnostics that you report for each store catalog item: offer_status, offer_diagnostics, product_status, and product_diagnostics. All four travel on updateStoreCatalogItems, in one entry for each store catalog item, keyed by the item's product_id. Catalog flow places this report in the wider catalog synchronization, and Concepts and glossary defines the shared vocabulary.

Call updateStoreCatalogItems whenever you learn the state of an item on the channel. Two triggers lead into it.

After every export attempt, whether it succeeded or failed. This is the common case, and three flows lead into it:

• After you create a product from a ProductUpsertEvent, the report-status step of Create or update products.
• After you create or update an offer from an OfferUpsertEvent, the report-feedback step of Create and update offers.
• After the channel rejects a price or stock change from a PriceStockUpsertEvent, the feedback step of Sync price and stock.

Many channels accept a submission at once and decide each offer separately minutes or hours later, so one export produces outcomes over time. Each late outcome is a new report.

Whenever the channel changes an item on its own, with no export from you. An item you exported keeps living on the channel, and the channel decides its state there:

• The channel deactivates or removes an offer that was live, for a policy problem, a compliance problem, or a rule of its own.
• The channel approves or refuses a product days after you submitted it.
• The seller edits the listing in the channel's own back office.
• The channel reopens an offer it had blocked.

Report each of these the same way, because Mirakl Connect learns of none of them by itself.

When not to use this. Receiving, mapping, deduplicating, and ordering events belongs to Create and update offers and Sync price and stock. This page starts once you know what the channel holds for an item.

Mirakl Connect sends you the product, offer, and price and stock events of a store. You apply them to a durable state, and you export a batch of items to the channel. The channel returns some outcomes in the export response and others later. You collect the outcomes into one current status for each item, and you report them in one call. Mirakl Connect advances each item's lifecycle from what you reported, and it chooses the next event from the new statuses. The seller sees the result. Later, the channel can change the same item on its own, and that change is a new report with no export in front of it.

The export is specific to the channel, and Mirakl Connect does not define it. It can be a feed submission, a bulk listings API, or one call for each offer. What Mirakl Connect defines is what you do with the outcome, from step 2 onward.

An export may produce outcomes in two waves:

• Synchronous outcomes come back in the export response. Some channels answer inline that they accepted or rejected a SKU. Capture these against the offer at once.
• Asynchronous outcomes arrive later, out of band. They come as a feed-result document you poll for, or as a notification the channel sends when it finishes the processing. Until that result lands, the channel has accepted the submission and the offer's real outcome is unknown.

Drive the asynchronous results from the submission you recorded in step 1:

• When a result arrives, match it to the submission and mark the SKUs it covers as processed. Deduplicate the repeated deliveries of one result, so that you never apply it twice.
• Give each pending submission a bounded number of retries, and a terminal failed state once you give up. A result that never arrives then becomes a condition you can report, instead of an offer that stays submitted forever.
• Compare the SKUs you submitted against the SKUs the result names. A SKU you exported and the channel never reported on needs the same attention as a rejection.
• Advance your export checkpoint once the matching feedback call returns 202, and not when the export to the channel returns. A crash between the two then replays the report instead of losing it.
• Track the age of the oldest outcome you have not reported yet. A result you captured and never reported leaves Mirakl Connect's view frozen, and no other signal shows it.

An offer that went live keeps living on the channel, and the channel governs it from then on. It can deactivate the offer, remove it, block it for a compliance problem, approve a product it had held, or reopen an offer it had blocked. The seller can also edit the listing in the channel's own back office. None of this passes through Mirakl Connect, and none of it follows an export of yours.

Two mechanisms bring you these changes, and a channel rarely offers only one:

• The notifications the channel sends. Subscribe to every listing event and product event the channel publishes, and treat each one as a state to report.
• Reconciliation on a schedule. Read the channel's current state for the store's items, compare it against the statuses you reported last, and report every difference. This is the only mechanism that catches a change the channel never announced.

Pick a reconciliation cadence from how fast the channel moves and how many items the store holds. Reconcile the items you reported as OFFER_ACTIVE first, because a deactivation there is the change that costs the seller a sale and shows no other signal.

This step produces, for each item, one current state to translate into the statuses of step 3. The source does not change what you report, and it does not change the call.

An item carries two statuses and two diagnostics lists. Report the status for the state you observed on the channel, and report both statuses in the same call whenever you know both.

Report product_status to tell Mirakl Connect where the product stands on the channel.

Report offer_status to tell Mirakl Connect where the offer stands on the channel.

An offer waiting for its product is an offer that Mirakl Connect holds back until its product exists on the channel:

• Mirakl Connect puts the offer in this state when you report product_status: PRODUCT_DOES_NOT_EXIST, whatever offer_status the same call carries.
• You cannot report this state, because it is not a value of offer_status.
• While the offer waits, Mirakl Connect sends no offer event, no price, and no stock for it.
• The offer leaves the state on its own when you report product_status: PRODUCT_CREATED, and Mirakl Connect then attempts the offer creation.

• The product is not on the channel. Report product_status: PRODUCT_DOES_NOT_EXIST, with a product diagnostic that says so. Report it before you create the product, because it is what asks Mirakl Connect for the product data.
• The product is already on the channel, and you created nothing. Report offer_status: OFFER_DOES_NOT_EXIST on its own, and leave product_status out of the call. PRODUCT_CREATED reports the outcome of a creation you asked for, so it has nothing to say about a product that was already there. The offer creation follows from the offer status alone.
• You submitted the product, and the channel is reviewing it. Report product_status: PRODUCT_PENDING_APPROVAL.
• The channel created the product you submitted. Report product_status: PRODUCT_CREATED. Report it only after you reported PRODUCT_DOES_NOT_EXIST for the same item, because that is what put the product creation in flight.
• The channel refused the product. Report product_status: PRODUCT_REFUSED, with the refusal reason as a product diagnostic.
• The offer is not on the channel, and its product is. Report offer_status: OFFER_DOES_NOT_EXIST.
• The channel accepted the offer, and it is live. Report offer_status: OFFER_ACTIVE.
• The seller must fix something before the item can go live. Report ACTION_REQUIRED on the status that is blocked, with a diagnostic that says what to correct. Report OFFER_DOES_NOT_EXIST again once the blocker clears, because ACTION_REQUIRED schedules no retry.
• The channel removed an offer that was live, and a new attempt would succeed. Report offer_status: OFFER_DOES_NOT_EXIST, which asks Mirakl Connect for a new creation attempt.
• The channel blocked an offer that was live, and a new attempt would fail the same way. Report offer_status: ACTION_REQUIRED, with a diagnostic that carries the channel's reason. This is the case for a policy problem or a compliance problem, where the seller must act first.
• You submitted something, and no outcome has come back yet. Report nothing for that status, because neither field has a pending value.

A diagnostic is a message that a human can read and that explains a problem. It can also point at the product attribute or the offer attribute at fault, through channel_attribute_id. Diagnostics are how you explain why an item is ACTION_REQUIRED or PRODUCT_REFUSED, and the seller reads them as the instructions to fix it. An item that is action-required with no diagnostic tells the seller that something is wrong, and not what.

Write every message for the seller. A diagnostic is not a debug channel for your connector. The seller reads it in Mirakl Connect, and they know their own catalog, not your connector and not the channel's API. So state the business fact and the action: what the channel refuses, on which attribute, and what it expects instead.

• Keep the technical detail out of the message: the channel's error code, the HTTP status, the payload fragment, the field path, and any internal identifier. Log that in your connector, where you are the one who reads it.
• channel_diagnostic_id carries the channel's own diagnostic identifier, so send the code there and leave the message readable.
• Name the attribute the way the seller knows it, and set channel_attribute_id so that Mirakl Connect resolves the label itself.
• Say what to do. A message that only states the refusal leaves the seller to guess the fix.

Three rules govern the two lists:

• They are full-replace. Every report must carry the item's complete current set of active diagnostics, up to 100 in each list. The list is not additive. Send the whole set each time, and send an empty list to clear the diagnostics once the seller resolves the problem.
• They inform, and they do not transition. A diagnostic explains a status. It never moves an item to a new state on its own, and a diagnostics list sent without a status changes no status.
• They carry the attribute at fault. Set channel_attribute_id to the id of the channel attribute the channel rejected. Mirakl Connect groups the diagnostics by attribute, and the group is what lets the seller fix every product it blocks in one action. Read What the seller does with the diagnostics.

Report the outcome of each store catalog item with updateStoreCatalogItems.

POST https://miraklconnect.com/api/channel-platform/v1/channel-catalog/001/store-catalog-items/2005

The path carries the channel_id, 001, and the store_id, 2005. The body is one array, store_catalog_items, of up to 10,000 items. The id of an item is its product_id, the SKU from the event you handled. Each item carries the product_status, the offer_status, and the matching product_diagnostics and offer_diagnostics that step 3 gave you.

Send every status you know for a SKU in the same item entry. Mirakl Connect resolves the two statuses against each other for each call, so splitting them across two calls does not give the result of sending them together. A status you leave out keeps the value you reported last, and it does not fall back to a default. How a report changes the state sets out the three resolution rules.

A batch that reports one live offer and one blocked offer looks like this:

{
  "store_catalog_items": [
    {
      "id": "SKU_123456",
      "offer_status": "OFFER_ACTIVE",
      "offer_diagnostics": []
    },
    {
      "id": "SKU_234567",
      "offer_status": "ACTION_REQUIRED",
      "offer_diagnostics": [
        {
          "message": "The channel rejected the offer: the required attribute \"condition\" is missing. Set it so the offer can be published.",
          "channel_attribute_id": "condition"
        }
      ]
    }
  ]
}

The live offer carries an empty offer_diagnostics, which clears any problem it reported before. The blocked offer carries a diagnostic anchored to the attribute at fault. Report each item against the store that owns it, and batch many items in each call.

The operation is asynchronous. A successful call returns 202 Accepted, which means Mirakl Connect queued the report, and not that it applied it. Two other responses exist, and both are about the request, never about one item:

• 404: Mirakl Connect does not know the channel or the store in the path. Check the identifiers, and do not send the same call again.
• 400: the body is malformed. Fix it, because a bad request fails the same way on a retry.

Inside an accepted request, Mirakl Connect processes each item on its own:

• Mirakl Connect ignores an unknown product id silently. When the id of an item is a SKU Mirakl Connect does not know, it drops that item without an error and processes the items it matched. A dropped id usually means the item's product was not synchronized first, so reconcile that state instead of sending the report again.
• The 202 acknowledges no individual item. It does not name the items that matched, so track which items you reported and with which statuses, and drive step 6 from that record.
• One problematic item holds back no other. When you cannot determine one item's outcome, leave that item out and report the rest. Never hold back a batch of confirmed outcomes while you wait on one item.
• A channel rejection is an outcome to report, and not a failure of your pipeline. Turn it into an ACTION_REQUIRED item with a diagnostic, and send it next to the successes.

An item's statuses change for as long as the seller keeps it in the selection. A pending submission resolves, the channel rejects a live offer after a review, the seller fixes a blocked offer, or the channel deactivates an offer months after you exported it. Each change is a new report, and the last one is a report your connector sends with no export behind it. updateStoreCatalogItems is idempotent, so sending an item again with its latest statuses replaces what Mirakl Connect holds.

Four rules keep the reports correct:

• Report a pending item once its asynchronous result lands. Leave it out of the current call, and report it in a follow-up.
• Collapse the outcomes of one item to its latest state before you send. When a synchronous acceptance and a later asynchronous rejection describe the same offer, merge them on the channel's outcome time and report the result. The operation has no anti-replay guard, so reporting an old outcome after a newer one regresses the item.
• Never hide a blocking outcome behind a live one. In the merge, an action-required outcome and a rejected outcome win over a live one for the same item.
• Keep reporting an item after it goes live. OFFER_ACTIVE is not a terminal state, and the channel can leave it at any time. A connector that stops watching an item once it is active never reports the day it stops selling.

Each report also replaces the item's diagnostics, so send the current set every time.

Mirakl Connect chooses the next event from the pair (product and offer) of statuses.

Find the row that matches the state of the item.

• If you report PRODUCT_DOES_NOT_EXIST for an item whose offer you had already reported as OFFER_ACTIVE, every event stops. The offer waits for its product, so the price, the stock, and the offer updates stop. Mirakl Connect does not send the product again either, because the offer was active once. Report PRODUCT_CREATED once the product is back on the channel, and the offer creation follows.

• Report OFFER_ACTIVE only for an item whose product you do not need to edit again. From that report on, Mirakl Connect sends no ProductUpsertEvent for the item, whatever product status you report later.

Three rules govern how Mirakl Connect resolves the two fields in a single call. It evaluates them for each call, which is why splitting a report across two calls does not give the result of sending both statuses together.

• Report both statuses in the same call whenever you know both. The product_status in a call decides how Mirakl Connect interprets the offer_status in that same call.
• PRODUCT_DOES_NOT_EXIST overrides the offer status sent with it. If a call carries it, Mirakl Connect parks the offer as waiting for its product, even if the same call reports OFFER_ACTIVE. Drive the product to PRODUCT_CREATED first, and only then does the offer status you reported take effect. No other product status does this. PRODUCT_PENDING_APPROVAL and a product-level ACTION_REQUIRED both let the offer status through unchanged.
• PRODUCT_REFUSED discards the offer status sent with it. A refused product has no sellable offer, so the offer keeps whatever status it had.

Mirakl Connect leaves untouched everything you omit. There is no way to return a status to "never reported". The only way out of a state is to report a new value for it.

A seller never sees product_status or offer_status. Mirakl Connect combines the two statuses your connector reports with the store's settings, such as whether price synchronization is switched on, into a single state shown for each product in the seller's catalog. There are five:

Because the seller sees one combined state, what your connector reports maps onto it like this:

• The product is not created yet, or the offer is created and the price and stock are still synchronizing: the seller sees Synchronizing.
• product_status: PRODUCT_PENDING_APPROVAL while the offer waits for its product: the seller sees Pending approval. With an offer status you reported, the seller sees the state of that offer status.
• product_status: PRODUCT_REFUSED with diagnostics: the seller sees Rejected, with your diagnostics as the reason.
• product_status: ACTION_REQUIRED with diagnostics, while the offer waits for its product: the seller sees Action required, with your diagnostics as the fix instruction. With OFFER_ACTIVE, the seller sees Active, and the diagnostics stay on the product page.
• offer_status: ACTION_REQUIRED with diagnostics: the seller sees Action required, with your diagnostics as the fix instruction.
• offer_status: OFFER_ACTIVE: the seller sees Active.

Two rules determine which state the seller sees:

• While the offer waits for its product, the product's state leads. Once the product is created, the offer's state leads. This follows the resolution rules between the two statuses.
• The same reported statuses can surface differently between stores, because the combined state also depends on that store's settings. Mirakl Connect computes the exact combination. What your connector controls is the accuracy of the two statuses and the clarity of the diagnostics.

The seller works from the diagnostics, and not from the statuses. Mirakl Connect groups the diagnostics of a store by message, then by channel_attribute_id, and it counts the products of each group. The seller reads one line for each group: the message, the label of the attribute at fault, and the number of products the group blocks. Mirakl Connect orders those lines by the requirement level of the attribute, then by the product count, so a required attribute comes before a recommended one.

The attribute id is also what makes a bulk correction possible: one action that fixes every product of the group. Mirakl Connect selects the products of a bulk correction by the attribute id their diagnostics carry, and it reads product_diagnostics for it. A group with no attribute id gets no bulk correction, so the seller opens each product and fixes it one by one.

Three rules follow, and product_diagnostics is where they matter most.

• Set channel_attribute_id on every diagnostic you can. Mirakl Connect groups by attribute only when every diagnostic of the group carries one. One diagnostic without it removes the attribute from the whole group, so a partial report removes the bulk correction for every product that shares the message. A diagnostic with no attribute id also has no requirement level, so its line comes after every other one.
• Send an attribute id the taxonomy holds. Mirakl Connect reads the attribute's label from the taxonomy you declared for the channel. An id the taxonomy does not hold has no label, so the seller reads the raw id.
• Write the message for the problem, and not for the product. The message is the grouping key, and Mirakl Connect matches it exactly. A message that carries the SKU or the value the channel rejected makes one group for each product, so the count and the bulk correction lose their value.

What it looks like: the connector logs the channel's rejection and moves on, or it skips the offers it cannot handle, such as an offer that misses an identifier it expected.

The failure: Mirakl Connect leaves the item where it was, and the seller sees an offer that never appears and no reason for it.

The fix: report every rejection as ACTION_REQUIRED with a diagnostic the seller can act on, and name the channel_attribute_id at fault where you can (step 3). Reserve a silent skip for a genuine no-op.

What it looks like: the connector reads the 2xx on the export call as a confirmation, and reports OFFER_ACTIVE as soon as the channel accepts the submission.

The failure: on a channel that decides each offer asynchronously, the acceptance means queued alone, and the channel can still reject the offer minutes later. Mirakl Connect then stops sending creations for an offer that never went live, and no signal shows it.

The fix: report OFFER_ACTIVE only once you hold the channel's confirmation for that offer (step 2). Until then the item has no status, so leave it out of the call and report it in a follow-up (step 6).

What it looks like: the connector creates the product on the channel before it reports anything for the item. Its first report is product_status: PRODUCT_CREATED, and it waits for an OfferUpsertEvent to build the offer.

The failure: Mirakl Connect never sends an offer event. The offer status has never been reported, and the offer is not waiting for its product, so the item matches no offer creation rule. Price and stock events keep arriving for it, so the connector gets no signal, and the seller sees an offer that never appears.

The fix: report the missing state before you report the outcome.

• Report product_status: PRODUCT_DOES_NOT_EXIST the moment you find the product absent.
• Report product_status: PRODUCT_CREATED once the channel confirms the product. You do not need an offer status in the same call, because the offer leaves the wait on its own.
• If the product is already on the channel when you first report the item, report offer_status: OFFER_DOES_NOT_EXIST alone.

PRODUCT_CREATED is the answer to a creation you asked for, and it is never the first thing you report for an item.

What it looks like: the connector treats the arrival of price and stock events for an item as a confirmation that its lifecycle is advancing.

The failure: price and stock events flow for items you never reported at all, and for offers stuck in ACTION_REQUIRED. They are the least conditional event Mirakl Connect sends, so they are the weakest evidence that an item is progressing.

The fix: track each item's reported statuses yourself, and reconcile them against what the channel holds. An item whose offer status has been absent or ACTION_REQUIRED for a long time is a candidate for reconciliation, however much traffic it receives.

What it looks like: the connector copies the channel's API error into message, with its error code, its field path, and the fragment of the payload it refused.

The failure: the seller cannot act on it. An error code and a field path name nothing the seller owns, so they do not know which value to change. The message also changes with the payload, so each product makes its own group, and the count and the bulk correction lose their value.

The fix: translate the channel's error into the business fact and the action before you report it (step 3). Send the channel's code in channel_diagnostic_id, and the attribute at fault in channel_attribute_id.

What it looks like: the connector reports ACTION_REQUIRED with the channel's message and leaves channel_attribute_id empty, because the message already names the field in its text.

The failure: Mirakl Connect cannot group the diagnostic by attribute, so it offers the seller no bulk correction for it. One such diagnostic removes the attribute from every product that shares the message, and its line comes after every other one. The seller reads the problem, and fixes it one product at a time.

The fix: map the channel's error onto the attribute at fault, and send that attribute's id in channel_attribute_id (step 3). Send an id the taxonomy holds, so the seller reads the attribute's label and not the raw id.

What it looks like: the connector sends only the new diagnostic in each call, or it sends an empty list in every report while the item still has active problems, or it sends a list with no status.

The failure: sending one diagnostic replaces the list and drops the others, so the seller sees an incomplete set of problems. Sending an empty list clears every problem, so an active one looks resolved, and never sending an empty list leaves a stale diagnostic after the offer goes live. Sending a list with no status applies the diagnostics and leaves the status exactly as it was, so an item you never reported stays outside every creation rule.

The fix: send the complete set of the item's active diagnostics in every report, an empty list exactly when no problem is left, and always the status that the diagnostics describe (step 3). An empty list means the item has no active problem, and only a status says that the item is live.

What it looks like: the connector reports after each export and at no other time. It has no subscription to the channel's listing notifications, and it never re-reads the channel's state for the items it reported as OFFER_ACTIVE.

The failure: every change the channel makes on its own is invisible. An offer the channel deactivated for a compliance problem stays OFFER_ACTIVE in Mirakl Connect, so the seller reads Active on an offer that sells nothing, and no diagnostic tells them why. Mirakl Connect keeps sending PriceStockUpsertEvent for it, so the connector sees traffic and no error.

The fix: treat the channel as the authority on its own items, and not your export log. Subscribe to the listing and product notifications the channel publishes, and reconcile the store's items on a schedule to catch what it never announced (step 2). OFFER_ACTIVE is not a terminal state (step 6).

What it looks like: the channel deactivates a live offer, and the connector reports OFFER_DOES_NOT_EXIST for every such case, because the offer is indeed no longer on the channel.

The failure: OFFER_DOES_NOT_EXIST asks Mirakl Connect for a new creation attempt. When the channel blocked the offer for a reason nothing has fixed, it rejects the new offer the same way, and the connector reports OFFER_DOES_NOT_EXIST again. The item cycles between the two, and the seller sees Synchronizing on an offer that will never go live.

The fix: choose the status from whether a new attempt could succeed. Report OFFER_DOES_NOT_EXIST when the offer is simply gone and a new creation would work. Report ACTION_REQUIRED with the channel's reason when the seller must act first, because it stops the attempts and shows the reason (step 3).

What it looks like: the connector reports once, right after the export response, and never revisits an item. It does not consume the channel's asynchronous results, or it consumes them and turns none of them into a report.

The failure: Mirakl Connect's view stays at the moment of the export. An offer the channel rejected after review stays OFFER_ACTIVE, a submission whose result never arrived stays pending, and the seller reads a status that was true once.

The fix: consume the asynchronous results with bounded retries and a terminal failed state (step 2), and report each item again as its outcome changes (step 6).

• Catalog flow: where this report sits in the catalog synchronization, and which event carries which stage.
• Create or update products: how to consume ProductUpsertEvent and create the product whose status you report here.
• Create and update offers: how to consume OfferUpsertEvent and create the offer whose status you report here.
• Sync price and stock: how to buffer and batch price and stock changes before the export.
• updateStoreCatalogItems: the operation that carries product_status, offer_status, and both diagnostics lists.
• Taxonomy: the attribute ids you declare, and the labels the seller reads for them.
• Concepts and glossary: the vocabulary for feedback, diagnostics, and store catalog items.