Importing Order Patches

Elevate, May 20-22-2025, Miami Beach, Florida
Update Orders in your Project.
Use this endpoint to update the ReturnInfo, Parcel, and Delivery data of an existing Order.
To create a new Order, use OrderImport.
The Order update data is represented by OrderPatchImport and included in an OrderPatchImportRequest, which is imported using Import OrderPatches.

Representations

OrderPatchImportRequest

The request body to import OrderPatches. The data to be imported are represented by OrderPatchImport.
order-patch

The resource types that can be imported.

patches
Array of OrderPatchImport

The order patches of this request

MaxItems20
Example: json
{
  "type": "order-patch",
  "patches": [
    {
      "orderNumber": "12345",
      "fields": {
        "addReturnInfo": {
          "items": [
            {
              "quantity": 1,
              "lineItemId": "1",
              "comment": "any comment",
              "shipmentState": "Advised"
            }
          ],
          "returnTrackingId": "returnTrackingId-example",
          "returnDate": "2021-04-30T09:21:15.003Z"
        },
        "addDeliveries": [
          {
            "items": [
              {
                "id": "4ce24c27-cce5-447c-890e-0d6b70b690be",
                "quantity": 5
              }
            ],
            "parcels": [
              {
                "measurements": {
                  "heightInMillimeter": 20,
                  "lengthInMillimeter": 40,
                  "widthInMillimeter": 5,
                  "weightInGram": 10
                }
              }
            ]
          }
        ],
        "removeDelivery": {
          "id": "95a6e7a7-b74e-4397-b0b4-37473d2e3573"
        },
        "removeParcelFromDelivery": {
          "parcelId": "98840afa-ac20-4a34-a904-88d3407e2d76"
        },
        "addParcelToDelivery": {
          "deliveryId": "95a6e7a7-b74e-4397-b0b4-37473d2e3573",
          "measurements": {
            "heightInMillimeter": 20,
            "lengthInMillimeter": 40,
            "widthInMillimeter": 5,
            "weightInGram": 10
          }
        },
        "setParcelMeasurements": {
          "parcelId": "98840afa-ac20-4a34-a904-88d3407e2d76",
          "measurements": {
            "heightInMillimeter": 20,
            "lengthInMillimeter": 40,
            "widthInMillimeter": 5,
            "weightInGram": 10
          }
        },
        "setParcelTrackingData": {
          "parcelId": "98840afa-ac20-4a34-a904-88d3407e2d76",
          "trackingData": {
            "carrier": "carrier data"
          }
        },
        "setParcelItems": [
          {
            "parcelId": "98840afa-ac20-4a34-a904-88d3407e2d76",
            "items": [
              {
                "id": "4ce24c27-cce5-447c-890e-0d6b70b690be",
                "quantity": 5
              }
            ]
          }
        ]
      }
    }
  ]
}

OrderPatchImport

Representation for an update of an Order. Use this type to import updates for existing Orders in a Project.
orderNumber
String
Maps to Order.orderNumber, String that uniquely identifies an order, unique across a project.
fields
Each field referenced must be defined in an already existing order in the project or the import operation state is set to validationFailed.

OrderField

Order fields that needs to be added or updated.

addReturnInfo
Maps to Order.returnInfo
addParcelToDelivery
Maps to Order.delivery
addDeliveries
Array of DeliveryDraft
Maps to Order.delivery
removeDelivery
Maps to Order.removeDelivery
removeParcelFromDelivery
Maps to Order.removeParcelFromDelivery
setDeliveryAddress
Maps to Order.addressDraft
setParcelMeasurements
Maps to Order.parcelMeasurements
setParcelTrackingData
Maps to Order.parcelTrackingData
setParcelItems
Array of ParcelItems
Maps to Order.parcelItems

ReturnInfo

items
Array of ReturnItemDraft
returnTrackingId
String
Maps to ReturnInfo.returnTrackingId
returnDate
DateTime
Maps to ReturnInfo.returnDate

ReturnItemDraft

quantity
Int
lineItemId
String
customLineItemId
String
comment
String
shipmentState
Maps to ReturnItem.shipmentState

ReturnShipmentState

Maps to ReturnItem.shipmentState
Advised
Returned
BackInStock
Unusable

DeliveryParcel

deliveryId
String
measurements
trackingData
items
Array of DeliveryItem

DeliveryItem

id
String
quantity
Int

DeliveryDraft

items
Array of DeliveryItem
address
parcels

DeliveryParcelDraft

measurements
trackingData
items
Array of DeliveryItem

DeliveryAddressDraft

deliveryId
String
address

ParcelMeasurement

heightInMillimeter
Int
lengthInMillimeter
Int
widthInMillimeter
Int
weightInGram
Int

ParcelMeasurementDraft

parcelId
String
measurements

ParcelTrackingData

parcelId
String
trackingData

TrackingData

trackingId
String
carrier
String
provider
String
providerTransaction
String
isReturn
Boolean

ParcelItems

parcelId
String
items
Array of DeliveryItem

RemoveDeliveryDraft

id
String

RemoveParcelFromDeliveryDraft

parcelId
String

Import OrderPatches

POST
https://import.{region}.commercetools.com/{projectKey}/order-patches/import-containers/{importContainerKey}

Creates a new import request for order patches

OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String
The Region in which the Project is hosted.
projectKey
String

The Project key.

importContainerKey
String

The ImportContainer used to create the resource

Request Body:OrderPatchImportRequestasapplication/json
Response:
201

ImportResponse

asapplication/json