Orders

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

Representations

Order

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
  • 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 if the Quote has expired (validTo check).
  • version - Number - Required
    The version of the Quote 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
  • 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: ReturnedBackInStock, ReturnedUnusable

ReturnPaymentState

Values of the ReturnPaymentState enumeration:

  • NonRefundable
  • Initial
  • Refunded
  • NotRefunded

Allowed initial states: Initial, NonRefundable
Allowed transitions: InitialRefunded, InitialNotRefunded

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

DeliveryDraft

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

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

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

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

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

Add Parcel

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

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.

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.

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

  • 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 an existing Delivery.

  • action - String - "setDeliveryCustomField"
  • deliveryId - 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 Parcel Custom Type

This action sets, overwrites, or removes any existing custom type and fields for an 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 an existing Parcel.

  • action - String - "setParcelCustomField"
  • parcelId - 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 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.

  • 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 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 a ParcelRemovedFromDelivery Message.

Remove Delivery

Removes a Delivery.

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

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