Importing Orders

Create new Orders in your Project.

The Order data to import is represented by OrderImport and included in an OrderImportRequest, which is imported using Import Orders.

To update an Order's ReturnInfo, Parcel, and Delivery information, use OrderPatchImport.

Representations

OrderImportRequest

The request body to import Orders. Contains data for Orders to be created in a Project.

type
String
"order"

The Order import resource type.

resources
Array of OrderImport

The order import resources of this request.

MaxItems: 20
Example: json
{
"type": "order",
"resources": [
{
"orderNumber": "test-order-number",
"customer": {
"typeId": "customer",
"key": "order-customer-key"
},
"customerEmail": "customer-email@example.com",
"shippingInfo": {
"shippingMethodName": "string-name",
"price": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 300
},
"shippingRate": {
"price": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 3
},
"tiers": []
},
"deliveries": [
{
"id": "4ce24c27-cce5-447c-890e-0d6b70b690ba",
"createdAt": "2021-04-30T09:21:15.003Z",
"items": [
{
"id": "95a6e7a7-b74e-4397-b0b4-37473d2e3573",
"quantity": 4
}
],
"parcels": [
{
"id": "98840afa-ac20-4a34-a904-88d3407e2d76",
"createdAt": "2021-04-30T09:21:15.003Z",
"measurements": {
"heightInMillimeter": 20,
"lengthInMillimeter": 40,
"widthInMillimeter": 5,
"weightInGram": 10
}
}
]
}
]
},
"lineItems": [
{
"name": {
"en": "abc"
},
"quantity": 10,
"price": {
"value": {
"type": "centPrecision",
"centAmount": 100,
"currencyCode": "EUR"
}
},
"supplyChannel": {
"typeId": "channel",
"key": "supplier-channel-key"
},
"variant": {
"productVariant": {
"typeId": "product-variant",
"key": "product-key"
},
"sku": "variant-sku",
"attributes": [],
"images": [],
"prices": []
}
}
],
"customLineItems": [
{
"name": {
"en": "name"
},
"totalPrice": {
"type": "centPrecision",
"centAmount": 123,
"currencyCode": "EUR"
},
"state": [
{
"quantity": 10,
"state": {
"key": "state-key",
"typeId": "state"
}
}
],
"money": {
"type": "centPrecision",
"centAmount": 123,
"currencyCode": "EUR"
},
"quantity": 10,
"slug": "my-slug",
"taxCategory": {
"typeId": "tax-category",
"key": "tax-category-key"
},
"discountedPricePerQuantity": [
{
"value": {
"type": "centPrecision",
"centAmount": 123,
"currencyCode": "EUR"
},
"includedDiscounts": [
{
"discountedAmount": {
"type": "centPrecision",
"centAmount": 123,
"currencyCode": "EUR"
},
"discount": {
"typeId": "cart-discount",
"key": "cart-discount-key"
}
}
]
}
]
}
],
"customerGroup": {
"typeId": "customer-group",
"key": "customer-group-key"
},
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 4200
}
}
]
}

OrderImport

The data representation for an Order to be imported that is persisted as an Order in the Project.

In commercetools, you can import an Order using the Create Order by Import endpoint method instead of creating it from a Cart.

An OrderImport is a snapshot of an order at the time it was imported.

orderNumber
String

Maps to Order.orderNumber, String that uniquely identifies an order. It should be unique across a project. Once it's set it cannot be changed.

customer
customerEmail
String

Maps to Order.customerEmail.

lineItems

Maps to Order.lineItems.

customLineItems

Maps to Order.customLineItems

totalPrice

Maps to Order.totalPrice.

taxedPrice

Maps to Order.taxedPrice.

shippingAddress

Maps to Order.shippingAddress.

billingAddress

Maps to Order.billingAddress.

customerGroup

Maps to Order.customerGroup.

country
String

Maps to Order.country.

orderState

Maps to Order.orderState.

shipmentState

Maps to Order.shipmentState.

