Documentation

Orders

An order can be created from a cart, usually after a checkout process has been completed. Orders can also be imported.

Representations

Order

  • id - String
    The unique ID of the order.

  • version - Number
    The current version of the order.

  • createdAt - DateTime

  • createdBy - CreatedBy BETA - Optional
    Present on resources created after 2019-02-01 except for events not tracked.

  • lastModifiedAt - DateTime

  • lastModifiedBy - LastModifiedBy BETA - Optional
    Present on resources updated after 2019-02-01 except for events not tracked.

  • completedAt - DateTime - Optional
    This field will only be present if it was set for Order Import

  • 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 across a project. Once it's set it cannot be changed.

  • customerId - String - Optional

  • customerEmail - String - Optional

  • anonymousId - String - Optional
    Identifies carts and orders belonging to an anonymous session (the customer has not signed up/in yet).

  • store - KeyReference to a Store - Optional

  • lineItems - Array of LineItem

  • customLineItems - Array of CustomLineItem

  • totalPrice - CentPrecisionMoney
    The total price of this line item. If the line item is discounted, then the totalPrice is the DiscountedLineItemPriceForQuantity multiplied by quantity. Otherwise the total price is the product price multiplied by the quantity. totalPrice may or may not include the taxes: it depends on the taxRate.includedInPrice property.

  • taxedPrice - TaxedPrice - Optional
    The taxes are calculated based on the shipping address.

  • shippingAddress - Address - Optional

  • billingAddress - Address - Optional

  • taxMode - TaxMode

  • taxRoundingMode - RoundingMode
    When calculating taxes for taxedPrice, the selected mode is used for rouding.

  • taxCalculationMode - TaxCalculationMode
    When calculating taxes for taxedPrice, the selected mode is used for calculating the price with LineItemLevel (horizontally) or UnitPriceLevel (vertically) calculation mode.

  • 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
    One of the four predefined OrderStates.

  • state - Reference to a State - Optional
    This reference can point to a state in a custom workflow.

  • shipmentState - ShipmentState - Optional

  • paymentState - PaymentState - Optional

  • shippingInfo - ShippingInfo - Optional
    Set if the ShippingMethod is set.

  • syncInfo - Set of SyncInfo

  • returnInfo - Array of ReturnInfo

  • discountCodes - Array of DiscountCodeInfo

  • refusedGifts - Array of References to CartDiscounts
    Automatically filled when a line item with LineItemMode GiftLineItem is removed from this order.

  • lastMessageSequenceNumber - Number
    The sequence number of the last order message produced by changes to this order. 0 means, that no messages were created yet.

  • cart - Reference to a Cart - Optional
    Set when this order was created from a cart. The cart will have the state Ordered.

  • custom - CustomFields - Optional

  • paymentInfo - PaymentInfo - Optional

  • locale - String conforming to IETF language tag - Optional

  • inventoryMode - InventoryMode

  • shippingRateInput - ShippingRateInput - Optional
    The shippingRateInput is used as an input to select a ShippingRatePriceTier.

  • origin - CartOrigin

  • itemShippingAddresses - Array of Address
    Contains addresses for orders with multiple shipping addresses.

    Order fields that can be used in query predicates:
    createdAt, lastModifiedAt, completedAt, orderNumber, customerId, customerEmail, anonymousId, country, totalPrice, taxedPrice, shippingAddress, billingAddress, customerGroup, orderState, shipmentState, paymentState, syncInfo, returnInfo, lineItems, customLineItems, cart, paymentInfo, state, locale, inventoryMode, shippingRateInput, shippingInfo.

OrderFromCartDraft

The field shippingAddress is required for the Cart from which an order is created.

  • cart - ResourceIdentifier - Required
    ResourceIdentifier of the Cart from which this order is created.
  • version - Number - Required
    The version of the cart from which an order is created.
  • 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 across a project. Once it's set it cannot be changed. For easier use on Get, Update and Delete actions we suggest assigning order numbers that match the regular expression [a-z0-9_\-]{2,36}.
  • paymentState - PaymentState - Optional
  • orderState - OrderState - Optional
    Order will be created with Open status by default.
  • state - Reference to a State - Optional
  • shipmentState - ShipmentState - Optional

OrderState

Values of the OrderState enumeration:

  • Open
  • Confirmed
  • Complete
  • Cancelled

ShipmentState

