{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Sync orders into Connect","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":"sync-orders-into-connect","__idx":0},"children":["Sync orders into Connect"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep the copy of every order in Mirakl Connect current."," ","Observe an order on the sales channel, and push its complete state in with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/rest/connect/openapi3/orders/upsertorders"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upsertOrders"]}]},"."," ","Mirakl Connect, the seller, and the return and action flows then all work from an accurate picture."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"business-context","__idx":1},"children":["Business context"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An order lives on the sales channel, but the seller manages it from inside Mirakl Connect, which drives the fulfillment actions, the returns, and the refunds from there too."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The connector is the middleware: it watches the channel and reports each order, and every change to it."," ","Everything downstream depends on that report being accurate and current, from the status the seller sees to the actions Mirakl Connect is allowed to request."]},{"$$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":["Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/rest/connect/openapi3/orders/upsertorders"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upsertOrders"]}]}," whenever an order is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["created or changes on the channel"]},": a new order, a status change, a new adjustment, or updated shipping information."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Never use it to report the outcome of an action Mirakl Connect requested."," ","An action arrives as an ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/webhooks/webhook/webhooks/orderactionevent"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OrderActionEvent"]}]},", and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/rest/connect/openapi3/orders/updateactionstatus"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updateActionStatus"]}]}," reports its outcome."," ","Once the action is done, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upsertOrders"]}," to push the state it produced."]},{"$$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 CH->>CN: Order created or changed\n CN->>CN: Build the complete order object\n CN->>MC: POST /v1/orders (origin + orders[])\n alt all orders valid\n MC-->>CN: 204 No Content\n else any order invalid\n MC-->>CN: 400 (whole request rejected)\n end\n","diagramHtml":"","diagramHtmlDark":""},"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 CH->>CN: Order created or changed\n CN->>CN: Build the complete order object\n CN->>MC: POST /v1/orders (origin + orders[])\n alt all orders valid\n MC-->>CN: 204 No Content\n else any order invalid\n MC-->>CN: 400 (whole request rejected)\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-detect-the-change-on-the-channel","__idx":5},"children":["1. Detect the change on the channel"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["How your connector detects a change depends on the channel, and Mirakl Connect prescribes nothing here."," ","A channel exposes one of two mechanisms, and some channels expose both:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The channel notifies your connector"]},", asynchronously, when an order is created or changes."," ","Your connector reacts to each notification it receives."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Your connector polls the channel's API"]},", synchronously, on a schedule it owns, or it reads a feed the channel publishes."," ","Keep a cursor, such as the date of the last change you read, so that each poll picks up only what moved since."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You report the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["current"]}," state of the order, not the individual change, so all you need is the order as it now stands."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-build-the-complete-order-object","__idx":6},"children":["2. Build the complete order object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upsertOrders"]}," does not support PATCH, so every call restates the order in full."," ","An order carries its origin, its lines, and a lifecycle status."," ","Each line carries its price, tax excluded, its taxes, its product, its quantity, its status, and its full append-only list of adjustments."," ","Set the line's product ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," to the seller's own product reference on the channel."," ","The seller reads that value to identify what was ordered."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add the order's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sub_channel_code"]}," when the store carries sub-channels."," ","Mirakl Connect needs it to tell apart two orders that share a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_order_id"]},", and it rejects a creation with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orders[i].channel_order_id"]}," once another order already holds a code under that id."," ","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":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"origin\": {\n \"channel_id\": \"0024\",\n \"channel_store_id\": \"2005\"\n },\n \"orders\": [\n {\n \"channel_order_id\": \"0024_COMMERCIAL_ID-A\",\n \"created_at\": \"2026-07-10T09:12:00Z\",\n \"channel_updated_at\": \"2026-07-10T14:03:22Z\",\n \"status\": \"AWAITING_SHIPMENT\",\n \"fulfillment\": { \"type\": \"FULFILLED_BY_SELLER\" },\n \"shipping_info\": {\n \"email\": \"buyer@example.com\",\n \"carrier\": \"DHL Express\",\n \"method\": \"standard\",\n \"address\": {\n \"first_name\": \"Alex\",\n \"last_name\": \"Martin\",\n \"street\": \"12 rue des Fleurs\",\n \"city\": \"Lyon\",\n \"zip_code\": \"69001\",\n \"country_iso_code\": \"FRA\"\n }\n },\n \"order_lines\": [\n {\n \"channel_order_line_id\": \"0024_COMMERCIAL_ID-A-1\",\n \"created_at\": \"2026-07-10T09:12:00Z\",\n \"updated_at\": \"2026-07-10T09:12:00Z\",\n \"quantity\": 2,\n \"can_cancel\": true,\n \"can_refund\": true,\n \"price\": { \"amount\": 49.98, \"currency\": \"EUR\" },\n \"total_shipping_price\": { \"amount\": 4.90, \"currency\": \"EUR\" },\n \"product\": { \"id\": \"SELLER_ID_1\", \"title\": \"Wireless mouse\" },\n \"taxes\": [\n { \"code\": \"VAT\", \"rate\": 0.20, \"amount\": { \"amount\": 9.99, \"currency\": \"EUR\" } }\n ],\n \"status\": \"AWAITING_SHIPMENT\",\n \"adjustments\": []\n }\n ]\n }\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-stamp-channel_updated_at-from-the-channel","__idx":7},"children":["3. Stamp ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_updated_at"]}," from the channel"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_updated_at"]}," to the last time the order was modified ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["on the channel"]},"."," ","Connect uses it to version the updates: it silently ignores an upsert whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_updated_at"]}," is older than the value it already stores."," ","This is what keeps a delayed or replayed message from overwriting a newer state."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-send-the-request-and-read-the-outcome","__idx":8},"children":["4. Send the request and read the outcome"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/orders"]}," is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["synchronous"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["all or nothing"]},":"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Response"},"children":["Response"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What to do"},"children":["What to do"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Connect accepted every order in the request."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Nothing."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["At least one order is invalid, so ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Connect rejects the whole request"]}," and applies no order."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fix the invalid order, and send the batch again."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Connect does not know the channel or the store in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["origin"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check the identifiers. Usually, the store was not onboarded or synchronized first."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because one invalid order rejects the entire batch, validate before you send."," ","Keep a batch small enough to isolate a bad order quickly, and send up to 100 orders in each request."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"5-preserve-the-order-and-the-adjustment-history","__idx":9},"children":["5. Preserve the order and the adjustment history"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two habits keep the state correct over many updates:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Order the updates for each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_order_id"]},", and let the newest win."]}," ","Key that ordering on the pair of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_order_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sub_channel_code"]}," when the store carries sub-channels."," ","Fold each observed change into the order's current state, and stamp it with the time of the channel."," ","If two updates race, keep the one stamped later."," ","The anti-replay guard of Connect backs this up, but to order your own writes avoids work you send and Connect drops."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Adjustments are append-only."]}," ","Each order line carries its complete history of past adjustments on every upsert."," ","To send only the newest adjustment erases the rest."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"complete-example","__idx":10},"children":["Complete example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An order is placed with one line that awaits its shipment, as in step 2 above."," ","The seller later ships it, so the order and the line move to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SHIPPED"]}," on the channel."," ","The connector rebuilds the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["whole"]}," order, with the same lines and adjustments, the new status, and a newer ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_updated_at"]},", and it upserts the order again:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"origin\": { \"channel_id\": \"0024\", \"channel_store_id\": \"2005\" },\n \"orders\": [\n {\n \"channel_order_id\": \"0024_COMMERCIAL_ID-A\",\n \"created_at\": \"2026-07-10T09:12:00Z\",\n \"channel_updated_at\": \"2026-07-11T08:40:10Z\",\n \"status\": \"SHIPPED\",\n \"fulfillment\": { \"type\": \"FULFILLED_BY_SELLER\" },\n \"shipping_info\": {\n \"carrier\": \"DHL Express\",\n \"method\": \"standard\",\n \"address\": {\n \"first_name\": \"Alex\", \"last_name\": \"Martin\",\n \"street\": \"12 rue des Fleurs\", \"city\": \"Lyon\",\n \"zip_code\": \"69001\", \"country_iso_code\": \"FRA\"\n }\n },\n \"order_lines\": [\n {\n \"channel_order_line_id\": \"0024_COMMERCIAL_ID-A-1\",\n \"created_at\": \"2026-07-10T09:12:00Z\",\n \"updated_at\": \"2026-07-11T08:40:10Z\",\n \"quantity\": 2,\n \"can_cancel\": false,\n \"can_refund\": true,\n \"price\": { \"amount\": 49.98, \"currency\": \"EUR\" },\n \"total_shipping_price\": { \"amount\": 4.90, \"currency\": \"EUR\" },\n \"product\": { \"id\": \"SELLER_ID_1\", \"title\": \"Wireless mouse\" },\n \"status\": \"SHIPPED\",\n \"adjustments\": []\n }\n ]\n }\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Connect accepts it with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204"]},", because ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_updated_at"]}," moved forward."]},{"$$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 send only what changed."]}," ","There is no merge."," ","A line or an adjustment you leave out of the payload is deleted, not preserved."," ","Always send the complete order."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["To send a delta of the adjustments."]}," ","Send the full adjustment history of the line every time."," ","The list is append-only, and a partial list rewrites it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["To omit or reuse ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_updated_at"]},"."]}," ","Without a timestamp that moves forward, Connect cannot tell a newer state from a replay."," ","A stale upsert can then be dropped, and if you reuse an old value, Connect silently ignores it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["To read a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204"]}," as \"applied on the channel\"."]}," ","A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204"]}," means that Connect accepted the order into its own copy."," ","It says nothing about the channel, because the channel is the source you report from, not the target."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["To send the channel's own product identifier on a line."]}," ","The seller cannot tell which of their items was ordered."," ","Send the seller's product reference on the channel, which is the SKU is most cases."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["To upsert an order for an unknown store or channel."]}," ","A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}," means that Connect does not know the store or the channel."," ","Synchronize the onboarding first, then retry."]}]},{"$$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/handle-order-action-events"},"children":["Handle order action events"]},": how to perform the accept, ship, cancel, and refund actions Mirakl Connect requests, and report the outcome with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updateActionStatus"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/returns"},"children":["Returns"]},": how to synchronize the returns with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upsertReturns"]}," and record the refunds."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/orders"},"children":["Orders"]},": the order process between Mirakl Connect and the channel, and the events and APIs the connector implements."]}]}]},"headings":[{"value":"Sync orders into Connect","id":"sync-orders-into-connect","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. Detect the change on the channel","id":"1-detect-the-change-on-the-channel","depth":3},{"value":"2. Build the complete order object","id":"2-build-the-complete-order-object","depth":3},{"value":"3. Stamp channel_updated_at from the channel","id":"3-stamp-channel_updated_at-from-the-channel","depth":3},{"value":"4. Send the request and read the outcome","id":"4-send-the-request-and-read-the-outcome","depth":3},{"value":"5. Preserve the order and the adjustment history","id":"5-preserve-the-order-and-the-adjustment-history","depth":3},{"value":"Complete example","id":"complete-example","depth":2},{"value":"Common mistakes","id":"common-mistakes","depth":2},{"value":"Related","id":"related","depth":2}],"frontmatter":{"seo":{"title":"Sync orders into Connect"}},"lastModified":"2026-11-06T15:01:50.981Z","pagePropGetterError":{"message":"","name":""}},"slug":"/content/product/connect-channel-platform/developer-guide/orders/sync-orders-into-connect","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}