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
  • lastModifiedAt - DateTime
  • 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).
  • lineItems - Array of LineItem
  • customLineItems - Array of CustomLineItem
  • totalPrice - Money
  • 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 - Set of ReturnInfo
  • discountCodes - Array of DiscountCodeInfo
  • 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

  • id - String - Required
    The unique id of the cart from which an order is created.
  • version - Number - Required
  • 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 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
    Identifies, which return tracking ID is connected to this particular return.
  • returnDate - DateTime

ReturnItem

ReturnItemDraft

The ReturnItemDraft needs to be given with the Add ReturnInfo update method.

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

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

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

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 keep an eye on 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
OAuth2 Scopes: view_orders:{projectKey}
Response Representation: Order

Get Order by OrderNumber

Endpoint: /{projectKey}/orders/order-number={orderNumber}
Method: GET
OAuth2 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.

Query Orders

Endpoint: /{projectKey}/orders
Method: GET
OAuth2 Scopes: view_orders:{projectKey}
Response Representation: PagedQueryResult with the results array of Order
Query Parameters:

Create Order from Cart

Creates an order from a Cart. The cart must have a shipping address set which is used for the tax calculation.

The cart data is copied to the created order.

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

Specific Error Codes:

This method produces the OrderCreated message.

Create Order by Import

See How to Create Order by Import

Update Order

Update Order by ID

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

  • version - Number - Required
    The expected version of the cart 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 by OrderNumber

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

  • version - Number - Required
    The expected version of the cart 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.

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

Update Actions
Please find below the individual update actions provided on this endpoint.


Change OrderState

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

This update action produces the OrderStateChanged message.

Change ShipmentState

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

This update action produces the 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 - Reference to a Channel
    Connection to 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
    The items to be returned.

This update action produces the ReturnInfoAdded message.

Set ReturnShipmentState

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

This update action produces the OrderReturnShipmentStateChanged message.

Set ReturnPaymentState

In order 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 the 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 the 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 the DeliveryAdded message and the ParcelAddedToDelivery message 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 - Address - Optional
    If not set an existing address is removed from the delivery.

This update action produces the DeliveryAddressSet message.

Add Parcel

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

This update action produces the 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.

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

Transitioning the state of a product produces the 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 action produces a OrderCustomerEmailSet 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 - Address - Optional

This action produces a 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 - Address - Optional

This action produces a 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.

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.

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.

Add Payment beta

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

Remove Payment beta

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.

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

This update action produces the DeliveryItemsUpdated message.

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 the ParcelRemovedFromDelivery message.

Remove Delivery

Removes a Delivery.

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

This update action produces the DeliveryRemoved message.

Set Parcel Measurements

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

This update action produces the ParcelMeasurementsUpdated message.

Set Parcel Tracking Data

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

This update action produces the ParcelTrackingDataUpdated message.

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 the 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 - Address
    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 - Address
    The address which is to replace the address with the key already present in the array

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.

Delete Order by ID

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

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

Delete Order by OrderNumber

Endpoint: /{projectKey}/orders/order-number={orderNumber}
Method: DELETE
OAuth2 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.