Values of the ShipmentState enumeration:

  • Shipped
  • Ready
  • Pending
  • Delayed
  • Partial
  • Backorder

PaymentState

Values of the PaymentState enumeration:

  • BalanceDue
  • Failed
  • Pending
  • CreditOwed
  • Paid

ReturnShipmentState

Values of the ReturnShipmentState enumeration:

  • Advised
  • Returned
  • BackInStock
  • Unusable

ReturnPaymentState

Values of the ReturnPaymentState enumeration:

  • NonRefundable
  • Initial
  • Refunded
  • NotRefunded

SyncInfo

Stores information about order synchronization activities (like export or import).

  • channel - Reference to a Channel
    Connection to a particular synchronization destination.
  • externalId - String - Optional
    Can be used to reference an external order instance, file etc.
  • syncedAt - DateTime

ReturnInfo

Stores information about returns connected to this order.

  • items - Array of ReturnItem
  • returnTrackingId - String - Optional Identifies, which return tracking ID is connected to this particular return.
  • returnDate - DateTime - Optional

ReturnItem

Entry for a returned LineItem as LineItemReturnItem or CustomLineItem as CustomLineItemReturnItem.

LineItemReturnItem

CustomLineItemReturnItem

ReturnItemDraft

Entry draft for a returned Line Item as LineItemReturnItemDraft or CustomLineItem as CustomLineItemReturnItemDraft.

At this point only Advised or Returned are allowed as ReturnShipmentState.
Item with Advised shipment state gets the NonRefundable ReturnPaymentState and item with Returned shipment state gets the Initial payment state.

ReturnInfoDraft

Entry draft for an array of returned Line Items or Custom Line Items as an array of ReturnItemDraft.

LineItemReturnItemDraft

  • quantity - Number - Required
  • lineItemId - String - Required
  • comment - String - Optional
  • shipmentState - ReturnShipmentState - Required
  • custom - CustomFields - Optional

CustomLineItemReturnItemDraft

  • quantity - Number - Required
  • customLineItemId - String - Required
  • comment - String - Optional
  • shipmentState - ReturnShipmentState - Required
  • custom - CustomFields - Optional

Delivery

Deliveries are compilations of information on how the articles are being shipped to the customers. A delivery can contain multiple items. All items in a delivery can be shipped with several parcels. To create a delivery, it is necessary to have a shipment method assigned to the order. A sample use case for a delivery object is to create a delivery note.

  • id - String
  • createdAt - DateTime
  • items - Array of DeliveryItem
    Items which are shipped in this delivery regardless their distribution over several parcels. Can also be specified individually for each Parcel.
  • parcels - Array of Parcel
  • address - Address - Optional
  • custom - CustomFields - Optional

DeliveryItem

Parcel

A parcel stores the information about the appearance, the movement and the content of a parcel.

ParcelDraft

ParcelMeasurements

Information regarding the dimensions of a parcel.

  • heightInMillimeter - Number
  • lengthInMillimeter - Number
  • widthInMillimeter - Number
  • weightInGram - Number

TrackingData

Tracking data is usually some info about the delivery (like a DHL tracking number) which is useful to track your delivery, view its status, etc.

  • trackingId - String - Optional
    The ID to track one parcel.
  • carrier - String - Optional
    The carrier that delivers the parcel.
  • provider - String - Optional The name of the provider which serves as facade to several carriers.
  • providerTransaction - String - Optional The id of the transaction with the provider.
  • isReturn - Boolean - Optional
    Flag to distinguish if the parcel is on the way to the customer (false) or on the way back (true).

ItemState

For item states we also need the information how much of the quantity is affected by this state.

PaymentInfo

Get Order

Get Order by ID

Endpoint: /{projectKey}/orders/{id}
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}
Response Representation: Order

Get Order in a Store by ID

Endpoint: /{projectKey}/in-store/key={storeKey}/orders/{id}
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}, view_orders:{projectKey}:{storeKey}
Response Representation: Order

Returns an order by its ID from a specific Store. The {storeKey} path parameter maps to a Store's key.

If the order exists in the commercetools project but does not have the store field, or the store field references a different store, this method returns a ResourceNotFound error.

Get Order by OrderNumber

Endpoint: /{projectKey}/orders/order-number={orderNumber}
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}
Response Representation: Order

In case the orderNumber does not match the regular expression [a-zA-Z0-9_\-]+, it should be provided in URL-encoded format.

