Orders

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

Representations

Order

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

OrderFromCartDraft

OrderState

Values of the OrderState enumeration:

ShipmentState

Values of the ShipmentState enumeration:

PaymentState

Values of the PaymentState enumeration:

ReturnShipmentState

Values of the ReturnShipmentState enumeration:

ReturnPaymentState

Values of the ReturnPaymentState enumeration:

SyncInfo

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

ReturnInfo

Stores information about returns connected to this order.

ReturnItem

ReturnItemDraft

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

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.

DeliveryItem

Parcel

A parcel stores the information about the appearance and the movement of a parcel

ParcelMeasurements

Information regarding the dimensions of a parcel.

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.

ItemState

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

PaymentInfo

Get Order by ID

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

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

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

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


Change OrderState

This update action produces the OrderStateChanged message.

Change ShipmentState

Change PaymentState

Update SyncInfo

Add ReturnInfo

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.

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

This update action produces the LineItemStateTransition message.

Change the state of CustomLineItem according to allowed transitions

This update action produces the CustomLineItemStateTransition message.

Import State for LineItems

These import of states does not follow any predefined rules and should be only used if no transitions are defined.

Import State for CustomLineItems

These import of states does not follow any predefined rules and should be only used if no transitions are defined.

Add Delivery

This update action produces the DeliveryAdded message and the ParcelAddedToDelivery message if the action contain a Parcel.

Add Parcel

In order to add a Parcel, there needs to be at least one Delivery with at least one DeliveryItem 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.

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.

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.

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.

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.

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.

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.

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.

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.

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

comments powered by Disqus