The Order Import API allows you to import existing Orders from a different system or a different Composable Commerce Project.
Representations
OrderImportDraft
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 | The Customer Group of the Customer the Order belongs to. |
businessUnit | 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 | 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 | 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 Default: taxedPrice .HalfEven |
taxCalculationMode | Determines how taxes are calculated for Default: taxedPrice .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 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 | Custom Fields for the Order. |
LineItemImportDraft
productId
and variant.id
, or by providing a variant.sku
.key String | User-defined unique identifier of the Line Item. MinLength:2 MaxLength: 256 Pattern: ^[a-zA-Z0-9_-] |
name | Name of the Line Item. |
variant | 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
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 | |
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:2 MaxLength: 256 Pattern: ^[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. |
taxCategory | Include a value to associate a Tax Category with the Custom Line Item. |
priceMode |
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
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. |
taxCategory | Include a value to associate a Tax Category with the shipping information. |
shippingMethod | 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 Array of DiscountedLineItemPortionDraft | Discounts to be applied. |
Create Order by Import
Specific Error Codes:
manage_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
application/json
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
by language
store
field, excess LocalizedStrings can be are filtered.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 Projectlanguages
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
store
field, excess Prices can be filtered .distributionChannels
is set, then only the Prices with distribution channels defined in distributionChannels
, and Prices without distribution channels are kept.countries
is set, then only the Prices with a country defined in countries
, and Prices without a country are kept.by Inventory Entry
store
field, excess ProductVariantAvailabilities can be filtered.supplyChannels
is set, then only Inventory Entries with supply channels defined in supplyChannels
, and Inventory Entries without supply channels are kept.