Order Import

The Order Import API allows you to import existing Orders from a different system or a different Project.

The Create Order by Import endpoint imports a single Order without the need of creating a Cart before creating the Order. No error is given when specified Prices or quantities of (Custom) Line Items have negative values. The Order total price needs to be set explicitly, it is not calculated from the sum of (Custom) Line Item totals.

You can also provide pre-calculated taxedPrice values on Line Items, Custom Line Items, and Shipping Info. If taxedPrice is set, the values are stored as-is on the resulting item instead of being derived from the taxRate. This is useful when importing Orders from external systems (for example, external tax services) to avoid rounding discrepancies. If taxedPrice is not set, the platform continues to derive the taxed price from the taxRate as before.

When taxedPrice is provided on a Line Item or Custom Line Item, the values are stored as sent and are not checked for consistency, so totalGross - totalNet does not need to equal totalTax. For Line Items and Custom Line Items, taxRate must also be provided; for Shipping Info, taxRate is optional.

To import Orders in bulk, use the Import Orders BETA endpoint of the Import API. The Import API, however, does not support beta features on the commercetools commerce APIs.

Create Order by Import

POST

https://api.{region}.commercetools.com/{projectKey}/orders/import

Creates an Order without needing to create a Cart first. Importing an Order produces the Order Imported Message.

Specific Error Codes:

OAuth 2.0 Scopes:

manage_orders:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Request Body:OrderImportDraftasapplication/json

Response:

201

Order

application/json

curl https://api.{region}.commercetools.com/{projectKey}/orders/import -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "orderNumber" : "100000001",
  "totalPrice" : {
    "centAmount" : 4200,
    "currencyCode" : "EUR"
  },
  "lineItems" : [ ],
  "customLineItems" : [ {
    "name" : {
      "en" : "Name EN",
      "de" : "Name DE"
    },
    "quantity" : 1,
    "money" : {
      "currencyCode" : "EUR",
      "centAmount" : 4200
    },
    "slug" : "mySlug"
  } ]
}
DATA

{
  "type": "Order",
  "id": "35f816ea-7770-4623-895b-7a6454e22e8a",
  "version": 1,
  "createdAt": "2024-10-09T23:12:14.264Z",
  "lastModifiedAt": "2024-10-09T23:12:14.264Z",
  "lastModifiedBy": {
    "clientId": "qnfzsm5-qNfCGwHiRgI03Emc",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "qnfzsm5-qNfCGwHiRgI03Emc",
    "isPlatformClient": false
  },
  "orderNumber": "100000001",
  "totalPrice": {
    "type": "centPrecision",
    "currencyCode": "EUR",
    "centAmount": 4200,
    "fractionDigits": 2
  },
  "orderState": "Open",
  "syncInfo": [],
  "returnInfo": [],
  "taxMode": "External",
  "inventoryMode": "None",
  "taxRoundingMode": "HalfEven",
  "taxCalculationMode": "LineItemLevel",
  "origin": "Customer",
  "shippingMode": "Single",
  "shipping": [],
  "lineItems": [],
  "customLineItems": [
    {
      "id": "fc864da7-0cc9-438f-9626-4d5907ea51c9",
      "name": {
        "en": "Name EN",
        "de": "Name DE"
      },
      "money": {
        "type": "centPrecision",
        "currencyCode": "EUR",
        "centAmount": 4200,
        "fractionDigits": 2
      },
      "slug": "mySlug",
      "quantity": 1,
      "discountedPricePerQuantity": [],
      "state": [
        {
          "quantity": 1,
          "state": {
            "typeId": "state",
            "id": "7e3b7f8b-74c1-4d01-8335-0197ba1de6e9"
          }
        }
      ],
      "totalPrice": {
        "type": "centPrecision",
        "currencyCode": "EUR",
        "centAmount": 4200,
        "fractionDigits": 2
      },
      "taxedPricePortions": [],
      "perMethodTaxRate": [],
      "priceMode": "Standard"
    }
  ],
  "transactionFee": false,
  "discountCodes": [],
  "directDiscounts": [],
  "itemShippingAddresses": [],
  "refusedGifts": []
}