Get Order in a Store by OrderNumber

Endpoint: /{projectKey}/in-store/key={storeKey}/orders/order-number={orderNumber}
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey} , view_orders:{projectKey}:{storeKey} Response Representation: Order

Returns an order by its order number from a specific Store. The {storeKey} path parameter maps to a Store's key.

If the order exists in the commercetools project but does not have the store field, or the store field references a different store, this method returns a ResourceNotFound error.

In case the orderNumber does not match the regular expression [a-zA-Z0-9_\-]+, it should be provided in URL-encoded format.

Query Orders

Your feedback will help us to improve the Order search experience. Join our commercetools user research program.

Query Orders

Endpoint: /{projectKey}/orders
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}
Response Representation: PagedQueryResult with results containing an array of Order
Query Parameters:

Query Orders in a Store

Endpoint: /{projectKey}/in-store/key={storeKey}/orders
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}, view_orders:{projectKey}:{storeKey}
Response Representation: PagedQueryResult with results containing an array of Order
Query Parameters:

Queries orders in a specific Store. The {storeKey} path parameter maps to a Store's key.

Create Order

Create Order from Cart

Creates an order from a Cart. The cart must have a shipping address set before creating an order. When using the Platform TaxMode, the shipping address is used for tax calculation.

Endpoint: /{projectKey}/orders
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey}
Request Representation: OrderFromCartDraft
Response Representation: Order

Specific Error Codes:

Messages:

Create Order from Cart in a Store

Creates an order from a Cart from a specific Store. The {storeKey} path parameter maps to a Store's key.

When using this endpoint the orders's store field is always set to the store specified in the path parameter.

The cart must have a shipping address set before creating an order. When using the Platform TaxMode, the shipping address is used for tax calculation.

Endpoint: /{projectKey}/in-store/key={storeKey}/orders
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey}, manage_orders:{projectKey}:{storeKey}
Request Representation: OrderFromCartDraft
Response Representation: Order

Specific Error Codes:

Messages:

Create Order by Import

See How to Create Order by Import

Update Order

Update Order by ID

Endpoint: /{projectKey}/orders/{id}
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey}
Response Representation: Order
Fields:

  • version - Number - Required
    The expected version of the order on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the order.

Update Order in a Store by ID

Endpoint: /{projectKey}/in-store/key={storeKey}/orders/{id}
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey}, manage_orders:{projectKey}:{storeKey}
Response Representation: Order
Fields:

  • version - Number - Required
    The expected version of the order on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the order.

Updates an order in the store specified by {storeKey}. The {storeKey} path parameter maps to a Store's key.

If the order exists in the commercetools project but does not have the store field, or the store field references a different store, this method returns a ResourceNotFound error.

Update Order by OrderNumber

Endpoint: /{projectKey}/orders/order-number={orderNumber}
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey}
Response Representation: Order

  • version - Number - Required
    The expected version of the order on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the order.

Update Order in a Store by OrderNumber

Endpoint: /{projectKey}/in-store/key={storeKey}/orders/order-number={orderNumber}
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey}, manage_orders:{projectKey}:{storeKey}
Response Representation: Order

  • version - Number - Required
    The expected version of the order on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the order.

Updates an order in the store specified by {storeKey}. The {storeKey} path parameter maps to a Store's key.

If the order exists in the commercetools project but does not have the store field, or the store field references a different store, this method returns a ResourceNotFound error.

In case the orderNumber does not match the regular expression [a-zA-Z0-9_\-]+, it should be provided in URL-encoded format.

Update actions

Change OrderState
Change ShipmentState
Change PaymentState
Update SyncInfo
Add ReturnInfo
Set ReturnInfo
Set ReturnShipmentState
Set ReturnPaymentState
Change the state of LineItem according to allowed transitions
Change the state of CustomLineItem according to allowed transitions
Import State for LineItems
Import State for CustomLineItems
Add Delivery
Set Delivery Address
Add Parcel
Set Order Number
Transition State
Set Customer Email
Set Customer Id
Set Shipping Address
Set Billing Address
Set Custom Type
Set CustomField
Set Shipping Address Custom Type
Set Shipping Address CustomField
Set Billing Address Custom Type
Set Billing Address CustomField
Set ItemShipping Address Custom Type
Set ItemShipping Address CustomField
Set Delivery Address Custom Type
Set Delivery Address CustomField
Set Delivery Custom Type
Set Delivery CustomField
Set Parcel Custom Type
Set Parcel CustomField
Set LineItem Custom Type
Set LineItem CustomField
Set CustomLineItem Custom Type
Set CustomLineItem CustomField
Set ReturnItem Custom Type
Set ReturnItem CustomField
Add Payment
Remove Payment
Set Locale
Set Delivery Items
Remove Parcel from Delivery
Remove Delivery
Set Parcel Measurements
Set Parcel Tracking Data
Set Parcel Items
Set LineItemShippingDetails
Set CustomLineItemShippingDetails
Add ItemShippingAddress
Remove ItemShippingAddress
Update ItemShippingAddress
Set Store

