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

  • businessUnit- BusinessUnitKeyReference - BETA - Optional
    The Business Unit the Order is assigned to.

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

  • taxedShippingPrice - TaxedPrice - Optional
    Sum of taxedPrice of ShippingInfo across all Shipping Methods. For Platform TaxMode, it is set automatically only if shipping address is set or Shipping Method is added to the Cart.

  • shippingAddress - Address - Optional

  • billingAddress - Address - Optional

  • shippingMode - ShippingMode
    Indicates whether one or multiple Shipping Methods are added to the Cart. The default mode is Single.

  • shippingKey - String - Optional
    User-defined unique identifier of the Shipping Method with Single ShippingMode.

  • shippingCustomFields - CustomFields - Optional
    Custom Fields of the Shipping Method for Single ShippingMode.

  • shipping - Array of Shipping
    Holds all shipping-related information per Shipping Method for Multi ShippingMode. It is updated automatically after the Shipping Method is added.

  • taxMode - TaxMode

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

  • 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-2External link icon. 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

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

  • discountCodes - Array of DiscountCodeInfo
    Discount codes applied to the cart or the order. Either discountCodes or directDiscounts can be set, but not both at the same time.

  • directDiscounts - Array of DirectDiscount
    Discounts added through the Set DirectDiscount update action.

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

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

  • quote - Reference to a Quote - Optional
    Set when the order was created from a quote.

  • custom - CustomFields - Optional

  • paymentInfo - PaymentInfo - Optional

  • locale - String conforming to IETF language tagExternal link icon - 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, purchaseOrderNumber, 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
    Unique identifier of 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}.
  • purchaseOrderNumber - String - Optional
    Identifier for the purchase order, usually in a B2B context. The Purchase Order Number is typically entered by the Buyer and can also be used with Quotes.
  • paymentState - PaymentState - Optional
  • orderState - OrderState - Optional
    Order will be created with Open status by default.
  • state - Reference to a State - Optional
  • shipmentState - ShipmentState - Optional
  • custom - CustomFieldsDraft - Optional
    CustomFields for the Order. The Custom Field type must match the type of the Custom Fields in the referenced Cart.
    • If specified, the Custom Fields are merged with the Custom Fields on the referenced Cart and added to the Order.
    • If empty, the Custom Fields on the referenced Cart are added to the Order automatically.

OrderFromQuoteDraft

  • quote - ResourceIdentifier - Required
    ResourceIdentifier of the Quote from which this order is created. If the Quote has QuoteState in Accepted, Declined or Withdrawn then the order creation will fail. The creation will also fail if the Quote has expired (validTo check).
  • version - Number - Required
    The version of the Quote from which an order is created.
  • quoteStateToAccepted - Boolean - Optional (default: false)
    If true, the quoteState of the referenced Quote will be set to Accepted.
  • 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
  • Delivered
  • 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

Allowed initial states: Advised, Returned
Allowed transitions: Returned → BackInStock, Returned → Unusable

ReturnPaymentState

Values of the ReturnPaymentState enumeration:

  • NonRefundable
  • Initial
  • Refunded
  • NotRefunded

Allowed initial states: Initial, NonRefundable
Allowed transitions: Initial → Refunded, Initial → 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
  • key - String
    User-defined unique identifier of the Delivery.
  • 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

DeliveryDraft

  • key - String - Optional
    User-defined unique identifier of the Delivery.
  • items - Array of DeliveryItem - Optional
    Items which are shipped in this delivery regardless their distribution over several parcels. Can also be specified individually for each Parcel.
  • parcels - Array of ParcelDraft - Optional
  • address - AddressDraft - Optional
  • custom - CustomFieldsDraft - Optional

DeliveryItem

Parcel

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

  • id - String - Unique id of the parcel
  • key - String - User-defined unique identifier of the parcel - Optional
  • createdAt - DateTime
  • measurements - ParcelMeasurements - Optional
  • trackingData - TrackingData - Optional
  • items - Array of DeliveryItem - Optional
    The delivery items contained in this parcel.
  • custom - CustomFields - Optional

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

Information icon

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

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 in Store from Cart

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

Creates an order from a Quote.

Endpoint: /{projectKey}/orders/quotes
Method: POST
OAuth 2.0 Scopes: manage_quotes:{projectKey}
Request Representation: OrderFromQuoteDraft
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 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 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
Set Purchase 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 OrderStateChanged Message.

Change ShipmentState

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

This update action produces an OrderShipmentStateChanged Message.

Change PaymentState

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

Changing the Payment State of the Order produces the OrderPaymentStateChanged Message.

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 ReturnInfoAdded Message.

Set ReturnInfo

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

This update action produces the ReturnInfoSet Message.

Set ReturnShipmentState

To set a ReturnShipmentState, the Order needs to have the ReturnInfo set with at least one ReturnItem.

This update action produces an OrderReturnShipmentStateChanged Message.

Set ReturnPaymentState

To set a ReturnPaymentState, the Order needs to have the ReturnInfo set with at least one ReturnItem.

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 LineItemStateTransition Message.

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 CustomLineItemStateTransition Message.

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 DeliveryAdded Message. If the update action contains a Parcel, the action also produces a ParcelAddedToDelivery Message.

Set Delivery Address

Sets the address value on an existing Delivery. Either deliveryId or deliveryKey is required.

  • action - String - "setDeliveryAddress"
  • deliveryId - String
    ID of the Delivery to update.
  • deliveryKey - String
    User-defined unique identifier of the Delivery to update.
  • address - AddressDraft - Optional
    If not set an existing address is removed from the delivery.

This update action produces a DeliveryAddressSet Message.

Add Parcel

