Order Import

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

The Create Order by Import endpoint imports a single Order into Composable Commerce 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.

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 Composable Commerce APIs.

Representations

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.

The Customer Group of the Customer the Order belongs to.

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.

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

Line Items to add to the Order.

If not specified, customLineItems must not be empty.

customLineItems

Custom Line Items to add to the Cart.

If not specified, lineItems must not be empty.

totalPrice

The total Price of the Order. The amount can be negative.

taxedPrice

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.

taxRoundingMode

Determines how monetary values are rounded when calculating taxes for taxedPrice.

Default: HalfEven
taxCalculationMode

Determines how taxes are calculated for taxedPrice.

Default: LineItemLevel
inventoryMode

Determines how stock quantities are tracked for Line Items in the Cart.

Default: None
billingAddress

Billing address associated with the Order.

shippingAddress

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

Shipping-related information of the Order.

paymentInfo

Payment information associated with the Order.

paymentState

Payment status of the Order.

shipmentState

Shipment status of the Order.

orderState

Current status of the Order.

Default: Open
state

State of the Order in a custom workflow.

country

Include a value to associate a country with the Order.

Pattern: ^[A-Z]{2}$
origin

Indicates the origin of the Order.

Default: Customer
completedAt

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

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 unique identifier of the Line Item.

MinLength: 2MaxLength: 256Pattern: ^[a-zA-Z0-9_-]
name

Name of the Line Item.

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
Int

The number of Product Variants in the LineItem. Can be a negative value.

price

The Line Item price for quantity = 1. The amount can be negative.

taxRate

The tax rate used to calculate the taxedPrice of the Order.

distributionChannel

The Channel used to select a Price. This Channel must have the ProductDistribution role.

supplyChannel

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

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

Container for Line Item-specific addresses.

state
Array of ItemState

States of the Line Item.

custom

Custom Fields of the LineItem.

ProductVariantImportDraft

Contains the Product Variant to be used in the LineItemImportDraft.

id
Int

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 unique identifier of the Custom Line Item.

MinLength: 2MaxLength: 256Pattern: ^[a-zA-Z0-9_-]
name

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
Int

The number of items in the Custom Line Item. Can be a negative value.

money

The cost of individual items in the Custom Line Item. The amount can be negative.

taxRate

The tax rate used to calculate the taxedPrice of the Order.

Include a value to associate a Tax Category with the Custom Line Item.

  • If Standard, Cart Discounts with a matching CartDiscountCustomLineItemsTarget are applied to the Custom Line Item.
  • If External, Cart Discounts are not considered on the Custom Line Item.
Default: Standard
shippingDetails

Container for Custom Line Item-specific addresses.

state
Array of ItemState

State of the Custom Line Items.

custom

Custom Fields of the CustomLineItem.

TaxedPriceDraft

totalNet

Total net price of the Cart or Order.

totalGross

Total gross price of the Cart or Order.

taxPortions
Array of TaxPortionDraft

Taxable portions added to the totalGross.

Calculated from the TaxRates.

totalTax

Total tax applicable for the Cart or Order.

ShippingInfoImportDraft

Becomes the shippingInfo of the imported Order.

shippingMethodName
String

Name of the Shipping Method.

price

The base price for the Shipping Method.

shippingRate

Shipping rate information for the Order.

taxRate

Include a Tax Rate for the Shipping Method.

Include a value to associate a Tax Category with the shipping information.

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

Discounted Price of the Shipping Method.

shippingMethodState

Indicates if the ShippingMethod referenced is allowed for the Order or not.

Default: MatchesCart

DiscountedLineItemPriceDraft

value

Discounted money value.

includedDiscounts

Discounts to be applied.

Create Order by Import

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

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:
201Orderasapplication/json
Request Example:cURL
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" : 1000,
"currencyCode" : "EUR"
}
}
DATA
201 Response Example: Orderjson
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}

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