paymentState

Maps to Order.paymentState.

shippingInfo

Maps to Order.shippingInfo.

completedAt

Maps to Order.completedAt.

inventoryMode

Maps to Order.inventoryMode.

taxRoundingMode

Maps to Order.taxRoundingMode.

taxCalculationMode

Maps to Order.taxCalculationMode.

origin

Maps to Order.origin.

itemShippingAddresses
Array of Address

Maps to Order.itemShippingAddresses.

Reference to the Store in which the Order is associated. If referenced Store does not exist, the state of the ImportOperation will be set to unresolved until the necessary Store exists.

Reference to a State in a custom workflow.

custom

Maps to Order.custom.

LineItemImportDraft

Represents an individual Line Item in an Order. A line item is a snapshot of a product at the time it was added to the order.

You cannot create an Order that includes line item operations that do not exist in the Project or have been deleted. Products and Product Variants referenced by a line item must already exist in the Project.

product

Maps to LineItem.productId.

name

Maps to LineItem.name.

variant
LineItemProductVariantImportDraft

Maps to ProductVariantImportDraft.

price
LineItemPrice

Maps to LineItem.price.

quantity
Int

Maps to LineItem.quantity.

state
Array of ItemState
supplyChannel

Maps to LineItem.supplyChannel. The Reference to the Supply Channel with which the LineItem is associated. If referenced Supply Channel does not exist, the state of the ImportOperation will be set to unresolved until the necessary Supply Channel is created.

distributionChannel

Maps to LineItem.distributionChannel. The Reference to the Distribution Channel with which the LineItem is associated. If referenced CustomerGroup does not exist, the state of the ImportOperation will be set to unresolved until the necessary Distribution Channel is created.

taxRate
TaxRate

Maps to LineItem.taxRate.

shippingDetails
ItemShippingDetailsDraft

Maps to LineItem.shippingDetails.

custom

Custom Fields for this Line Item.

CustomLineItemDraft

name
money
taxedPrice
CustomLineItemTaxedPrice
totalPrice
slug
String
quantity
Int
state
Array of ItemState
taxCategory

References a tax category by key.

taxRate
TaxRate
externalTaxRate
ExternalTaxRateDraft
discountedPricePerQuantity
Array of DiscountedLineItemPriceDraft
shippingDetails
ItemShippingDetailsDraft

TaxedPrice

totalNet
Money

Maps to TaxedPrice.totalNet.

totalGross
Money

Maps to TaxedPrice.totalGross.

taxPortions
Array of TaxPortion

Maps to TaxedPrice.taxPortions.

Address

id
String
key
String
title
String
salutation
String
firstName
String
lastName
String
streetName
String
streetNumber
String
additionalStreetInfo
String
postalCode
String
city
String
region
String
state
String
country
CountryCode

A two-digit country code as per ISO 3166-1 alpha-2.

company
String
department
String
building
String
apartment
String
pOBox
String
phone
String
mobile
String
email
String
fax
String
additionalAddressInfo
String
externalId
String
custom

Custom Fields defined for the Address. Custom Fields can only be applied to shippingAddress.

OrderState

Maps to Order.orderState.

Open
Confirmed
Complete
Cancelled

ShipmentState

Maps to Order.shipmentState.

Shipped
Ready
Pending
Delayed
Partial
Backorder

PaymentState

Maps to Order.paymentState.

BalanceDue
Failed
Pending
CreditOwed
Paid

ShippingInfoImportDraft

Maps to an order's shippingInfo property. This field is usually populated by the cart assosciated with the order, but when importing orders you must provide a draft representation as a part of the OrderImport.

shippingMethodName
String
price
shippingRate
ShippingRateDraft
taxRate
TaxRate
taxCategory

References a tax category by key.

shippingMethod

References a shipping method by key.

deliveries
Array of Delivery

Note that you can not add a DeliveryItem on import, as LineItems and CustomLineItems are not yet referencable by an id.