Change OrderState

  • action - String - "changeOrderState"
  • orderState - OrderState - Required

This update action produces an OrderStateChangedMessage.

Change ShipmentState

  • action - String - "changeShipmentState"
  • shipmentState - ShipmentState - Required

This update action produces an OrderShipmentStateChangedMessage.

Change PaymentState

  • action - String - "changePaymentState"
  • paymentState - PaymentState - Required

Changing the payment state of the order produces the OrderPaymentStateChangedMessage.

Update SyncInfo

  • action - String - "updateSyncInfo"
  • channel - ResourceIdentifier to a Channel
    Connection to a particular synchronization destination.
  • externalId - String - Optional
    Can be used to reference an external order instance, file etc.
  • syncedAt - DateTime - Optional If not provided, then current date would be used

Add ReturnInfo

  • action - String - "addReturnInfo" - Required
  • returnDate - DateTime - Optional
  • returnTrackingId - String - Optional
    Identifies which return tracking ID is connected to this particular return.
  • items - Array of ReturnItemDraft - Required
    Items to be returned.

This update action produces a ReturnInfoAddedMessage.

Set ReturnInfo

  • action - String - "setReturnInfo"
  • items - Array of ReturnInfoDraft - Optional
    Items to be returned.

This update action produces the ReturnInfoSetMessage.

Set ReturnShipmentState

To set a ReturnShipmentState, there needs to be at least one ReturnInfo with at least one ReturnItem created before.

This update action produces an OrderReturnShipmentStateChangedMessage.

Set ReturnPaymentState

To set a ReturnPaymentState, there needs to be at least one ReturnInfo with at least one ReturnItem created before.

Change the state of LineItem according to allowed transitions

  • action - String - "transitionLineItemState"
  • lineItemId - String
  • quantity - Number
  • fromState - Reference to a State
  • toState - Reference to a State
  • actualTransitionDate - DateTime - Optional

This update action produces a LineItemStateTransitionMessage.

Change the state of CustomLineItem according to allowed transitions

  • action - String - "transitionCustomLineItemState"
  • customLineItemId - String
  • quantity - Number
  • fromState - Reference to a State
  • toState - Reference to a State
  • actualTransitionDate - DateTime - Optional

This update action produces a CustomLineItemStateTransitionMessage.

Import State for LineItems

The import of states does not follow any predefined rules and should be only used if no transitions are defined. The quantity in the ItemStates must match the sum of all LineItems states' quantities.

  • action - String - "importLineItemState"
  • lineItemId - String
  • state - Array of ItemState

Import State for CustomLineItems

The import of states does not follow any predefined rules and should be only used if no transitions are defined. The quantity in the ItemStates must match the sum of all CustomLineItem states' quantities.

  • action - String - "importCustomLineItemState"
  • customLineItemId - String
  • state - Array of ItemState

Add Delivery

A Delivery can only be added to an Order if its shippingInfo exists.

This update action produces a DeliveryAddedMessage and the ParcelAddedToDeliveryMessage if the action contains a Parcel.

Set Delivery Address

Sets the address value on an existing Delivery.

  • action - String - "setDeliveryAddress"
  • deliveryId - String The ID of the Delivery which should be updated.
  • address - AddressDraft - Optional
    If not set an existing address is removed from the delivery.

This update action produces a DeliveryAddressSetMessage.

Add Parcel

To add a Parcel, there needs to be at least one Delivery created before.

This update action produces a ParcelAddedToDeliveryMessage.

Set Order Number

Sets a string that uniquely identifies an order. It can be used to create more human-readable (in contrast to ID) identifier for the order.

  • action - String - "setOrderNumber"
  • orderNumber - String - Optional
    It should be unique across a project. Once it's set, it cannot be changed.

