--- title: "upsertOrders - Upsert orders" method: POST path: "/v1/orders" tags: ["Orders"] --- # upsertOrders - Upsert orders `POST /v1/orders` ## Request - Base URL: `https://miraklconnect.com/api/channel-platform` - URL: `https://miraklconnect.com/api/channel-platform/v1/orders` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema)
Description
Use this API to synchronize orders with Mirakl Connect. - The operation is **not partially successful**: if any order in the payload is invalid, the entire request is rejected. - This API does not support PATCH operations. All fields must be sent with each upsert request to ensure the complete update of the order data. - Updates whose `channel_updated_at` timestamp is older than the value already stored in Connect are silently ignored (anti-replay guard).
Call Frequency
Recommended usage: 20 / sec
Maximum usage: 30 / sec
## Request body - UpsertOrdersRequest - `orders` OrderRequest[], required: List of orders to create or update. - `billing_info` BillingInfoRequest: Billing information for invoice and payment purposes. Optional. - `address` AddressRequest - `additional_info` string: Additional delivery instructions or notes. - `city` string, required: City. - `company` string: Company name, if applicable. - `country` string: Country name. - `country_iso_code` string: ISO 3166-1 alpha-3 country code (e.g. FRA, USA, DEU). - `first_name` string: Recipient's first name. - `last_name` string, required: Recipient's last name. - `phone` string: Phone number of the recipient. - `state` string: State or region. - `street` string: Street name and number. Strongly recommended for accurate delivery; may be omitted for block-based address systems (e.g. Japan). - `street_additional_info` string: Additional street information (apartment, floor, building, etc.). - `zip_code` string: Postal or ZIP code. - `channel_order_id` string, required: Identifier of the order on the channel. Order uniqueness is guaranteed by the combination of the channel (`origin.channel_id`), the store (`origin.channel_store_id`), the sub-channel (`sub_channel_code`) and this `channel_order_id`. - `channel_updated_at` string, date-time, required: Date and time of the last update on the channel. Connect uses this timestamp to handle updates versioning: an order is updated only if this value is greater or equal to the current stored value in Connect. This means that an update whose `channel_updated_at` is older than the currently stored value will be silently ignored. - `created_at` string, date-time, required: Date and time when the order was placed on the channel. - `custom_attributes` CustomAttributeRequest[]: Custom attributes - `id` string, required: Attribute's id - `type` string, required: The attribute's type Enum: `"STRING"`, `"NUMERIC"`, `"BOOLEAN"`, `"DATE"`, `"LIST"` - `fulfillment` FulfillmentRequest, required - `code` string: Identifier of the fulfillment partner. Only meaningful when `type` is `FULFILLED_BY_PARTNER`. Ignored for `FULFILLED_BY_SELLER`. - `type` string, required: Indicates who is responsible for physically fulfilling the order. Enum: `"FULFILLED_BY_SELLER"`, `"FULFILLED_BY_PARTNER"` - `has_incident` boolean: Indicates whether the order has an active incident or dispute. - `order_lines` OrderLineRequest[], required: Lines composing the order. Each line corresponds to one distinct product in a given quantity. - `adjustments` AdjustmentRequest[]: Post-order modifications on this line, such as partial cancellations or refunds. Each adjustment represents a discrete event that occurred after the order was placed. Adjustments are append-only: send all past adjustments on every upsert. - `channel_adjustment_id` string, required: Unique identifier of the adjustment on the channel. - `created_at` string, date-time, required: Date and time when the adjustment was created on the channel. - `price` Money, required - `amount` number, required: Monetary amount. Must be zero or positive. - `currency` string, required: ISO 4217 currency code (e.g. EUR, USD, GBP). - `quantity` integer, required: Number of units affected by this adjustment. For a `CANCELATION`, this is the number of units cancelled. For a `REFUND`, this is the number of units for which the refund applies. - `reason` string, required: Business reason for the adjustment. Enum: `"CUSTOMER_CANCELATION"`, `"OUT_OF_STOCK"`, `"RETURN"`, `"ITEM_NOT_RECEIVED"`, `"AGREEMENT"`, `"DEFECT"`, `"UNABLE_TO_DELIVER"`, `"CHANNEL_SPECIFIC"` - `shipping_price` Money, required - `amount` number, required: Monetary amount. Must be zero or positive. - `currency` string, required: ISO 4217 currency code (e.g. EUR, USD, GBP). - `shipping_taxes` TaxRequest[]: Taxes on the adjusted shipping amount. These amounts are **not** included in `shipping_price`. - `amount` Money, required - `amount` number, required: Monetary amount. Must be zero or positive. - `currency` string, required: ISO 4217 currency code (e.g. EUR, USD, GBP). - `channel_collectible` Money - `amount` number, required: Monetary amount. Must be zero or positive. - `currency` string, required: ISO 4217 currency code (e.g. EUR, USD, GBP). - `code` string, required: Identifier of the tax type, as defined by the channel (e.g. VAT, GST, HST). - `rate` number: Tax rate expressed as a decimal (e.g. `0.20` for 20%). - `seller_collectible` Money - `amount` number, required: Monetary amount. Must be zero or positive. - `currency` string, required: ISO 4217 currency code (e.g. EUR, USD, GBP). - `taxes` TaxRequest[]: Refunded or cancelled taxes. These amounts should **not** be included in `price`. - `amount` Money, required - `amount` number, required: Monetary amount. Must be zero or positive. - `currency` string, required: ISO 4217 currency code (e.g. EUR, USD, GBP). - `channel_collectible` Money - `amount` number, required: Monetary amount. Must be zero or positive. - `currency` string, required: ISO 4217 currency code (e.g. EUR, USD, GBP). - `code` string, required: Identifier of the tax type, as defined by the channel (e.g. VAT, GST, HST). - `rate` number: Tax rate expressed as a decimal (e.g. `0.20` for 20%). - `seller_collectible` Money - `amount` number, required: Monetary amount. Must be zero or positive. - `currency` string, required: ISO 4217 currency code (e.g. EUR, USD, GBP). - `type` string, required: Nature of the adjustment. `CANCELATION` means units were removed from the line (quantity reduction); connect will release the corresponding stock reservation. `REFUND` means a monetary compensation was issued without changing the ordered quantity. Enum: `"REFUND"`, `"CANCELATION"` - `can_cancel` boolean, required: Whether the order line is currently eligible for cancellation. - `can_refund` boolean, required: Whether the order line is currently eligible for refund. - `channel_order_line_id` string, required: Unique identifier of the order line on the channel. Must be unique across **all** orders of the channel, not just within the current order. - `created_at` string, date-time, required: Date and time when the order line was created on the channel. - `custom_attributes` CustomAttributeRequest[]: Custom attributes - `id` string, required: Attribute's id - `type` string, required: The attribute's type Enum: `"STRING"`, `"NUMERIC"`, `"BOOLEAN"`, `"DATE"`, `"LIST"` - `price` Money, required - `amount` number, required: Monetary amount. Must be zero or positive. - `currency` string, required: ISO 4217 currency code (e.g. EUR, USD, GBP). - `product` ProductRequest, required - `id` string, required: Unique identifier of the product. This must be the seller's product identifier (usually the SKU). - `thumbnail_url` string, uri: URL of a product image. - `title` string, required: Display name of the product as shown to the buyer. - `quantity` integer, required: Number of units ordered for this product. - `ship_from` object: Warehouse from which the marketplace requires this order line to be shipped when it manages order routing. Optional; omitted if not provided by the marketplace. - `warehouse` object: Warehouse from which the order line is required to be shipped. - `id` string: Identifier of the warehouse. - `shipping_taxes` TaxRequest[]: Taxes applied to the shipping price. These amounts are **not** included in `total_shipping_price`. - `amount` Money, required - `amount` number, required: Monetary amount. Must be zero or positive. - `currency` string, required: ISO 4217 currency code (e.g. EUR, USD, GBP). - `channel_collectible` Money - `amount` number, required: Monetary amount. Must be zero or positive. - `currency` string, required: ISO 4217 currency code (e.g. EUR, USD, GBP). - `code` string, required: Identifier of the tax type, as defined by the channel (e.g. VAT, GST, HST). - `rate` number: Tax rate expressed as a decimal (e.g. `0.20` for 20%). - `seller_collectible` Money - `amount` number, required: Monetary amount. Must be zero or positive. - `currency` string, required: ISO 4217 currency code (e.g. EUR, USD, GBP). - `status` string, required: Current lifecycle status of the order line. Lines within the same order can have different statuses (e.g. one line shipped while another is still awaiting shipment). See `order.status` for the meaning of each value. Enum: `"AWAITING_ACCEPTANCE"`, `"AWAITING_FRAUD_CHECK"`, `"AWAITING_PAYMENT"`, `"AWAITING_SHIPMENT"`, `"CHANNEL_SPECIFIC"`, `"CLOSED"`, `"DELIVERED"`, `"SHIPPED"` - `status_reason` string: Reason that explains why this order line reached its current status. See `order.status_reason` for the meaning of each value. Enum: `"ACCEPTANCE_TIMEOUT"`, `"AUTOMATICALLY_CLOSED"`, `"CANCELED"`, `"FRAUD_CHECK_FAILED"`, `"FRAUD_CHECK_TIMEOUT"`, `"PAYMENT_TIMEOUT"`, `"REFUNDED"`, `"REFUSED"`, `"REFUSED_PAYMENT"` - `taxes` TaxRequest[]: Taxes applied to the product price. These amounts should **not** be included in `price`. Each entry represents a distinct tax type (e.g. VAT, GST). - `amount` Money, required - `amount` number, required: Monetary amount. Must be zero or positive. - `currency` string, required: ISO 4217 currency code (e.g. EUR, USD, GBP). - `channel_collectible` Money - `amount` number, required: Monetary amount. Must be zero or positive. - `currency` string, required: ISO 4217 currency code (e.g. EUR, USD, GBP). - `code` string, required: Identifier of the tax type, as defined by the channel (e.g. VAT, GST, HST). - `rate` number: Tax rate expressed as a decimal (e.g. `0.20` for 20%). - `seller_collectible` Money - `amount` number, required: Monetary amount. Must be zero or positive. - `currency` string, required: ISO 4217 currency code (e.g. EUR, USD, GBP). - `total_shipping_price` Money, required - `amount` number, required: Monetary amount. Must be zero or positive. - `currency` string, required: ISO 4217 currency code (e.g. EUR, USD, GBP). - `updated_at` string, date-time, required: Date and time of the last update of this order line on the channel. - `shipping_info` ShippingInfoRequest, required: Shipping destination and logistics information for the order. - `address` AddressRequest - `additional_info` string: Additional delivery instructions or notes. - `city` string, required: City. - `company` string: Company name, if applicable. - `country` string: Country name. - `country_iso_code` string: ISO 3166-1 alpha-3 country code (e.g. FRA, USA, DEU). - `first_name` string: Recipient's first name. - `last_name` string, required: Recipient's last name. - `phone` string: Phone number of the recipient. - `state` string: State or region. - `street` string: Street name and number. Strongly recommended for accurate delivery; may be omitted for block-based address systems (e.g. Japan). - `street_additional_info` string: Additional street information (apartment, floor, building, etc.). - `zip_code` string: Postal or ZIP code. - `carrier` string: Name of the carrier handling the shipment, as defined on the channel. - `delivery_date` object: Estimated delivery window communicated to the buyer. - `earliest` string, date-time, required: Earliest expected delivery date. - `latest` string, date-time, required: Latest expected delivery date. - `email` string, email: Email address of the recipient. - `method` string: Shipping service level or method name (e.g. standard, express, next-day). - `pudo_id` string: Identifier of the pick-up/drop-off point (PUDO) when the delivery targets a relay point, locker, or store rather than a home address. - `shipping_deadline` string, date-time: Latest date and time by which the seller must ship the order. - `status` string, required: Current lifecycle status of the order. - `AWAITING_FRAUD_CHECK`: Order is pending fraud verification before being confirmed. - `AWAITING_ACCEPTANCE`: Order has been placed and is waiting for the seller to accept or refuse it. - `AWAITING_PAYMENT`: Order has been accepted but payment has not yet been confirmed. - `AWAITING_SHIPMENT`: Order is paid and accepted, waiting for the seller to ship. - `SHIPPED`: Order has been handed to a carrier. - `DELIVERED`: Order has been delivered to the buyer. - `CLOSED`: Order lifecycle is complete (delivered, cancelled, or refunded). - `CHANNEL_SPECIFIC`: The order has a status specific to the channel that does not map to any standard Connect status. Use `status_reason` to carry additional context. Enum: `"AWAITING_ACCEPTANCE"`, `"AWAITING_FRAUD_CHECK"`, `"AWAITING_PAYMENT"`, `"AWAITING_SHIPMENT"`, `"CHANNEL_SPECIFIC"`, `"CLOSED"`, `"DELIVERED"`, `"SHIPPED"` - `status_reason` string: Reason that explains why the order reached its current status. Typically used for terminal or exceptional statuses (e.g. `CLOSED`, `CHANNEL_SPECIFIC`). - `ACCEPTANCE_TIMEOUT`: Seller did not accept the order within the acceptance deadline. - `AUTOMATICALLY_CLOSED`: Order was automatically closed by the channel. - `CANCELED`: Order was cancelled. - `FRAUD_CHECK_FAILED`: Order failed fraud verification. - `FRAUD_CHECK_TIMEOUT`: Fraud check was not completed within the deadline. - `PAYMENT_TIMEOUT`: Payment was not received within the deadline. - `REFUNDED`: Order was fully refunded. - `REFUSED`: Order was refused by the seller. - `REFUSED_PAYMENT`: Payment was refused. Enum: `"ACCEPTANCE_TIMEOUT"`, `"AUTOMATICALLY_CLOSED"`, `"CANCELED"`, `"FRAUD_CHECK_FAILED"`, `"FRAUD_CHECK_TIMEOUT"`, `"PAYMENT_TIMEOUT"`, `"REFUNDED"`, `"REFUSED"`, `"REFUSED_PAYMENT"` - `sub_channel_code` string: Code of the sub-channel - `origin` OriginRequest, required - `channel_id` string, required: Unique identifier of the sales channel - `channel_store_id` string, required: Store identifier on the sales channel. ## Response `204` No Content ## Other responses - `400`: Bad Request - `404`: A critical resource was not found. This may occur if: - The channel or its technology is unknown to Connect - The store is unknown to Connect ## Changes - **2026-10-23** `29947cf052d3`: 1 info - added the new optional request property `orders/items/order_lines/items/ship_from` - **2026-09-03** `446d410e6601`: 2 info - the request property `orders/items/billing_info/address/street` became optional - the request property `orders/items/shipping_info/address/street` became optional [Operation history](https://skmtc.dev/mirakl/apis/mirakl-connect-channel-platform-apis/changes/v1/orders/post.md) --- [API](https://skmtc.dev/mirakl/apis/mirakl-connect-channel-platform-apis.md) - [All operations](https://skmtc.dev/mirakl/apis/mirakl-connect-channel-platform-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/mirakl/apis/mirakl-connect-channel-platform-apis/revisions/5fe2e95ce715?raw)