Filtering

During Order Import, if the referenced Store defines languages, distribution channels, supply channels, or countries, they can be used to filter languages, Prices, or Inventory Entry respectively.

by language

Based on the languages configured for the referenced Store in the OrderImportDraft store field, excess LocalizedStrings can be filtered.

If the Store languages is set, then only localized values of languages defined in languages are kept.

If no matching language is found on a LocalizedString for languages specified in the Store languages, as a fallback, the next language specified in the Project languages is used. This ensures that required fields do not remain empty in the Order.
If an empty value is found on a LocalizedString for languages specified in the Store languages, the empty value will be imported for that language.

by Price

Based on the distribution channels configured for the referenced Store in the OrderImportDraft store field, excess Prices can be filtered.

If the Store distributionChannels is set, then only the Prices with distribution channels defined in distributionChannels, and Prices without distribution channels are kept.

Likewise, if the Store countries is set, then only the Prices with a country defined in countries, and Prices without a country are kept.

by Inventory Entry

Based on the inventory supply channels configured for the referenced Store in the OrderImportDraft store field, excess ProductVariantAvailabilities can be filtered.

If the Store supplyChannels is set, then only Inventory Entries with supply channels defined in supplyChannels, and Inventory Entries without supply channels are kept.

Representations

OrderImportDraft

LineItemImportDraft -ProductVariantImportDraft

CustomLineItemImportDraft

TaxedPriceDraft

ShippingInfoImportDraft -DiscountedLineItemPriceDraft

OrderImportDraft

This type is equivalent to ImportOrderDraft in the GraphQL API.

A snapshot of an Order at the time it was imported.

`orderNumber` String	User-defined identifier of the Order. Must be unique across a Project. Once set, the value cannot be changed.
`purchaseOrderNumber` String	User-defined identifier for a purchase Order.
`customerId` String	The `id` of the Customer the Order belongs to.
`customerEmail` String	The Email address of the Customer the Order belongs to. Can be used instead of `customerId` when no check against existing Customers is required.
`customerGroup` CustomerGroupResourceIdentifier	The Customer Group of the Customer the Order belongs to.
`businessUnit` BusinessUnitResourceIdentifier	ResourceIdentifier to the Business Unit the Order should belong to. When the `customerId` of the Order is also set, the Customer must be an Associate of the Business Unit. Only available for B2B-enabled Projects.
`store` StoreResourceIdentifier	The Store the Order belongs to. Used for filtering. If a LineItemImportDraft or a CustomLineItemImportDraft specifies a `distributionChannel` or a `supplyChannel` that is not defined for the referenced Store, the Order Import gets rejected. The same applies when the provided `country` is not defined for the referenced Store.
`lineItems` Array of LineItemImportDraft	Line Items to add to the Order. If not specified, `customLineItems` must not be empty.
`customLineItems` Array of CustomLineItemImportDraft	Custom Line Items to add to the Cart. If not specified, `lineItems` must not be empty.
`totalPrice` Money	The total Price of the Order. The amount can be negative.
`taxedPrice` TaxedPriceDraft	Include TaxedPrice information for the Order. If not included, and if you have Tax Rates set for Line Items and Custom Line Items, the Order total will not be recalculated.
`priceRoundingMode` RoundingMode	Determines how the total prices on LineItems and CustomLineItems are rounded when calculated. Default: `HalfEven`
`taxRoundingMode` RoundingMode	Determines how monetary values are rounded when calculating taxes for `taxedPrice`. Default: `HalfEven`
`taxCalculationMode` TaxCalculationMode	Determines how taxes are calculated for `taxedPrice`. Default: `LineItemLevel`
`inventoryMode` InventoryMode	Determines how stock quantities are tracked for Line Items in the Cart. Default: `None`
`billingAddress` BaseAddress	Billing address associated with the Order.
`shippingAddress` BaseAddress	Shipping address associated with the Order.
`itemShippingAddresses` Array of BaseAddress	Addresses for Orders with multiple shipping addresses. Addresses must include a value for `key`.
`shippingInfo` ShippingInfoImportDraft	Shipping-related information of the Order.
`paymentInfo` PaymentInfo	Payment information associated with the Order.
`paymentState` PaymentState	Payment status of the Order.
`shipmentState` ShipmentState	Shipment status of the Order.
`orderState` OrderState	Current status of the Order. Default: `Open`
`state` StateReference	State of the Order in a custom workflow.
`country` CountryCode	Include a value to associate a country with the Order. Pattern: `^[A-Z]{2}$`
`origin` CartOrigin	Indicates the origin of the Order. Default: `Customer`
`completedAt` DateTime	User-defined date and time for the Order. This value does not influence the `createdAt` or `lastModifiedAt` values of the Order created by the Order Import.
`custom` CustomFieldsDraft	Custom Fields for the Order.