Transition State

Transition to a new state. If there is no state yet, the new state must be an initial state. If the existing state has transitions set, there must be a direct transition to the new state. If transitions is not set, no validation is performed. These validations can be turned off by setting the force parameter to true.

  • action - String - "transitionState"
  • state - Reference to a State
  • force - Boolean - Optional - Defaults to false

This update action produces an OrderStateTransitionMessage.

Set Customer Email

This action sets, overwrites, or removes any existing value for customerEmail.
This action does not change the customer email on the Cart the order has been created from.

  • action - String - "setCustomerEmail"
  • email - String - Optional

This update action produces an OrderCustomerEmailSetMessage.

Set Customer Id

Relates a Customer to the order. In case the customer belongs to a CustomerGroup the order's field customerGroup would be updated automatically. When applied, no prices or discounts will be re-calculated on the order.

  • action - String - "setCustomerId"
  • customerId - String - Optional
    If set, a Customer with the given ID must exist in the project.

This update action produces an OrderCustomerSetMessage.

Set Shipping Address

This action sets, overwrites, or removes any existing value for shippingAddress.
Changing the shipping address does not recalculate the cart. The taxes might not fit to the shipping address anymore.
This action does not change the shipping address on the Cart the order has been created from.

  • action - String - "setShippingAddress"
  • address - AddressDraft - Optional

This update action produces an OrderShippingAddressSetMessage.

Set Billing Address

This action sets, overwrites, or removes any existing value for billingAddress.
This action does not change the billing address on the Cart the order has been created from.

  • action - String - "setBillingAddress"
  • address - AddressDraft - Optional

This update action produces an OrderBillingAddressSetMessage.

Set Custom Type

This action sets, overwrites, or removes any existing custom type and fields for an existing order.

Set CustomField

This action sets, overwrites, or removes any existing custom field for an existing order.

  • action - String - "setCustomField"
  • name - String - Required
  • value - Value - Optional
    If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, set the value of the field defined by the name.

Set Shipping Address Custom Type

This action sets, overwrites, or removes any existing custom type and fields for an existing shippingAddress.

  • action - String - "setShippingAddressCustomType"
  • type - ResourceIdentifier to a Type - Optional
    If set, the custom type is set to this new value.
    If absent, the custom type and any existing custom fields are removed.
  • fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
    If set, the custom fields are set to this new value.

Set Shipping Address CustomField

This action sets, overwrites, or removes any existing custom field for an existing shippingAddress.

  • action - String - "setShippingAddressCustomField"
  • name - String - Required
    The name of the Custom Field to set
  • value - Value - Optional
    Specifies the format of the value of the Custom Field defined by name. If value is absent or null, the field specified by name, if it exists, is removed. Trying to remove a field that does not exist will fail with an InvalidOperation error.

Set Billing Address Custom Type

This action sets, overwrites, or removes any existing custom type and fields for an existing billingAddress.

  • action - String - "setBillingAddressCustomType"
  • type - ResourceIdentifier to a Type - Optional
    If set, the custom type is set to this new value. If absent, the custom type and any existing custom fields are removed.
  • fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
    If set, the custom fields are set to this new value.

Set Billing Address CustomField

This action sets, overwrites, or removes any existing custom field for an existing billingAddress.

  • action - String - "setBillingAddressCustomField"
  • name - String - Required
    The name of the Custom Field to set
  • value - Value - Optional
    Specifies the format of the value of the Custom Field defined by name. If value is absent or null, the field specified by name, if it exists, is removed. Trying to remove a field that does not exist will fail with an InvalidOperation error.

Set ItemShipping Address Custom Type

This action sets, overwrites, or removes any existing custom type and fields for an existing itemShippingAddress.

  • action - String - "setItemShippingAddressCustomType"
  • addressKey - String - Required
  • type - ResourceIdentifier to a Type - Optional
    If set, the custom type is set to this new value.
    If absent, the custom type and any existing custom fields are removed.
  • fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
    If set, the custom fields are set to this new value.

Set ItemShipping Address CustomField

This action sets, overwrites, or removes any existing custom field for an existing itemShippingAddress.

  • action - String - "setItemShippingAddressCustomField"
  • addressKey - String - Required
  • name - String - Required
    The name of the Custom Field to set
  • value - Value - Optional
    Specifies the format of the value of the Custom Field defined by name. If value is absent or null, the field specified by name, if it exists, is removed. Trying to remove a field that does not exist will fail with an InvalidOperation error.