discountedPrice
DiscountedLineItemPriceDraft
shippingMethodState
ShippingMethodState

InventoryMode

Maps to Order.inventoryMode.

TrackOnly
ReserveOnOrder

RoundingMode

Maps to Order.taxRoundingMode.

HalfEven
HalfUp
HalfDown

TaxCalculationMode

Maps to Order.taxCalculationMode.

LineItemLevel
UnitPriceLevel

CartOrigin

Maps to Order.origin.

Customer
Merchant

Delivery

id
String
items
Array of DeliveryItem
parcels
Array of Parcel
address
createdAt

Parcel

id
String
measurements
trackingData
items
Array of DeliveryItem
custom
createdAt

Import Orders

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

Creates a request for creating new Orders.

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 new resource

Request Body:OrderImportRequestasapplication/json
Response:
201ImportResponseasapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/orders/import-containers/{importContainerKey} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"type" : "order",
"resources" : [ {
"orderNumber" : "test-order-number",
"customer" : {
"typeId" : "customer",
"key" : "order-customer-key"
},
"customerEmail" : "customer-email@example.com",
"shippingInfo" : {
"shippingMethodName" : "string-name",
"price" : {
"type" : "centPrecision",
"currencyCode" : "EUR",
"centAmount" : 300
},
"shippingRate" : {
"price" : {
"type" : "centPrecision",
"currencyCode" : "EUR",
"centAmount" : 3
},
"tiers" : [ ]
},
"deliveries" : [ {
"id" : "4ce24c27-cce5-447c-890e-0d6b70b690ba",
"createdAt" : "2021-04-30T09:21:15.003Z",
"items" : [ {
"id" : "95a6e7a7-b74e-4397-b0b4-37473d2e3573",
"quantity" : 4
} ],
"parcels" : [ {
"id" : "98840afa-ac20-4a34-a904-88d3407e2d76",
"createdAt" : "2021-04-30T09:21:15.003Z",
"measurements" : {
"heightInMillimeter" : 20,
"lengthInMillimeter" : 40,
"widthInMillimeter" : 5,
"weightInGram" : 10
}
} ]
} ]
},
"lineItems" : [ {
"name" : {
"en" : "abc"
},
"quantity" : 10,
"price" : {
"value" : {
"type" : "centPrecision",
"centAmount" : 100,
"currencyCode" : "EUR"
}
},
"supplyChannel" : {
"typeId" : "channel",
"key" : "supplier-channel-key"
},
"variant" : {
"productVariant" : {
"typeId" : "product-variant",
"key" : "product-key"
},
"sku" : "variant-sku",
"attributes" : [ ],
"images" : [ ],
"prices" : [ ]
}
} ],
"customLineItems" : [ {
"name" : {
"en" : "name"
},
"totalPrice" : {
"type" : "centPrecision",
"centAmount" : 123,
"currencyCode" : "EUR"
},
"state" : [ {
"quantity" : 10,
"state" : {
"key" : "state-key",
"typeId" : "state"
}
} ],
"money" : {
"type" : "centPrecision",
"centAmount" : 123,
"currencyCode" : "EUR"
},
"quantity" : 10,
"slug" : "my-slug",
"taxCategory" : {
"typeId" : "tax-category",
"key" : "tax-category-key"
},
"discountedPricePerQuantity" : [ {
"value" : {
"type" : "centPrecision",
"centAmount" : 123,
"currencyCode" : "EUR"
},
"includedDiscounts" : [ {
"discountedAmount" : {
"type" : "centPrecision",
"centAmount" : 123,
"currencyCode" : "EUR"
},
"discount" : {
"typeId" : "cart-discount",
"key" : "cart-discount-key"
}
} ]
} ]
} ],
"customerGroup" : {
"typeId" : "customer-group",
"key" : "customer-group-key"
},
"totalPrice" : {
"type" : "centPrecision",
"currencyCode" : "EUR",
"centAmount" : 4200
}
} ]
}
DATA