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
- DateTimecreatedBy
- CreatedBy BETA - Optional
Present on resources created after 2019-02-01 except for events not tracked.lastModifiedAt
- DateTimelastModifiedBy
- 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 ImportorderNumber
- 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 - OptionalcustomerEmail
- String - OptionalanonymousId
- 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 - OptionallineItems
- Array of LineItemcustomLineItems
- Array of CustomLineItemtotalPrice
- CentPrecisionMoney
The total price of this line item. If the line item is discounted, then thetotalPrice
is the DiscountedLineItemPriceForQuantity multiplied byquantity
. Otherwise the total price is the product price multiplied by thequantity
.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 oftaxedPrice
of ShippingInfo across all Shipping Methods. ForPlatform
TaxMode, it is set automatically only if shipping address is set or Shipping Method is added to the Cart.shippingAddress
- Address - OptionalbillingAddress
- Address - OptionalshippingMode
- ShippingMode
Indicates whether one or multiple Shipping Methods are added to the Cart. The default mode isSingle
.shippingKey
- String - Optional
User-defined unique identifier of the Shipping Method withSingle
ShippingMode.shippingCustomFields
- CustomFields - Optional
Custom Fields of the Shipping Method forSingle
ShippingMode.shipping
- Array of Shipping
Holds all shipping-related information per Shipping Method forMulti
ShippingMode. It is updated automatically after the Shipping Method is added.taxMode
- TaxModetaxRoundingMode
- RoundingMode
When calculating taxes fortaxedPrice
, the selected mode is used for rounding.taxCalculationMode
- TaxCalculationMode
When calculating taxes fortaxedPrice
, 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 - OptionalpaymentState
- PaymentState - OptionalshippingInfo
- ShippingInfo - Optional
Set if the ShippingMethod is set.syncInfo
- Set of SyncInforeturnInfo
- Array of ReturnInfopurchaseOrderNumber
- 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. EitherdiscountCodes
ordirectDiscounts
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 LineItemModeGiftLineItem
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 stateOrdered
.quote
- Reference to a Quote - Optional
Set when the order was created from a quote.custom
- CustomFields - OptionalpaymentInfo
- PaymentInfo - Optionallocale
- String conforming to IETF language tag - OptionalinventoryMode
- InventoryModeshippingRateInput
- ShippingRateInput - Optional
The shippingRateInput is used as an input to select a ShippingRatePriceTier.origin
- CartOriginitemShippingAddresses
- 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
Theversion
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 - OptionalorderState
- OrderState - Optional
Order will be created withOpen
status by default.state
- Reference to a State - OptionalshipmentState
- ShipmentState - Optionalcustom
- CustomFieldsDraft - Optional
CustomFields for the Order. The Custom Field type must match the type of the Custom Fields in the referenced Cart.
OrderFromQuoteDraft
quote
- ResourceIdentifier - Required
ResourceIdentifier of the Quote from which this order is created. If the Quote hasQuoteState
inAccepted
,Declined
orWithdrawn
then the order creation will fail. The creation will also fail if theQuote
has expired (validTo
check).version
- Number - Required
Theversion
of the Quote from which an order is created.quoteStateToAccepted
- Boolean - Optional (default:false
)
Iftrue
, thequoteState
of the referenced Quote will be set toAccepted
.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 - OptionalorderState
- OrderState - Optional
Order will be created withOpen
status by default.state
- Reference to a State - OptionalshipmentState
- 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).
ReturnInfo
Stores information about returns connected to this order.
items
- Array of ReturnItemreturnTrackingId
- 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
id
- Stringtype
-LineItemReturnItem
quantity
- NumberlineItemId
- Stringcomment
- StringshipmentState
- ReturnShipmentStatepaymentState
- ReturnPaymentStatecustom
- CustomFields - OptionallastModifiedAt
- DateTimecreatedAt
- DateTime
CustomLineItemReturnItem
id
- Stringtype
-CustomLineItemReturnItem
quantity
- NumbercustomLineItemId
- Stringcomment
- StringshipmentState
- ReturnShipmentStatepaymentState
- ReturnPaymentStatecustom
- CustomFields - OptionallastModifiedAt
- DateTimecreatedAt
- DateTime
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 - RequiredlineItemId
- String - Requiredcomment
- String - OptionalshipmentState
- ReturnShipmentState - Requiredcustom
- CustomFields - Optional
CustomLineItemReturnItemDraft
quantity
- Number - RequiredcustomLineItemId
- String - Requiredcomment
- String - OptionalshipmentState
- ReturnShipmentState - Requiredcustom
- 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
- Stringkey
- String
User-defined unique identifier of the Delivery.createdAt
- DateTimeitems
- 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 Parceladdress
- Address - Optionalcustom
- 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 - Optionaladdress
- AddressDraft - Optionalcustom
- CustomFieldsDraft - Optional
DeliveryItem
id
- ID of a LineItem or a CustomLineItemquantity
- Number
Parcel
A parcel stores the information about the appearance, the movement and the content of a parcel.
id
- String - Unique id of the parcelkey
- String - User-defined unique identifier of the parcel - OptionalcreatedAt
- DateTimemeasurements
- ParcelMeasurements - OptionaltrackingData
- TrackingData - Optionalitems
- Array of DeliveryItem - Optional
The delivery items contained in this parcel.custom
- CustomFields - Optional
ParcelDraft
key
- String - User-defined unique identifier of the parcel - Optionalmeasurements
- ParcelMeasurements - OptionaltrackingData
- TrackingData - Optionalitems
- Array of DeliveryItem - Optional
The delivery items contained in this parcel.custom
- CustomFieldsDraft - Optional
ParcelMeasurements
Information regarding the dimensions of a parcel.
heightInMillimeter
- NumberlengthInMillimeter
- NumberwidthInMillimeter
- NumberweightInGram
- 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 theprovider
.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
payments
- Array of References to Payments
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
Your feedback will help us to improve the Order search experience. Join our commercetools user research program.
Query Orders
Endpoint: /{projectKey}/orders
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}
Response Representation: PagedQueryResult with results
containing an array of Order
Query Parameters:
where
- Query Predicate - Optionalsort
- Sort - Optionalexpand
- Expansion - Optionallimit
- Number - Optionaloffset
- Number - Optional
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:
where
- Query Predicate - Optionalsort
- Sort - Optionalexpand
- Expansion - Optionallimit
- Number - Optionaloffset
- Number - Optional
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:
- OutOfStock
- PriceChanged
- DiscountCodeNonApplicable
- ShippingMethodDoesNotMatchCart
- InvalidItemShippingDetails
- MatchingPriceNotFound
- MissingTaxRateForCountry
Messages:
- OrderCreated Message.
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:
- OutOfStock
- PriceChanged
- DiscountCodeNonApplicable
- ShippingMethodDoesNotMatchCart
- InvalidItemShippingDetails
- MatchingPriceNotFound
- MissingTaxRateForCountry
- CountryNotConfiguredInStore
Messages:
- OrderCreated Message.
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:
- OrderCreated Message
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"
- RequiredreturnDate
- DateTime - OptionalreturnTrackingId
- 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.
action
- String -"setReturnShipmentState"
returnItemId
- String - ID of the concerning ReturnItemshipmentState
- ReturnShipmentState - New ReturnShipmentState according to allowed transitions
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.
action
- String -"setReturnPaymentState"
returnItemId
- String - ID of the concerning ReturnItempaymentState
- ReturnPaymentState - New ReturnPaymentState according to allowed transitions
Change the state of LineItem according to allowed transitions
action
- String -"transitionLineItemState"
lineItemId
- Stringquantity
- NumberfromState
- Reference to a StatetoState
- Reference to a StateactualTransitionDate
- DateTime - Optional
This update action produces a LineItemStateTransition Message.
Change the state of CustomLineItem according to allowed transitions
action
- String -"transitionCustomLineItemState"
customLineItemId
- Stringquantity
- NumberfromState
- Reference to a StatetoState
- Reference to a StateactualTransitionDate
- 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
- Stringstate
- 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
- Stringstate
- Array of ItemState
Add Delivery
A Delivery can only be added to an Order if its shippingInfo
exists.
action
- String -"addDelivery"
deliveryKey
- String - Optional
User-defined unique identifier of the Delivery.items
- Array of DeliveryItem - Optionaladdress
- AddressDraft - Optionalparcels
- Array of ParcelDraft - Optionalcustom
- CustomFieldsDraft - Optional
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 - Optionalmeasurements
- ParcelMeasurements - OptionaltrackingData
- TrackingData - Optionalitems
- 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 Stateforce
- Boolean - Optional - Defaults tofalse
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.
action
- String -"setCustomType"
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.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 CustomField
This action sets, overwrites, or removes any existing custom field for an existing order.
action
- String -"setCustomField"
name
- String - Requiredvalue
- CustomFieldValue - Optional
Ifvalue
is absent ornull
, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. Ifvalue
is provided, set thevalue
of the field defined by thename
.
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 setvalue
- CustomFieldValue - Optional
Specifies the format of the value of the Custom Field defined byname
. Ifvalue
is absent ornull
, the field specified byname
, 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 setvalue
- CustomFieldValue - Optional
Specifies the format of the value of the Custom Field defined byname
. Ifvalue
is absent ornull
, the field specified byname
, 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 - Requiredtype
- 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 - Requiredname
- String - Required
The name of the Custom Field to setvalue
- CustomFieldValue - Optional
Specifies the format of the value of the Custom Field defined byname
. Ifvalue
is absent ornull
, the field specified byname
, 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 setvalue
- CustomFieldValue - Optional
Specifies the format of the value of the Custom Field defined byname
. Ifvalue
is absent ornull
, the field specified byname
, 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 setvalue
- CustomFieldValue - Optional
Specifies the format of the value of the Custom Field defined byname
. Ifvalue
is absent ornull
, the field specified byname
, 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 - EitherparcelId
orparcelKey
is requiredparcelKey
- String - EitherparcelId
orparcelKey
is requiredtype
- 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 - EitherparcelId
orparcelKey
is requiredparcelKey
- String - EitherparcelId
orparcelKey
is requiredname
- String - Required
The name of the Custom Field to setvalue
- CustomFieldValue - Optional
Specifies the format of the value of the Custom Field defined byname
. Ifvalue
is absent ornull
, the field specified byname
, 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
- Stringfields
- 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
- Stringname
- String - Requiredvalue
- CustomFieldValue - Optional
Ifvalue
is absent ornull
, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. Ifvalue
is provided, set thevalue
of the field defined by thename
.
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
- Stringfields
- 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
- Stringname
- String - Requiredvalue
- CustomFieldValue - Optional
Ifvalue
is absent ornull
, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. Ifvalue
is provided, set thevalue
of the field defined by thename
.
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
- Stringfields
- 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
- Stringname
- String - Requiredvalue
- CustomFieldValue - Optional
Ifvalue
is absent ornull
, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. Ifvalue
is provided, set thevalue
of the field defined by thename
.
Add Payment
This action adds a payment to the PaymentInfo. The payment must not be assigned to another Order or active Cart yet.
Remove Payment
This action removes a payment from the PaymentInfo.
Set Locale
Sets the locale. Must be one of the languages supported for this Project.
action
- String -"setLocale"
locale
- String conforming to IETF language tag - Optional
Set Delivery Items
Updates the delivery items of a Delivery. 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 - EitherparcelId
orparcelKey
is required
ID of the Parcel which shall be updated.parcelKey
- String - EitherparcelId
orparcelKey
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 - EitherparcelId
orparcelKey
is required
ID of the Parcel which shall be updated.parcelKey
- String - EitherparcelId
orparcelKey
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 - EitherparcelId
orparcelKey
is required
ID of the Parcel which shall be updated.parcelKey
- String - EitherparcelId
orparcelKey
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 - EitherparcelId
orparcelKey
is required
ID of the Parcel which shall be updated.parcelKey
- String - EitherparcelId
orparcelKey
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).
action
- String -"setStore"
store
- ResourceIdentifier to a Store - Optional
This update action produces an OrderStoreSet Message.
Overview of update actions for Cart, Order and OrderEdit
Update action | Cart | Order | Order 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 - RequireddataErasure
- Boolean - Optional, defaults tofalse
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 - RequireddataErasure
- Boolean - Optional, defaults tofalse
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 - RequireddataErasure
- Boolean - Optional, defaults tofalse
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 - RequireddataErasure
- Boolean - Optional, defaults tofalse
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.