Set Delivery Address Custom Type

This action sets, overwrites, or removes any existing custom type and fields for an existing address in a Delivery.

  • action - String - "setDeliveryAddressCustomType"
  • deliveryId - String - Required
  • type - ResourceIdentifier to a Type - Optional
    If set, the custom type is set to this new value.
    If absent, the custom type and any existing custom fields are removed.
  • fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
    If set, the custom fields are set to this new value.

Set Delivery Address CustomField

This action sets, overwrites, or removes any existing custom field for an existing address in a Delivery.

  • action - String - "setDeliveryAddressCustomField"
  • deliveryId - String - Required
  • name - String - Required
    The name of the Custom Field to set
  • value - Value - Optional
    Specifies the format of the value of the Custom Field defined by name. If value is absent or null, the field specified by name, if it exists, is removed. Trying to remove a field that does not exist will fail with an InvalidOperation error.

Set Delivery Custom Type

This action sets, overwrites, or removes any existing custom type and fields for a existing Delivery.

  • action - String - "setDeliveryCustomType"
  • deliveryId - String - Required
  • type - ResourceIdentifier to a Type - Optional
    If set, the custom type is set to this new value.
    If absent, the custom type and any existing custom fields are removed.
  • fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
    If set, the custom fields are set to this new value.

Set Delivery CustomField

This action sets, overwrites, or removes any existing custom field for a existing Delivery.

  • action - String - "setDeliveryCustomField"
  • deliveryId - String - Required
  • name - String - Required
    The name of the Custom Field to set
  • value - Value - Optional
    Specifies the format of the value of the Custom Field defined by name. If value is absent or null, the field specified by name, if it exists, is removed. Trying to remove a field that does not exist will fail with an InvalidOperation error.

Set Parcel Custom Type

This action sets, overwrites, or removes any existing custom type and fields for a existing Parcel.

  • action - String - "setParcelCustomType"
  • parcelId - String - Required
  • type - ResourceIdentifier to a Type - Optional
    If set, the custom type is set to this new value.
    If absent, the custom type and any existing custom fields are removed.
  • fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
    If set, the custom fields are set to this new value.

Set Parcel CustomField

This action sets, overwrites, or removes any existing custom field for a existing Parcel.

  • action - String - "setParcelCustomField"
  • parcelId - String - Required
  • name - String - Required
    The name of the Custom Field to set
  • value - Value - Optional
    Specifies the format of the value of the Custom Field defined by name. If value is absent or null, the field specified by name, if it exists, is removed. Trying to remove a field that does not exist will fail with an InvalidOperation error.

Set LineItem Custom Type

This action sets, overwrites, or removes the existing custom type and fields for an existing order LineItem.

  • action - String - "setLineItemCustomType"
  • type - ResourceIdentifier to a Type - Optional
    If set, the custom type is set to this new value.
    If absent, the custom type and any existing CustomFields are removed at the same time.
  • lineItemId - String
  • fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
    If set, the custom fields are set to this new value.

Set LineItem CustomField

This action sets, overwrites, or removes any existing custom field for an existing order LineItem.

  • action - String - "setLineItemCustomField"
  • lineItemId - String
  • name - String - Required
  • value - Value - Optional
    If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, set the value of the field defined by the name.

Set CustomLineItem Custom Type

This action sets, overwrites, or removes the existing custom type and fields for an existing order CustomLineItem.

  • action - String - "setCustomLineItemCustomType"
  • type - ResourceIdentifier to a Type - Optional
    If set, the custom type is set to this new value.
    If absent, the custom type and any existing CustomFields are removed at the same time.
  • customLineItemId - String
  • fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
    If set, the custom fields are set to this new value.

Set CustomLineItem CustomField

This action sets, overwrites, or removes any existing custom field for an existing order CustomLineItem.

  • action - String - "setCustomLineItemCustomField"
  • customLineItemId - String
  • name - String - Required
  • value - Value - Optional
    If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, set the value of the field defined by the name.

Set ReturnItem Custom Type