LineItemImportDraft

Represents a snapshot of a Product Variant at the time it was imported with the Order. The Product Variant can be specified by providing a productId and variant.id, or by providing a variant.sku.

`key` String	User-defined identifier of the Line Item. Must be unique among Line Items in the Order. MinLength: `2`MaxLength: `256`Pattern: `^[a-zA-Z0-9_-]`
`name` LocalizedString	Name of the Line Item.
`variant` ProductVariantImportDraft	The Product Variant to use as a Line Item.
`productId` String	`id` of the Product the Product Variant belongs to. If provided, you must also set `variant.id`.
`quantity` Int64	Quantity of the Product Variant. Can be a negative value.
`price` PriceDraft	The Line Item price for `quantity` = `1`. The amount can be negative.
`taxRate` TaxRate	The tax rate used to calculate the `taxedPrice` of the Line Item if `taxedPrice` is not provided.
`taxedPrice` TaxedPriceDraft	Taxed price of the Line Item. If provided, the values are stored as-is on the resulting LineItem instead of being derived from `price`, `quantity`, and `taxRate`. Can only be set if `taxRate` is also set.
`distributionChannel` ChannelResourceIdentifier	The Channel used to select a Price. This Channel must have the `ProductDistribution` role.
`supplyChannel` ChannelResourceIdentifier	The Channel used to supply Line Items. By providing supply Channel information, you can uniquely identify Inventory entries that should be reserved. This Channel must have the `InventorySupply` role.
`inventoryMode` InventoryMode	Inventory mode specific to the LineItem, valid for the entire `quantity` of the LineItem. Set only if Inventory mode should be different from the `inventoryMode` specified on the OrderImportDraft.
`shippingDetails` ItemShippingDetailsDraft	Container for Line Item-specific addresses.
`state` Array of ItemState	States of the Line Item.
`custom` CustomFieldsDraft	Custom Fields for the LineItem.

ProductVariantImportDraft

Contains the Product Variant to be used in the LineItemImportDraft.

`id` Int64	The `id` of the ProductVariant. Required if you do not set a value for `sku`. If set, you must specify a `productId` in the LineItemImportDraft also.
`sku` String	The `sku` of the ProductVariant. Required if you do not set a value for `id`.
`prices` Array of PriceDraft	The Prices of the Product Variant if you want to override the `prices` property in the referenced ProductVariant. If not set, the `prices` from the referenced ProductVariant are used in the resulting Order. If set, each Price must have its unique price scope (same `value.currencyCode`, `country`, `customerGroup`, `channel`, `validFrom` and `validUntil`).
`attributes` Array of Attribute	The Attributes of the Product Variant if you want to override the `attributes` property in the referenced ProductVariant. If not set, the `attributes` from the referenced ProductVariant are copied to the resulting Order.
`images` Array of Image	The Images of the Product Variant if you want to override the `images` property in the referenced ProductVariant. If not set, the `images` from the referenced ProductVariant are copied to the resulting Order.

CustomLineItemImportDraft

