{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Handle order action events","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"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"handle-order-action-events","__idx":0},"children":["Handle order action events"]},{"$$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/orderactionevent"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OrderActionEvent"]}]}," for the order actions Mirakl Connect requests, which are to accept, ship, cancel, and refund an order, and to upload a document."," ","You perform each action on the sales channel, and you report its outcome so that Mirakl Connect knows the action is done."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"business-context","__idx":1},"children":["Business context"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some things happen to an order because a seller decided so inside Mirakl Connect, not because the channel changed."," ","To accept a new order, to book its shipment, to cancel a line, and to issue a refund all start in Connect."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Mirakl Connect turns each decision into an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OrderActionEvent"]}," and sends it to your connector to carry out on the channel."," ","Your connector is what makes the seller's decision real on the channel, and its report back is what tells Mirakl Connect that the decision took effect."]},{"$$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 an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OrderActionEvent"]}," whenever one arrives with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," on the order side: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCEPT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREATE_SHIPMENT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCEL"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUND"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UPLOAD_DOCUMENT"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/returns"},"children":["Returns"]}," covers the actions on the return side, which are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCEPT_RETURN"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UPDATE_RETURN_TRACKING_INFORMATION"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACKNOWLEDGE_RETURN_RECEPTION"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLOSE_RETURN"]},"."," ","Their mechanics are the same."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide is distinct from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/orders/sync-orders-into-connect"},"children":["Sync orders into Connect"]},"."," ","There, you report the state the channel produced."," ","Here, you perform an action Mirakl Connect requested, and then you report both its outcome and the resulting state."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":3},"children":["How it works"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","align":"center","diagramType":"mermaid","diagramSource":"sequenceDiagram\n box rgb(219,234,254) Mirakl\n participant MC as Mirakl Connect\n end\n box rgb(209,250,229) Middleware\n participant CN as Channel Connector\n end\n box rgb(254,240,199) Channel\n participant CH as Sales channel\n end\n\n MC--)CN: OrderActionEvent (type, data.action_id)\n CN->>CN: Deduplicate on id, persist action_id\n CN->>CH: Perform the action\n alt action succeeds\n CH-->>CN: done\n CN->>MC: PUT /v1/orders/actions/{action_id} (SUCCESS)\n CN->>MC: POST /v1/orders (resulting state)\n else action refused\n CH-->>CN: refused\n CN->>MC: PUT /v1/orders/actions/{action_id} (FAILED + ActionError)\n end\n","diagramHtml":"ChannelMiddlewareMiraklSales channelChannel ConnectorMirakl ConnectSales channelChannel ConnectorMirakl Connectalt[action succeeds][action refused]OrderActionEvent (type, data.action_id)Deduplicate on id, persist action_idPerform the actiondonePUT /v1/orders/actions/{action_id} (SUCCESS)POST /v1/orders (resulting state)refusedPUT /v1/orders/actions/{action_id} (FAILED + ActionError)","diagramHtmlDark":"ChannelMiddlewareMiraklSales channelChannel ConnectorMirakl ConnectSales channelChannel ConnectorMirakl Connectalt[action succeeds][action refused]OrderActionEvent (type, data.action_id)Deduplicate on id, persist action_idPerform the actiondonePUT /v1/orders/actions/{action_id} (SUCCESS)POST /v1/orders (resulting state)refusedPUT /v1/orders/actions/{action_id} (FAILED + ActionError)"},"children":["sequenceDiagram\n box rgb(219,234,254) Mirakl\n participant MC as Mirakl Connect\n end\n box rgb(209,250,229) Middleware\n participant CN as Channel Connector\n end\n box rgb(254,240,199) Channel\n participant CH as Sales channel\n end\n\n MC--)CN: OrderActionEvent (type, data.action_id)\n CN->>CN: Deduplicate on id, persist action_id\n CN->>CH: Perform the action\n alt action succeeds\n CH-->>CN: done\n CN->>MC: PUT /v1/orders/actions/{action_id} (SUCCESS)\n CN->>MC: POST /v1/orders (resulting state)\n else action refused\n CH-->>CN: refused\n CN->>MC: PUT /v1/orders/actions/{action_id} (FAILED + ActionError)\n end\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-by-step","__idx":4},"children":["Step by step"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-receive-and-deduplicate-the-event","__idx":5},"children":["1. Receive and deduplicate the event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every event arrives in the shared envelope, with an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", which is a ULID, a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["time"]},", a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]},", and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," body."," ","Deduplicate on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", so that a repeat delivery does nothing twice."," ","Persist the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.action_id"]},", because it is how you report the outcome, and it must survive a restart."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-dispatch-on-the-action-type","__idx":6},"children":["2. Dispatch on the action ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," names the action and selects the shape of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},"."," ","The set of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," values can grow, so plan for a value you do not know yet:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Map each action to the closest action on the channel, and keep that mapping as accurate as you can."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Report ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTION_NOT_SUPPORTED"]}," only when the channel offers no action for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Report an outcome for every action you receive, so that no action stays pending."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," of each order action carries the identifiers, which are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_store_id"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_order_id"]},", plus what the action needs."," ","It also carries the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sub_channel_code"]}," when the order belongs to a sub-channel (read ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/orders#naming-the-sub-channel-of-an-order"},"children":["Naming the sub-channel of an order"]},")."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"examples","__idx":7},"children":["Examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCEPT"]}," accepts or refuses the order's lines:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"type\": \"ACCEPT\",\n \"data\": {\n \"action_id\": \"1ba5fc4b-c4fd-4251-880b-3052e301bbd4\",\n \"channel_id\": \"0024\",\n \"channel_store_id\": \"2005\",\n \"channel_order_id\": \"0024_COMMERCIAL_ID-A\",\n \"order_lines\": [\n { \"channel_order_line_id\": \"0024_COMMERCIAL_ID-A-1\", \"accepted\": true }\n ]\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREATE_SHIPMENT"]}," ships the order, or a set of its lines, with a carrier."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier"]}," is optional, and it holds the display ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}," of the carrier, not the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_carrier_id"]}," you sent to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/rest/connect/openapi3/carriers/upsertcarriers"},"children":["upsertCarriers"]},"."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warehouse_id"]}," is required only when the channel needs it:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"type\": \"CREATE_SHIPMENT\",\n \"data\": {\n \"action_id\": \"2cb6fd5c-d5fe-4362-991c-4163f412cce5\",\n \"channel_id\": \"0024\",\n \"channel_store_id\": \"2005\",\n \"channel_order_id\": \"0024_COMMERCIAL_ID-A\",\n \"carrier\": \"DHL Express\",\n \"tracking_number\": \"1Z999AA1234567890\",\n \"tracking_url\": \"https://tracking.carrier.com/123456\",\n \"items\": [\n { \"channel_order_line_id\": \"0024_COMMERCIAL_ID-A-1\", \"id\": \"SELLER_ID_1\", \"quantity\": 2 }\n ]\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the channel requires a carrier and the event carries none, either send a default value the channel accepts, or report ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MISSING_CARRIER"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCEL"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUND"]}," carry the affected lines, in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelations"]}," and in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refunds"]},"."," ","Each line carries a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quantity"]},", a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]},", and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["price"]}," and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipping_price"]}," to cancel or refund, tax excluded, with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["taxes"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipping_taxes"]}," listed separately:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"type\": \"REFUND\",\n \"data\": {\n \"action_id\": \"3dc7fe6d-e60f-4473-aa2d-5274051523f6\",\n \"channel_id\": \"0024\",\n \"channel_store_id\": \"2005\",\n \"channel_order_id\": \"0024_COMMERCIAL_ID-A\",\n \"refunds\": [\n {\n \"channel_order_line_id\": \"0024_COMMERCIAL_ID-A-1\",\n \"product_id\": \"SELLER_ID_1\",\n \"quantity\": 1,\n \"reason\": \"DEFECT\",\n \"price\": { \"amount\": 24.99, \"currency\": \"EUR\" },\n \"shipping_price\": { \"amount\": 0, \"currency\": \"EUR\" }\n }\n ]\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UPLOAD_DOCUMENT"]}," provides a document for you to place ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["on the channel"]},"."," ","Mirakl Connect gives a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document_name"]},", a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document_type"]},", which is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURN_LABEL"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CUSTOMER_INVOICE"]},", and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document_download_url"]},", which is a presigned link that expires."," ","When the document belongs to a return, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document_entity"]}," names that return, with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: RETURN"]}," and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_return_id"]}," as its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"type\": \"UPLOAD_DOCUMENT\",\n \"data\": {\n \"action_id\": \"4ed8af7e-f710-4584-bb3e-6385162634a7\",\n \"channel_id\": \"0024\",\n \"channel_store_id\": \"2005\",\n \"channel_order_id\": \"0024_COMMERCIAL_ID-A\",\n \"document_name\": \"return_label_RET-0024-001.pdf\",\n \"document_type\": \"RETURN_LABEL\",\n \"document_download_url\": \"https://storage.example.com/documents/4f690afa-6543-4f4b-a89f-81934e65ddd5?expires=1787059200&signature=247a2aa45f169edf4d187d54e7cc46e4\",\n \"document_entity\": { \"type\": \"RETURN\", \"id\": \"RET-0024-001\" }\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Download the document from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document_download_url"]}," before the link expires, then upload it to the channel."," ","A document that belongs to the order itself, and not to a return, carries no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document_entity"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-perform-the-action-on-the-channel-idempotently","__idx":8},"children":["3. Perform the action on the channel, idempotently"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Carry the action out through the channel's own API."," ","Guard it so that a repeat is safe: if Mirakl Connect delivers the same event twice, the channel operation must not happen twice, so no double shipment and no double refund."," ","Tie the channel operation to the stored ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_id"]},", so that you can tell an action you already performed from a new one."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-report-the-outcome","__idx":9},"children":["4. Report the outcome"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Report the final result ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["once"]},", when the action is complete, with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/rest/connect/openapi3/orders/updateactionstatus"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /v1/orders/actions/{action_id}"]}]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On success:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{ \"status\": \"SUCCESS\" }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On failure, send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}," with one or more ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ActionError"]}," entries."," ","Map the channel's refusal to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," that matches, and put the specifics in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]},"."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," is a bounded set:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_INPUT"]},": the action carries data the channel refuses."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DATA_NOT_FOUND"]},": the order, the line, or the return the action names does not exist on the channel."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNEXPECTED"]},": the channel failed for a reason your connector cannot classify."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNAVAILABLE"]},": the channel was unreachable."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOO_MANY_REQUEST"]},": the channel throttled the call."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTION_NOT_SUPPORTED"]},": the channel offers no action for this ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ORDER_IN_WRONG_STATE"]},": the order's state on the channel does not allow the action."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURN_IN_WRONG_STATE"]},": the return's state on the channel does not allow the action."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CARRIER_NOT_SUPPORTED"]},": the channel does not accept the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier"]}," of the action."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MISSING_CARRIER"]},": the channel requires a carrier, and the action carries none."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WAREHOUSE_ID_NOT_FOUND"]},": the channel does not know the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warehouse_id"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WAREHOUSE_ID_REQUIRED"]},": the channel requires a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warehouse_id"]},", and the action carries none."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OTHER"]},": none of the codes above fits."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"status\": \"FAILED\",\n \"errors\": [\n { \"code\": \"ORDER_IN_WRONG_STATE\", \"message\": \"Cannot ship: order is already cancelled\" }\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Three responses matter:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204"]}," confirms the report."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTION_ALREADY_FINAL"]}," means that you already reported the action."," ","Treat it as a benign confirmation, not as an error to retry around."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}," means that the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_id"]}," is unknown, because it is incorrect, or because the order it belongs to was deleted."," ","An action never expires."," ","Mirakl Connect deletes it with its order, when the seller unlinks the store or when the order's retention period ends."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"5-re-sync-the-resulting-state","__idx":10},"children":["5. Re-sync the resulting state"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reporting the outcome of an action does ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," update the status of the order."," ","After an action changes the order's state, push the order's new state with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/orders/sync-orders-into-connect"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upsertOrders"]}]},"."," ","The action is not fully handled until you have reported both the outcome and the new state."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-mistakes","__idx":11},"children":["Common mistakes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["To never report ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},"."]}," ","An action with no reported outcome hangs, and Mirakl Connect waits forever."," ","Report the result of every action, whether it succeeded or failed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["To lose or reuse the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_id"]},"."]}," ","You must report the outcome against the exact ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_id"]}," from the event."," ","Persist it on receipt."," ","Without it, you cannot close the action, and a duplicate event can drive the channel operation twice."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["To acknowledge the delivery instead of the action."]}," ","To acknowledge the message on the queue confirms receipt only."," ","It does not report the outcome."," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/rest/connect/openapi3/orders/updateactionstatus"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updateActionStatus"]}]}," does that, sent once the action is really done."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["To report the outcome but not re-sync."]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updateActionStatus"]}," does not carry the order's new status."," ","Follow an action that changes the state with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upsertOrders"]},", or the copy of the order in Connect drifts from the channel."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["To collapse every failure into ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OTHER"]},"."]}," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," is what Mirakl Connect and the seller act on."," ","Map the failure to the specific ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ActionError"]},", such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ORDER_IN_WRONG_STATE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MISSING_CARRIER"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WAREHOUSE_ID_REQUIRED"]},", and reserve ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OTHER"]}," for the failures that genuinely fit none of them."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related","__idx":12},"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/orders/sync-orders-into-connect"},"children":["Sync orders into Connect"]},": how to report the order state that an action produces."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/returns"},"children":["Returns"]},": the actions on the return side, handled the same way."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/orders"},"children":["Orders"]},": the order actions in context."]}]}]},"headings":[{"value":"Handle order action events","id":"handle-order-action-events","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":"Step by step","id":"step-by-step","depth":2},{"value":"1. Receive and deduplicate the event","id":"1-receive-and-deduplicate-the-event","depth":3},{"value":"2. Dispatch on the action type","id":"2-dispatch-on-the-action-type","depth":3},{"value":"Examples","id":"examples","depth":4},{"value":"3. Perform the action on the channel, idempotently","id":"3-perform-the-action-on-the-channel-idempotently","depth":3},{"value":"4. Report the outcome","id":"4-report-the-outcome","depth":3},{"value":"5. Re-sync the resulting state","id":"5-re-sync-the-resulting-state","depth":3},{"value":"Common mistakes","id":"common-mistakes","depth":2},{"value":"Related","id":"related","depth":2}],"frontmatter":{"seo":{"title":"Handle order action events"}},"lastModified":"2026-11-06T15:01:50.980Z","pagePropGetterError":{"message":"","name":""}},"slug":"/content/product/connect-channel-platform/developer-guide/orders/handle-order-action-events","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}