This action sets, overwrites, or removes the existing custom type and fields for an existing order ReturnItem.

  • action - String - "setReturnItemCustomType"
  • type - ResourceIdentifier to a Type - Optional
    If set, the custom type is set to this new value.
    If absent, the custom type and any existing CustomFields are removed at the same time.
  • returnItemId - String
  • fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
    If set, the custom fields are set to this new value.

Set ReturnItem CustomField

This action sets, overwrites, or removes any existing custom field for an existing order ReturnItem.

  • action - String - "setReturnItemCustomField"
  • returnItemId - String
  • name - String - Required
  • value - Value - Optional
    If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, set the value of the field defined by the name.

Add Payment

This action adds a payment to the PaymentInfo. The payment must not be assigned to another Order or active Cart yet.

Remove Payment

This action removes a payment from the PaymentInfo.

Set Locale

Sets the locale. Must be one of the languages supported for this Project.

  • action - String - "setLocale"
  • locale - String conforming to IETF language tag - Optional

Set Delivery Items

Updates the delivery items of a Delivery.

  • action - String - "setDeliveryItems"
  • deliveryId - String - ID of the Delivery for which the items should be set
  • items - Array of DeliveryItem

This update action produces a DeliveryItemsUpdatedMessage.

Remove Parcel from Delivery

Removes a parcel in a Delivery.

  • action - String - "removeParcelFromDelivery"
  • parcelId - String - ID of the Parcel which shall be removed

This update action produces a ParcelRemovedFromDeliveryMessage.

Remove Delivery

Removes a Delivery.

  • action - String - "removeDelivery"
  • deliveryId - String - ID of the Delivery which shall be removed

This update action produces a DeliveryRemovedMessage.

Set Parcel Measurements

  • action - String - "setParcelMeasurements"
  • parcelId - String - ID of the Parcel which shall be updated
  • measurements - ParcelMeasurements - Optional

This update action produces a ParcelMeasurementsUpdatedMessage.

Set Parcel Tracking Data

  • action - String - "setParcelTrackingData"
  • parcelId - String - ID of the Parcel which shall be updated
  • trackingData - TrackingData - Optional

This update action produces a ParcelTrackingDataUpdatedMessage.

Set Parcel Items

Updates the items of a Parcel.

  • action - String - "setParcelItems"
  • parcelId - String - ID of the Parcel which shall be updated
  • items - Array of DeliveryItem

This update action produces a ParcelItemsUpdatedMessage.

Set LineItemShippingDetails

Sets the ItemShippingDetails for a line item.

  • action - String - "setLineItemShippingDetails"
  • lineItemId - String
    The ID of the line item that is to be updated.
  • shippingDetails - ItemShippingDetailsDraft - Optional
    The new shipping details for the line item.

Set CustomLineItemShippingDetails

Sets the ItemShippingDetails for a custom line item.

  • action - String - "setCustomLineItemShippingDetails"
  • customLineItemId - String
    The ID of the custom line item that is to be updated.
  • shippingDetails - ItemShippingDetailsDraft - Optional
    The new shipping details for the custom line item.

Add ItemShippingAddress

Add an address to the itemShippingAddresses array.

  • action - String - "addItemShippingAddress"
  • address - AddressDraft
    The address must have a key that is unique in this cart/order.

Remove ItemShippingAddress

Removes an address from the itemShippingAddresses array. An address can only be removed if it is not referenced in any ItemShippingTarget.

  • action - String - "removeItemShippingAddress"
  • addressKey - String
    The key of the address that is to be removed

Update ItemShippingAddress

Updates an address in the itemShippingAddresses array.

  • action - String - "updateItemShippingAddress"
  • address - AddressDraft
    The address which is to replace the address with the key already present in the array

Set Store

Updates the Store the order is assigned to. It should be used to migrate existing orders to a newly introduced store. Therefore no validations are performed (such as that the customer is allowed to create orders in the store).

This update action produces an OrderStoreSetMessage.

Overview of update actions for Cart, Order and OrderEdit

