BETA

Importing Orders

This page documents the API under the order endpoint /{projectKey}/orders. Namely, we document OrderImportRequest and the endpoint methods for ImportOperations for Orders.

OrderImportRequest

Representations

OrderImportRequest

An import request for multiple order import resources.

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" : [ {
"key" : "test-order-number",
"lineItems" : [ {
"name" : {
"en" : "abc"
},
"quantity" : 10,
"price" : {
"value" : {
"type" : "centPrecision",
"centAmount" : 100,
"currencyCode" : "EUR"
}
},
"supplyChannel" : {
"typeId" : "channel",
"key" : "supplier-channel-key"
},
"variant" : {
"key" : "product-variant-key",
"typeId" : "product-variant"
}
} ],
"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"
},
"customerEmail" : "customer-email@example.com",
"customer" : {
"typeId" : "customer",
"key" : "myKey"
},
"orderNumber" : "test-order-number",
"totalPrice" : {
"type" : "centPrecision",
"currencyCode" : "EUR",
"centAmount" : 4200
}
} ]
}

OrderImport

Import representation for an order.

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

The order import draft is a snapshot of an order at the time it was imported.

key
String
orderNumber
String

Maps to Order.orderNumber.

References a customer by its key.

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.

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.

Maps to Order.shippingInfo.

completedAt
DateTime

Maps to Order.completedAt.

inventoryMode

Maps to Order.inventoryMode.

taxRoundingMode

Maps to Order.taxRoundingMode.

taxCalculationMode

Maps to Order.taxCalculationMode.

Maps to Order.origin.

itemShippingAddresses
Array of Address

Maps to Order.itemShippingAddresses.

custom

Maps to Order.custom.

CustomerKeyReference

References a customer by its key.

key
String
typeId
String
"customer"

References a customer.

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 which includes line operations that do not exist in the project or have been deleted. Products and variants referenced by a line item must already exist in the commercetools project.

Maps to LineItem.productId.

name
LocalizedString

Maps to LineItem.name.

variant
LineItemProductVariantImportDraft

Maps to ProductVariantImportDraft.

price
LineItemPrice

Maps to LineItem.price.

quantity
Float

Maps to LineItem.quantity.

state
Array of ItemState
supplyChannel

References a supply channel. Maps to LineItem.supplyChannel.

The supply channel referenced must already exist in the commercetools project, or the import operation state is set to Unresolved.

distributionChannel

References a distribution channel. Maps to LineItem.distributionChannel.

The distribution channel referenced must already exist in the commercetools project, or the import operation state is set to Unresolved.

taxRate
TaxRate

Maps to LineItem.taxRate.

shippingDetails
ItemShippingDetailsDraft

Maps to LineItem.shippingDetails.

CustomLineItemDraft

name
LocalizedString
taxedPrice
CustomLineItemTaxedPrice
totalPrice
slug
String
quantity
Float
state
Array of ItemState

References a tax category by its key.

taxRate
TaxRate
externalTaxRate
ExternalTaxRateDraft
discountedPricePerQuantity
Array of DiscountedLineItemPriceDraft
shippingDetails
ItemShippingDetailsDraft

TypedMoney

HighPrecisionMoney

type
String
"highPrecision"
fractionDigits
Int
Maximum: 12
centAmount
Int
currencyCode
CurrencyCode

The currency code compliant to ISO 4217.

preciseAmount
Int

Money

type
String
"centPrecision"
fractionDigits
Int
Maximum: 12
centAmount
Int
currencyCode
CurrencyCode

The currency code compliant to ISO 4217.

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

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
shippingRate
ShippingRateDraft
taxRate
TaxRate

References a tax category by its key.

shippingMethod
ShippingMethodKeyReference

References a shipping method by its key.

deliveries
Array of Delivery
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

Custom

The representation to be sent to the server when creating a resource with custom fields.

type
TypeKeyReference

The type that provides the field definitions for this object.

fields
FieldContainer

The custom fields of this object.

CartDiscountKeyReference

References a cart discount by its key.

key
String
typeId
String
"cart-discount"

References a cart discount.

Endpoints

Request Order Data to be Imported

Creates import request for creating new orders or updating existing ones.

POST
https://import.europe-west1.gcp.commercetools.com/{projectKey}/orders/importSinkKey={importSinkKey}
OAuth 2.0 Scopes:
manage_project:{projectKey}, manage_orders:{projectKey}
Path Parameters:
projectKey
String
The commercetools project key.
importSinkKey
String
The import sink used to create the new resource
Request Body:OrderImportRequest
Response:

201ImportResponse

Request Example:cURL
curl -X POST https://import.europe-west1.gcp.commercetools.com/{projectKey}/orders/importSinkKey={importSinkKey} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"type" : "order",
"resources" : [ {
"key" : "test-order-number",
"lineItems" : [ {
"name" : {
"en" : "abc"
},
"quantity" : 10,
"price" : {
"value" : {
"type" : "centPrecision",
"centAmount" : 100,
"currencyCode" : "EUR"
}
},
"supplyChannel" : {
"typeId" : "channel",
"key" : "supplier-channel-key"
},
"variant" : {
"key" : "product-variant-key",
"typeId" : "product-variant"
}
} ],
"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"
},
"customerEmail" : "customer-email@example.com",
"customer" : {
"typeId" : "customer",
"key" : "myKey"
},
"orderNumber" : "test-order-number",
"totalPrice" : {
"type" : "centPrecision",
"currencyCode" : "EUR",
"centAmount" : 4200
}
} ]
}
DATA

Get ImportOperations

Get ImportOperations by an ImportSink Key

Retrieves all order import operations of an import sink key.

GET
https://import.europe-west1.gcp.commercetools.com/{projectKey}/orders/importSinkKey={importSinkKey}/import-operations
OAuth 2.0 Scopes:
manage_project:{projectKey}, manage_orders:{projectKey}, view_orders:{projectKey}
Path Parameters:
projectKey
String
The commercetools project key.
importSinkKey
String
The import sink used to create the new resource
Query Parameters:
limit
Float
-
offset
Float
-
resourceKey
String
The key of the import operation to retrieve.
state
The state of the import operations to retrieve.
Request Example:cURL
curl -X GET https://import.europe-west1.gcp.commercetools.com/{projectKey}/orders/importSinkKey={importSinkKey}/import-operations -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Get an ImportOperation by its ID

Retrieves the import operation with the given id.

GET
https://import.europe-west1.gcp.commercetools.com/{projectKey}/orders/importSinkKey={importSinkKey}/import-operations/{id}
OAuth 2.0 Scopes:
manage_project:{projectKey}, manage_orders:{projectKey}, view_orders:{projectKey}
Path Parameters:
projectKey
String
The commercetools project key.
importSinkKey
String
The import sink used to create the new resource
id
String
The operation identifier
Response:
Request Example:cURL
curl -X GET https://import.europe-west1.gcp.commercetools.com/{projectKey}/orders/importSinkKey={importSinkKey}/import-operations/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Response Example:json
{
"version" : 1,
"state" : "Unresolved",
"importSinkKey" : "category-import-sink",
"resourceKey" : "child-category",
"resourceType" : "category",
"resourceAsString" : "'{}'",
"id" : "252c6ed3-c668-4610-afe9-87b9255e62e0",
"createdAt" : "2018-02-05T09:47:16.648Z",
"lastModifiedAt" : "2018-02-05T09:47:16.649Z",
"expiresAt" : "2018-02-08T09:47:16.649Z",
"retryCount" : 0,
"unresolvedReferences" : [ {
"typeId" : "category",
"key" : "my-parent-category-key"
} ]
}