Documentation

Order Import

Order import helps to import your existing order without creating the carts.

To import an order into commercetools platform, 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 platform API.

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 or supply channels, they are used to enable Language filtering, Price filtering, and InventoryEntry filtering respectively.
    Additionally, suppose that the Store defines distribution (respectively, supply) channels. In this case, if some LineItem or CustomLineItem specifies distribution (respectively, supply) channels that are not defined on the Store, then the OrderImport gets rejected.
  • lineItems - Array of LineItemImportDraft - Optional
    If not given customLineItems must not be empty.
  • customLineItems - Array of CustomLineItemImportDraft - Optional
    If not given lineItems must not be empty.
  • totalPrice - Money - Required
  • taxedPrice - TaxedPrice - Optional
    Order Import does not support calculation of taxes. When setting the draft the taxedPrice is to be provided.
  • shippingAddress - Address - Optional
  • billingAddress - Address - Optional
  • customerGroup - 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 the Open state will be assigned by default.
  • shipmentState - ShipmentState - Optional
  • paymentState - PaymentState - Optional
  • shippingInfo - ShippingInfoImportDraft - Optional
    Set if the ShippingMethod is set.
  • completedAt - DateTime - Optional
  • custom - CustomFieldsDraft - Optional
    The custom fields.
  • inventoryMode - InventoryMode - Optional
    If not given the mode None will be assigned by default.
  • taxRoundingMode - RoundingMode - Optional
    If not given the tax rounding mode HalfEven will be assigned by default.
  • taxCalculationMode - TaxCalculationMode - Optional
    The default tax calculation mode is LineItemLevel.
  • origin - CartOrigin - Optional
    The default origin is Customer.
  • itemShippingAddresses - Array of Address - Optional
    Contains addresses for orders with multiple shipping addresses.

LineItemImportDraft

A line item import draft is a snapshot of a product variant at the time it was imported with the order.

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.

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 Price - Optional
    The prices of the variant. The prices should not contain two prices for the same price scope (same currency, country and customer group). If this property is defined, then it will override the prices property from the original product variant, otherwise prices 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 the attributes property from the original product variant, otherwise attributes 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 the images property from the original product variant, otherwise images property from the original product variant would be copied in the resulting order.

ShippingInfoImportDraft

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

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 unique identify the product. In this case variant.sku would be initialized automatically in the resulting order.
  • variant.sku - SKU can also unique identify the product. productId and variant.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 OrderImportedMessage.