Update ActionCartdirect OrderOrderEdit
setKey✓
setCustomerEmail✓✓✓
setShippingAddress✓✓✓
setBillingAddress✓✓✓
setCountry✓-✓
recalculate✓--
setShippingMethod✓-✓
setCustomShippingMethod✓-✓
addDiscountCode✓-✓
removeDiscountCode✓-✓
setCustomerId✓✓✓
setAnonymousId✓--
setCustomerGroup✓-✓
setCustomType✓✓✓
setCustomField✓✓✓
addPayment✓✓✓
removePayment✓✓✓
setShippingMethodTaxRate✓-✓
setShippingMethodTaxAmount✓-✓
setCartTotalTax✓--
setOrderTotalTax--✓
changeTaxMode✓-✓
setLocale✓✓✓
changeTaxRoundingMode✓-✓
setShippingRateInput✓-✓
changeTaxCalculationMode✓-✓
addShoppingList✓-✓
setDeleteDaysAfterLastModification✓--
addItemShippingAddress✓✓✓
removeItemShippingAddress✓✓✓
updateItemShippingAddress✓✓✓
setShippingAddressAndShippingMethod--✓
setShippingAddressAndCustomShippingMethod--✓
LineItem update actions
applyDeltaToLineItemShippingDetailsTargets✓--
setLineItemShippingDetails✓✓✓
addLineItem✓-✓
removeLineItem✓-✓
changeLineItemQuantity✓-✓
setLineItemCustomType✓✓✓
setLineItemCustomField✓✓✓
setShippingAddressCustomType✓✓✓
setShippingAddressCustomField✓✓✓
setBillingAddressCustomType✓✓✓
setBillingAddressCustomField✓✓✓
setItemShippingAddressCustomType✓✓✓
setItemShippingAddressCustomField✓✓✓
setDeliveryAddressCustomType✓✓✓
setDeliveryAddressCustomField✓✓✓
setDeliveryCustomType-✓✓
setDeliveryCustomField-✓✓
setParcelCustomType-✓✓
setParcelCustomField-✓✓
setReturnItemCustomType-✓✓
setReturnItemCustomField-✓✓
setLineItemTaxRate✓-✓
setLineItemTaxAmount✓-✓
setLineItemTotalPrice✓-✓
setLineItemPrice✓-✓
setLineItemDistributionChannel✓-✓
CustomLineItem update actions
applyDeltaToCustomLineItemShippingDetailsTargets✓--
setCustomLineItemShippingDetails✓--
addCustomLineItem✓-✓
removeCustomLineItem✓-✓
setCustomLineItemCustomType✓✓✓
setCustomLineItemCustomField✓✓✓
setCustomLineItemTaxAmount✓-✓
setCustomLineItemTaxRate✓-✓
changeCustomLineItemQuantity✓-✓
changeCustomLineItemMoney✓-✓

Delete Order

Only orders created for testing should be deleted.

If a DiscountCode with a maxApplications or maxApplicationsPerCustomer limit has been applied to the order, the deleted order will still count towards that limit.

Deleting an order produces the OrderDeletedMessage.

Delete Order by ID

Endpoint: /{projectKey}/orders/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_orders:{projectKey}
Query Parameters:

  • version - Number - Required
  • dataErasure - Boolean - Optional, defaults to false

Delete Order in a Store by ID

Endpoint: /{projectKey}/in-store/key={storeKey}/orders/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_orders:{projectKey}, manage_orders:{projectKey}:{storeKey}
Query Parameters:

  • version - Number - Required
  • dataErasure - Boolean - Optional, defaults to false

Removes an order in the store specified by {storeKey}. The {storeKey} path parameter maps to a Store's key.

If the order exists in the commercetools project but does not have the store field, or the store field references a different store, this method returns a ResourceNotFound error.

Delete Order by OrderNumber

Endpoint: /{projectKey}/orders/order-number={orderNumber}
Method: DELETE
OAuth 2.0 Scopes: manage_orders:{projectKey}
Query Parameters:

  • version - Number - Required
  • dataErasure - Boolean - Optional, defaults to false

In case the orderNumber does not match the regular expression [a-zA-Z0-9_\-]+, it should be provided in URL-encoded format.

Delete Order in a Store by OrderNumber

Endpoint: /{projectKey}/in-store/key={storeKey}/orders/order-number={orderNumber}
Method: DELETE
OAuth 2.0 Scopes: manage_orders:{projectKey}, manage_orders:{projectKey}:{storeKey}
Query Parameters:

  • version - Number - Required
  • dataErasure - Boolean - Optional, defaults to false

In case the orderNumber does not match the regular expression [a-zA-Z0-9_\-]+, it should be provided in URL-encoded format.

Removes an order in the store specified by {storeKey}. The {storeKey} path parameter maps to a Store's key.

If the order exists in the commercetools project but does not have the store field, or the store field references a different store, this method returns a ResourceNotFound error.