To add a Parcel, there needs to be at least one Delivery created before. Either deliveryId or deliveryKey is required.

  • action - String - "addParcelToDelivery"
  • deliveryId - String
    ID of the Delivery to which the parcel should be added.
  • deliveryKey - String
    User-defined unique identifier of the Delivery to which the parcel should be added.
  • parcelKey - String - Key of the Parcel which shall be updated - Optional
  • measurements - ParcelMeasurements - Optional
  • trackingData - TrackingData - Optional
  • items - Array of DeliveryItem - Optional

This update action produces a ParcelAddedToDelivery Message.

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.

Set Purchase Order Number

Sets an identifier for a purchase order, usually in a B2B context. The Purchase Order Number is typically generated by the Buyer and can also be used with Quotes.

  • action - String - "setPurchaseOrderNumber"
  • purchaseOrderNumber - String - Optional

This update action produces a PurchaseOrderNumberSet Message.

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 OrderStateTransition Message.

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 OrderCustomerEmailSet Message.

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 OrderCustomerSet Message.

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 OrderShippingAddressSet Message.

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 OrderBillingAddressSet Message.

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 - CustomFieldValue - 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 - CustomFieldValue - 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 - CustomFieldValue - 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 - CustomFieldValue - 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. Either deliveryId or deliveryKey is required.

  • action - String - "setDeliveryAddressCustomType"
  • deliveryId - String
    ID of the Delivery to update.
  • deliveryKey - String
    User-defined unique identifier of the Delivery to update.
  • 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. Either deliveryId or deliveryKey is required.

  • action - String - "setDeliveryAddressCustomField"
  • deliveryId - String
    ID of the Delivery to update.
  • deliveryKey - String
    User-defined unique identifier of the Delivery to update.
  • name - String - Required
    The name of the Custom Field to set
  • value - CustomFieldValue - 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 an existing Delivery. Either deliveryId or deliveryKey is required.

  • action - String - "setDeliveryCustomType"
  • deliveryId - String
    ID of the Delivery to update.
  • deliveryKey - String
    User-defined unique identifier of the Delivery to update.
  • 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 an existing Delivery. Either deliveryId or deliveryKey is required.

  • action - String - "setDeliveryCustomField"
  • deliveryId - String
    ID of the Delivery to update.
  • deliveryKey - String
    User-defined unique identifier of the Delivery to update.
  • name - String - Required
    The name of the Custom Field to set
  • value - CustomFieldValue - 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 an existing Parcel.

  • action - String - "setParcelCustomType"
  • parcelId - String - Either parcelId or parcelKey is required
  • parcelKey - String - Either parcelId or parcelKey is 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 an existing Parcel.

  • action - String - "setParcelCustomField"
  • parcelId - String - Either parcelId or parcelKey is required
  • parcelKey - String - Either parcelId or parcelKey is required
  • name - String - Required
    The name of the Custom Field to set
  • value - CustomFieldValue - 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 - CustomFieldValue - 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 - CustomFieldValue - 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 - CustomFieldValue - 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.

Set Delivery Items

Updates the delivery items of a Delivery. Either deliveryId or deliveryKey is required.

  • action - String - "setDeliveryItems"
  • deliveryId - String
    ID of the Delivery to update.
  • deliveryKey - String
    User-defined unique identifier of the Delivery to update.
  • items - Array of DeliveryItem

This update action produces a DeliveryItemsUpdated Message.

Remove Parcel from Delivery

Removes a parcel in a Delivery.

  • action - String - "removeParcelFromDelivery"
  • parcelId - String - Either parcelId or parcelKey is required
    ID of the Parcel which shall be updated.
  • parcelKey - String - Either parcelId or parcelKey is required
    Key of the Parcel which shall be updated. This update action produces a ParcelRemovedFromDelivery Message.

Remove Delivery

Removes a Delivery. Either deliveryId or deliveryKey is required.

  • action - String - "removeDelivery"
  • deliveryId - String
    ID of the Delivery to remove.
  • deliveryKey - String
    User-defined unique identifier of the Delivery to remove.

This update action produces a DeliveryRemoved Message.

Set Parcel Measurements

  • action - String - "setParcelMeasurements"
  • parcelId - String - Either parcelId or parcelKey is required
    ID of the Parcel which shall be updated.
  • parcelKey - String - Either parcelId or parcelKey is required
    Key of the Parcel which shall be updated.- measurements - ParcelMeasurements - Optional

This update action produces a ParcelMeasurementsUpdated Message.

Set Parcel Tracking Data

  • action - String - "setParcelTrackingData"
  • parcelId - String - Either parcelId or parcelKey is required
    ID of the Parcel which shall be updated.
  • parcelKey - String - Either parcelId or parcelKey is required
    Key of the Parcel which shall be updated.- trackingData - TrackingData - Optional

This update action produces a ParcelTrackingDataUpdated Message.

Set Parcel Items

Updates the items of a Parcel.

  • action - String - "setParcelItems"
  • parcelId - String - Either parcelId or parcelKey is required
    ID of the Parcel which shall be updated.
  • parcelKey - String - Either parcelId or parcelKey is required
    Key of the Parcel which shall be updated.- items - Array of DeliveryItem

This update action produces a ParcelItemsUpdated Message.

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 OrderStoreSet Message.

Overview of update actions for Cart, Order and OrderEdit

Update actionCartOrderOrder Edit
setKey✓-✓
setCustomerEmail✓✓✓
setPurchaseOrderNumber-✓✓
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✓-✓
changeCustomLineItemPriceMode✓--

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 OrderDeleted Message.

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 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 project but does not have the store field, or the store field references a different store, this method returns a ResourceNotFound error.