# upsertOrders - Upsert orders

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).

Endpoint: POST /v1/orders
Security: Bearer

## Request fields (application/json):

  - `orders` (array, required)
    List of orders to create or update.

  - `orders.billing_info` (object)
    Billing information for invoice and payment purposes. Optional.

  - `orders.billing_info.address` (object)
    Billing address used for invoice and payment purposes.

  - `orders.billing_info.address.additional_info` (string)
    Additional delivery instructions or notes.

  - `orders.billing_info.address.city` (string, required)
    City.

  - `orders.billing_info.address.company` (string)
    Company name, if applicable.

  - `orders.billing_info.address.country` (string)
    Country name.

  - `orders.billing_info.address.country_iso_code` (string)
    ISO 3166-1 alpha-3 country code (e.g. FRA, USA, DEU).

  - `orders.billing_info.address.first_name` (string)
    Recipient's first name.

  - `orders.billing_info.address.last_name` (string, required)
    Recipient's last name.

  - `orders.billing_info.address.phone` (string)
    Phone number of the recipient.

  - `orders.billing_info.address.state` (string)
    State or region.

  - `orders.billing_info.address.street` (string, required)
    Street name and number.

  - `orders.billing_info.address.street_additional_info` (string)
    Additional street information (apartment, floor, building, etc.).

  - `orders.billing_info.address.zip_code` (string)
    Postal or ZIP code.

  - `orders.channel_order_id` (string, required)
    Unique identifier of the order on the channel. Must be unique across all orders of the channel. Combined with origin.channel_id, it forms the global Connect order identifier.

  - `orders.channel_updated_at` (string, 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.

  - `orders.created_at` (string, required)
    Date and time when the order was placed on the channel.

  - `orders.custom_attributes` (array)
    Custom attributes

  - `orders.custom_attributes.id` (string, required)
    Attribute's id

  - `orders.custom_attributes.type` (string, required)
    The attribute's type

Enum: "STRING", "NUMERIC", "BOOLEAN", "DATE", "LIST"

  - `orders.fulfillment` (object, required)

  - `orders.fulfillment.code` (string)
    Identifier of the fulfillment partner. Only meaningful when type is FULFILLED_BY_PARTNER. Ignored for FULFILLED_BY_SELLER.

  - `orders.fulfillment.type` (string, required)
    Indicates who is responsible for physically fulfilling the order.


Enum: "FULFILLED_BY_SELLER", "FULFILLED_BY_PARTNER"

  - `orders.has_incident` (boolean)
    Indicates whether the order has an active incident or dispute.

  - `orders.order_lines` (array, required)
    Lines composing the order. Each line corresponds to one distinct product in a given quantity.

  - `orders.order_lines.adjustments` (array)
    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.

  - `orders.order_lines.adjustments.channel_adjustment_id` (string, required)
    Unique identifier of the adjustment on the channel.

  - `orders.order_lines.adjustments.created_at` (string, required)
    Date and time when the adjustment was created on the channel.

  - `orders.order_lines.adjustments.price` (object, required)
    Refunded or cancelled amount, tax excluded. Taxes on the adjusted product amount are listed separately in taxes.

  - `orders.order_lines.adjustments.price.amount` (number, required)
    Monetary amount. Must be zero or positive.

  - `orders.order_lines.adjustments.price.currency` (string, required)
    ISO 4217 currency code (e.g. EUR, USD, GBP).

  - `orders.order_lines.adjustments.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.

  - `orders.order_lines.adjustments.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"

  - `orders.order_lines.adjustments.shipping_price` (object, required)
    Refunded or cancelled shipping amount, tax excluded. Shipping taxes are listed separately in shipping_taxes.

  - `orders.order_lines.adjustments.shipping_price.amount` (number, required)
    Monetary amount. Must be zero or positive.

  - `orders.order_lines.adjustments.shipping_price.currency` (string, required)
    ISO 4217 currency code (e.g. EUR, USD, GBP).

  - `orders.order_lines.adjustments.shipping_taxes` (array)
    Taxes on the adjusted shipping amount. These amounts are not included in shipping_price.

  - `orders.order_lines.adjustments.shipping_taxes.amount` (object, required)
    Total amount for this tax entry.

  - `orders.order_lines.adjustments.shipping_taxes.amount.amount` (number, required)
    Monetary amount. Must be zero or positive.

  - `orders.order_lines.adjustments.shipping_taxes.amount.currency` (string, required)
    ISO 4217 currency code (e.g. EUR, USD, GBP).

  - `orders.order_lines.adjustments.shipping_taxes.channel_collectible` (object)
    Amount collected by the operator (marketplace facilitator).

  - `orders.order_lines.adjustments.shipping_taxes.channel_collectible.amount` (number, required)
    Monetary amount. Must be zero or positive.

  - `orders.order_lines.adjustments.shipping_taxes.channel_collectible.currency` (string, required)
    ISO 4217 currency code (e.g. EUR, USD, GBP).

  - `orders.order_lines.adjustments.shipping_taxes.code` (string, required)
    Identifier of the tax type, as defined by the channel (e.g. VAT, GST, HST).

  - `orders.order_lines.adjustments.shipping_taxes.rate` (number)
    Tax rate expressed as a decimal (e.g. 0.20 for 20%).

  - `orders.order_lines.adjustments.shipping_taxes.seller_collectible` (object)
    Amount the seller must collect and declare to tax authorities.

  - `orders.order_lines.adjustments.shipping_taxes.seller_collectible.amount` (number, required)
    Monetary amount. Must be zero or positive.

  - `orders.order_lines.adjustments.shipping_taxes.seller_collectible.currency` (string, required)
    ISO 4217 currency code (e.g. EUR, USD, GBP).

  - `orders.order_lines.adjustments.taxes` (array)
    Refunded or cancelled taxes. These amounts should not be included in price.

  - `orders.order_lines.adjustments.taxes.amount` (object, required)
    Total amount for this tax entry.

  - `orders.order_lines.adjustments.taxes.amount.amount` (number, required)
    Monetary amount. Must be zero or positive.

  - `orders.order_lines.adjustments.taxes.amount.currency` (string, required)
    ISO 4217 currency code (e.g. EUR, USD, GBP).

  - `orders.order_lines.adjustments.taxes.channel_collectible` (object)
    Amount collected by the operator (marketplace facilitator).

  - `orders.order_lines.adjustments.taxes.channel_collectible.amount` (number, required)
    Monetary amount. Must be zero or positive.

  - `orders.order_lines.adjustments.taxes.channel_collectible.currency` (string, required)
    ISO 4217 currency code (e.g. EUR, USD, GBP).

  - `orders.order_lines.adjustments.taxes.code` (string, required)
    Identifier of the tax type, as defined by the channel (e.g. VAT, GST, HST).

  - `orders.order_lines.adjustments.taxes.rate` (number)
    Tax rate expressed as a decimal (e.g. 0.20 for 20%).

  - `orders.order_lines.adjustments.taxes.seller_collectible` (object)
    Amount the seller must collect and declare to tax authorities.

  - `orders.order_lines.adjustments.taxes.seller_collectible.amount` (number, required)
    Monetary amount. Must be zero or positive.

  - `orders.order_lines.adjustments.taxes.seller_collectible.currency` (string, required)
    ISO 4217 currency code (e.g. EUR, USD, GBP).

  - `orders.order_lines.adjustments.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"

  - `orders.order_lines.can_cancel` (boolean, required)
    Whether the order line is currently eligible for cancellation.

  - `orders.order_lines.can_refund` (boolean, required)
    Whether the order line is currently eligible for refund.

  - `orders.order_lines.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.

  - `orders.order_lines.created_at` (string, required)
    Date and time when the order line was created on the channel.

  - `orders.order_lines.custom_attributes` (array)
    Custom attributes

  - `orders.order_lines.custom_attributes.id` (string, required)
    Attribute's id

  - `orders.order_lines.custom_attributes.type` (string, required)
    The attribute's type

Enum: "STRING", "NUMERIC", "BOOLEAN", "DATE", "LIST"

  - `orders.order_lines.price` (object, required)
    Total price of the order line, tax excluded. This is the price for the entire order line, i.e. unit price × quantity, not the unit price. Taxes are listed separately in the taxes array and should not be included in this amount.

  - `orders.order_lines.price.amount` (number, required)
    Monetary amount. Must be zero or positive.

  - `orders.order_lines.price.currency` (string, required)
    ISO 4217 currency code (e.g. EUR, USD, GBP).

  - `orders.order_lines.product` (object, required)

  - `orders.order_lines.product.id` (string, required)
    Unique identifier of the product on the channel.

  - `orders.order_lines.product.thumbnail_url` (string)
    URL of a product image.

  - `orders.order_lines.product.title` (string, required)
    Display name of the product as shown to the buyer.

  - `orders.order_lines.quantity` (integer, required)
    Number of units ordered for this product.

  - `orders.order_lines.shipping_taxes` (array)
    Taxes applied to the shipping price. These amounts are not included in total_shipping_price.

  - `orders.order_lines.shipping_taxes.amount` (object, required)
    Total amount for this tax entry.

  - `orders.order_lines.shipping_taxes.amount.amount` (number, required)
    Monetary amount. Must be zero or positive.

  - `orders.order_lines.shipping_taxes.amount.currency` (string, required)
    ISO 4217 currency code (e.g. EUR, USD, GBP).

  - `orders.order_lines.shipping_taxes.channel_collectible` (object)
    Amount collected by the operator (marketplace facilitator).

  - `orders.order_lines.shipping_taxes.channel_collectible.amount` (number, required)
    Monetary amount. Must be zero or positive.

  - `orders.order_lines.shipping_taxes.channel_collectible.currency` (string, required)
    ISO 4217 currency code (e.g. EUR, USD, GBP).

  - `orders.order_lines.shipping_taxes.code` (string, required)
    Identifier of the tax type, as defined by the channel (e.g. VAT, GST, HST).

  - `orders.order_lines.shipping_taxes.rate` (number)
    Tax rate expressed as a decimal (e.g. 0.20 for 20%).

  - `orders.order_lines.shipping_taxes.seller_collectible` (object)
    Amount the seller must collect and declare to tax authorities.

  - `orders.order_lines.shipping_taxes.seller_collectible.amount` (number, required)
    Monetary amount. Must be zero or positive.

  - `orders.order_lines.shipping_taxes.seller_collectible.currency` (string, required)
    ISO 4217 currency code (e.g. EUR, USD, GBP).

  - `orders.order_lines.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"

  - `orders.order_lines.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"

  - `orders.order_lines.taxes` (array)
    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).

  - `orders.order_lines.taxes.amount` (object, required)
    Total amount for this tax entry.

  - `orders.order_lines.taxes.amount.amount` (number, required)
    Monetary amount. Must be zero or positive.

  - `orders.order_lines.taxes.amount.currency` (string, required)
    ISO 4217 currency code (e.g. EUR, USD, GBP).

  - `orders.order_lines.taxes.channel_collectible` (object)
    Amount collected by the operator (marketplace facilitator).

  - `orders.order_lines.taxes.channel_collectible.amount` (number, required)
    Monetary amount. Must be zero or positive.

  - `orders.order_lines.taxes.channel_collectible.currency` (string, required)
    ISO 4217 currency code (e.g. EUR, USD, GBP).

  - `orders.order_lines.taxes.code` (string, required)
    Identifier of the tax type, as defined by the channel (e.g. VAT, GST, HST).

  - `orders.order_lines.taxes.rate` (number)
    Tax rate expressed as a decimal (e.g. 0.20 for 20%).

  - `orders.order_lines.taxes.seller_collectible` (object)
    Amount the seller must collect and declare to tax authorities.

  - `orders.order_lines.taxes.seller_collectible.amount` (number, required)
    Monetary amount. Must be zero or positive.

  - `orders.order_lines.taxes.seller_collectible.currency` (string, required)
    ISO 4217 currency code (e.g. EUR, USD, GBP).

  - `orders.order_lines.total_shipping_price` (object, required)
    Total shipping price for this order line, tax excluded. This is the total amount (not per-unit) for the shipping of this line. Shipping taxes are listed separately in shipping_taxes.

  - `orders.order_lines.total_shipping_price.amount` (number, required)
    Monetary amount. Must be zero or positive.

  - `orders.order_lines.total_shipping_price.currency` (string, required)
    ISO 4217 currency code (e.g. EUR, USD, GBP).

  - `orders.order_lines.updated_at` (string, required)
    Date and time of the last update of this order line on the channel.

  - `orders.shipping_info` (object, required)
    Shipping destination and logistics information for the order.

  - `orders.shipping_info.address` (object)
    Delivery address of the recipient.

  - `orders.shipping_info.address.additional_info` (string)
    Additional delivery instructions or notes.

  - `orders.shipping_info.address.city` (string, required)
    City.

  - `orders.shipping_info.address.company` (string)
    Company name, if applicable.

  - `orders.shipping_info.address.country` (string)
    Country name.

  - `orders.shipping_info.address.country_iso_code` (string)
    ISO 3166-1 alpha-3 country code (e.g. FRA, USA, DEU).

  - `orders.shipping_info.address.first_name` (string)
    Recipient's first name.

  - `orders.shipping_info.address.last_name` (string, required)
    Recipient's last name.

  - `orders.shipping_info.address.phone` (string)
    Phone number of the recipient.

  - `orders.shipping_info.address.state` (string)
    State or region.

  - `orders.shipping_info.address.street` (string, required)
    Street name and number.

  - `orders.shipping_info.address.street_additional_info` (string)
    Additional street information (apartment, floor, building, etc.).

  - `orders.shipping_info.address.zip_code` (string)
    Postal or ZIP code.

  - `orders.shipping_info.carrier` (string)
    Name of the carrier handling the shipment, as defined on the channel.

  - `orders.shipping_info.delivery_date` (object)
    Estimated delivery window communicated to the buyer.

  - `orders.shipping_info.delivery_date.earliest` (string, required)
    Earliest expected delivery date.

  - `orders.shipping_info.delivery_date.latest` (string, required)
    Latest expected delivery date.

  - `orders.shipping_info.email` (string)
    Email address of the recipient.

  - `orders.shipping_info.method` (string)
    Shipping service level or method name (e.g. standard, express, next-day).

  - `orders.shipping_info.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.

  - `orders.shipping_info.shipping_deadline` (string)
    Latest date and time by which the seller must ship the order.

  - `orders.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"

  - `orders.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"

  - `origin` (object, required)

  - `origin.channel_id` (string, required)
    Unique identifier of the sales channel

  - `origin.channel_store_id` (string, required)
    Store identifier on the sales channel.

## Response 400 fields (application/json):

  - `code` (string, required)
    Error code (immutable)

  - `errors` (array)

  - `errors.extensions` (object)
    Free map where you find additional context data to better describe the error

  - `errors.field` (string)
    JsonPath to the field where the error occurred

  - `errors.message` (string, required)
    Literal string error item description (Please do not base your error handling on this field since it is subject to change)

  - `extensions` (object)
    Free map where you find additional context data to better describe the error

  - `message` (string, required)
    Literal string error description (Please do not base your error handling on this field since it is subject to change)

## Response 404 fields (application/json):

  - `code` (string, required)
    Error code (immutable)

  - `errors` (array)

  - `errors.extensions` (object)
    Free map where you find additional context data to better describe the error

  - `errors.field` (string)
    JsonPath to the field where the error occurred

  - `errors.message` (string, required)
    Literal string error item description (Please do not base your error handling on this field since it is subject to change)

  - `extensions` (object)
    Free map where you find additional context data to better describe the error

  - `message` (string, required)
    Literal string error description (Please do not base your error handling on this field since it is subject to change)


## Response 204 fields