Order Import
Order import helps to import your existing order without creating the carts.
To import an order into commercetools Composable Commerce, use Create an Order by Import endpoint, it will help you import a single order.
To import Orders in bulk, you can also use the OrderImportRequest endpoint of the Import API BETA. However, please note that the Import API does not support beta features in the commercetools Composable Commerce APIs.
Representations
OrderImportDraft
An OrderImportDraft is a snapshot of an order at the time it was imported.
orderNumber
- String - Optional
String that uniquely identifies an order. It can be used to create more human-readable (in contrast to ID) identifier for the order. It should be unique within a project.customerId
- String - Optional
If given the customer with that ID must exist in the project.customerEmail
- String - Optional
The customer email can be used when no check against existing Customers is desired during order import.store
- KeyReference to a Store - Optional
If the Store defines some languages, distribution channels, supply channels, or countries, they are used to enable Language filtering, Price filtering, and InventoryEntry filtering respectively.
Additionally, suppose that the Store defines distribution (respectively, supply) channels or countries. In this case, if some LineItem or CustomLineItem specifies distribution (respectively, supply) channels or a country that are not defined on the Store, then the OrderImport gets rejected.lineItems
- Array of LineItemImportDraft - Optional
If not givencustomLineItems
must not be empty.customLineItems
- Array of CustomLineItemImportDraft - Optional
If not givenlineItems
must not be empty.totalPrice
- Money - RequiredtaxedPrice
- TaxedPrice - Optional
Order Import does not support calculation of taxes. When setting the draft the taxedPrice is to be provided.shippingAddress
- AddressDraft - OptionalbillingAddress
- AddressDraft - OptionalcustomerGroup
- Reference to a CustomerGroup - Optional
Set when the customer is set and the customer is a member of a customer group. Used for product variant price selection.country
- String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Used for product variant price selection.orderState
- OrderState - Optional
If not given theOpen
state will be assigned by default.shipmentState
- ShipmentState - OptionalpaymentState
- PaymentState - OptionalshippingInfo
- ShippingInfoImportDraft - Optional
Set if the ShippingMethod is set.completedAt
- DateTime - Optionalcustom
- CustomFieldsDraft - Optional
The custom fields.inventoryMode
- InventoryMode - Optional
If not given the modeNone
will be assigned by default.taxRoundingMode
- RoundingMode - Optional
If not given the tax rounding modeHalfEven
will be assigned by default.taxCalculationMode
- TaxCalculationMode - Optional
The default tax calculation mode isLineItemLevel
.origin
- CartOrigin - Optional
The default origin isCustomer
.itemShippingAddresses
- Array of AddressDraft - Optional
Contains addresses for orders with multiple shipping addresses.state
- Reference to a State - Optional
Reference to a State in a custom workflow.paymentInfo
- PaymentInfo - Optional
Reference to Payments.purchaseOrderNumber
- String - Optional
Identifier for a purchase order, usually in a B2B context. The Purchase Order Number is typically entered by the Buyer and can also be used with Quotes.businessUnit
- BusinessUnitResourceIdentifier - BETA - Optional
Reference to a Business Unit the Order is assigned to.
LineItemImportDraft
A line item import draft is a snapshot of a product variant at the time it was imported with the order.
productId
- String - Optional
ID of the existing product. You also need to specify the ID of the variant if this property is set or alternatively you can just specify SKU of the product variant.name
- LocalizedString
The product name.variant
- ProductVariantImportDraftprice
- PriceDraftquantity
- Numberstate
- Array of ItemState - OptionalsupplyChannel
- ResourceIdentifier of a Channel - Optional
Connection to a particular supplier. By providing supply channel information, you can uniquely identify inventory entries that should be reserved. The Channel must have theInventorySupply
ChannelRoleEnumdistributionChannel
- ResourceIdentifier of a Channel - Optional
The channel is used to select a price. The Channel must have theProductDistribution
ChannelRoleEnumtaxRate
- TaxRate - Optionalcustom
- CustomFieldsDraft - Optional
The custom fields.inventoryMode
- InventoryMode - Optional
Inventory mode specific to the line item only, valid for the entirequantity
of the line item. Set only if inventory mode should be different from theinventoryMode
specified on the OrderImportDraft.shippingDetails
- ItemShippingDetailsDraft - Optional
CustomLineItemImportDraft
A CustomLineItem is a generic item that can be added to the Cart, but is not bound to a Product. You can use it for discounts (negative money), vouchers, additional services or fees.
name
- LocalizedString
User-defined name of the CustomLineItem.quantity
- Number
The amount of a CustomLineItem in the Cart. Must be a positive integer.money
- Money
The cost to add to the cart. The amount can be negative.slug
- Stringstate
- Array of ItemState - OptionaltaxRate
- TaxRate - OptionaltaxCategory
- Reference to a TaxCategory - Optionalcustom
- CustomFieldsDraft - Optional
The Custom Fields.shippingDetails
- ItemShippingDetailsDraft - OptionalpriceMode
- CustomLineItemPriceMode - Optional
Specifies whether Cart Discounts with a matching CartDiscountCustomLineItemsTarget are applied to the custom line item:Standard
= yes,External
= no.
ProductVariantImportDraft
id
- Number - Optional
The sequential ID of the variant within the product. The variant with provided ID should exist in some existing product, so you also need to specify the productId if this property is set, or alternatively you can just specify SKU of the product variant.sku
- String - Optional The SKU of the existing variant.prices
- Array of PriceDraft - Optional
The Embedded Prices of the variant. The prices should not contain two prices for the same price scope (same currency, country, customer group, channel, valid from and valid until). If this property is defined, then it will override theprices
property from the original product variant, otherwiseprices
property from the original product variant would be copied in the resulting order.attributes
- Array of Attribute - Optional
If this property is defined, then it will override theattributes
property from the original product variant, otherwiseattributes
property from the original product variant would be copied in the resulting order.images
- Array of Image - Optional
If this property is defined, then it will override theimages
property from the original product variant, otherwiseimages
property from the original product variant would be copied in the resulting order.
ShippingInfoImportDraft
shippingMethodName
- Stringprice
- MoneyshippingRate
- ShippingRate
The shipping rate used to determine the price.taxRate
- TaxRate - OptionaltaxCategory
- ResourceIdentifier of a TaxCategory - OptionalshippingMethod
- ResourceIdentifier of a ShippingMethod - Optional
Not set if custom shipping method is used.deliveries
- Array of DeliveryDraft
Deliveries are compilations of information on how the articles are being delivered to the customers.discountedPrice
- DiscountedLineItemPrice - OptionalshippingMethodState
- ShippingMethodState
Indicates whether the ShippingMethod referenced is allowed for the cart or not.
Language, Price, and InventoryEntry filtering
Language filtering
To remove excess information, LocalizedStrings can be filtered based on the languages configured in the Store that is specified via the OrderImportDraft's store
field.
If the store has languages
set, then only localized values with the languages that are included in the store's languages
are kept.
If no matching language is found on a LocalizedString for some of the languages
specified in the Store, the next language specified in the languages
of the Project is used as a fallback. This ensures that required fields do not remain empty in the Order.
If an empty value is found on a LocalizedString for some of the languages
specified in the Store, the empty value will be imported for this language.
Price filtering
To remove excess of Prices, filtering is applied based on the distribution channels configured in the Store that is specified via the OrderImportDraft's store
field.
If the store has distributionChannels
set, then only the following Prices are kept:
- Prices with distribution channels that are in the store's
distributionChannels
- Prices without distribution channels
Likewise, if the Store has countries
set, only the following Prices are kept:
- prices with a country that is included in the Store's
countries
- prices without country
InventoryEntry filtering
To remove excess ProductVariantAvailabilities, filtering is applied based on the inventory supply channels configured in the Store that is specified via the OrderImportDraft's store
field.
If the store has supplyChannels
set, then only the following InventoryEntries are kept:
- InventoryEntries with supply channels that are in the store's
supplyChannels
- InventoryEntry without supply channels
Create an Order by Import
Creates directly an Order by importing it instead of creating it from a Cart. Each LineItem is referencing some existing product variant. You have 3 ways to specify a product reference:
productId
+variant.id
- this field combination will uniquely identify the product. In this casevariant.sku
would be initialized automatically in the resulting order.variant.sku
- SKU can also uniquely identify the product.productId
andvariant.id
would be filled automatically.productId
+variant.id
+variant.sku
- you can also provide all 3 fields. In this case SKU would be validated.
Endpoint: /{projectKey}/orders/import
Method: POST
OAuth 2.0 Scopes: manage_orders
:{projectKey}
Request Body Representation: OrderImportDraft
Response Representation: Order
Specific Error Codes:
Importing an Order produces the OrderImported Message.