Custom Line Items contain generic user-defined items that are not linked to Products.

`key` String	User-defined identifier of the Custom Line Item. Must be unique among Custom Line Items in the Order. MinLength: `2`MaxLength: `256`Pattern: `^[a-zA-Z0-9_-]`
`name` LocalizedString	Name of the Custom Line Item.
`slug` String	User-defined identifier used in a deep-link URL for the Custom Line Item. This value should match the pattern `[a-zA-Z0-9_-]{2,256}`.
`quantity` Int64	Quantity of items in the Custom Line Item. Can be a negative value.
`money` Money	The cost of individual items in the Custom Line Item. The amount can be negative. To set the money value in high precision, use HighPrecisionMoneyDraft.
`taxRate` TaxRate	The tax rate used to calculate the `taxedPrice` of the Custom Line Item if `taxedPrice` is not provided.
`taxedPrice` TaxedPriceDraft	Taxed price of the Custom Line Item. If provided, the values are stored as-is on the resulting CustomLineItem instead of being derived from `money`, `quantity`, and `taxRate`. Can only be set if `taxRate` is also set.
`taxCategory` TaxCategoryResourceIdentifier	Include a value to associate a Tax Category with the Custom Line Item.
`priceMode` CustomLineItemPriceMode	If `Standard`, Cart Discounts with a matching CartDiscountCustomLineItemsTarget, MultiBuyCustomLineItemsTarget, or CartDiscountPatternTarget are applied to the Custom Line Item. If `External`, Cart Discounts are not considered on the Custom Line Item. Default: `Standard`
`shippingDetails` ItemShippingDetailsDraft	Container for Custom Line Item-specific addresses.
`state` Array of ItemState	State of the Custom Line Items.
`custom` CustomFieldsDraft	Custom Fields for the CustomLineItem.

TaxedPriceDraft

`totalNet` Money	Total net price of the Cart or Order.
`totalGross` Money	Total gross price of the Cart or Order.
`taxPortions` Array of TaxPortionDraft	Taxable portions added to the `totalGross`. Calculated from the TaxRates.
`totalTax` TypedMoneyDraft	Total tax applicable for the Cart or Order.

ShippingInfoImportDraft

Becomes the shippingInfo of the imported Order.

`shippingMethodName` String	Name of the Shipping Method.
`price` Money	The base price for the Shipping Method.
`shippingRate` ShippingRateDraft	Shipping rate information for the Order.
`taxRate` TaxRate	Include a Tax Rate for the Shipping Method.
`taxedPrice` TaxedPriceDraft	Taxed price of the Shipping Method. If provided, the values are stored as-is on the resulting ShippingInfo instead of being derived from `price` and `taxRate`.
`taxCategory` TaxCategoryResourceIdentifier	Include a value to associate a Tax Category with the shipping information.
`shippingMethod` ShippingMethodResourceIdentifier	Include a value to associate a Shipping Method with the Order.
`deliveries` Array of DeliveryDraft	Information on how items are to be delivered to customers.
`discountedPrice` DiscountedLineItemPriceDraft	Discounted Price of the Shipping Method.
`shippingMethodState` ShippingMethodState	Indicates if the ShippingMethod referenced is allowed for the Order or not. Default: `MatchesCart`

DiscountedLineItemPriceDraft

`value` Money	Discounted money value.
`includedDiscounts` Array of DiscountedLineItemPortionDraft	Discounts to be applied.

Order Import

Create Order by Import.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Filtering.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

by language.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

by Price.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

by Inventory Entry.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Representations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

OrderImportDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

LineItemImportDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ProductVariantImportDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

CustomLineItemImportDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

TaxedPriceDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ShippingInfoImportDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

DiscountedLineItemPriceDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Create Order by Import

Filtering

by language

by Price

by Inventory Entry

Representations

OrderImportDraft

LineItemImportDraft

ProductVariantImportDraft

CustomLineItemImportDraft

TaxedPriceDraft

ShippingInfoImportDraft

DiscountedLineItemPriceDraft