This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Orders

An Order can be created from a Cart, usually after a checkout process has been completed.

Representations

Representations are JSON objects submitted or received as payload to API requests or responses.

Order

id
String

Unique identifier of the Order.

version
Int

Current version of the Order.

orderNumber
String

User-defined identifier of the Order that is unique across a Project.

purchaseOrderNumber
String

User-defined identifier of a purchase Order.

It is typically set by the Buyer and can be used with Quotes to track the purchase Order during the quote and order flow.

customerId
String

id of the Customer that the Order belongs to.

customerEmail
String

Email address of the Customer that the Order belongs to.

customerGroup

Reference to the Customer Group of the Customer that the Order belongs to. Used for LineItem Price selection.

anonymousId
String

Anonymous session associated with the Order.

businessUnit

Reference to a Business Unit the Order belongs to.

Reference to a Store the Order belongs to.

lineItems
Array of LineItem

Line Items that are part of the Order.

customLineItems
Array of CustomLineItem

Custom Line Items that are part of the Order.

totalPrice

Sum of the totalPrice field of all LineItems and CustomLineItems, and if available, the price field of ShippingInfo. If a discount applies on totalPrice, this field holds the discounted value.

Taxes are included if TaxRate includedInPrice is true for each price.

taxedPrice
  • For Platform TaxMode, it is automatically set when a shipping address is set.
  • For External TaxMode, it is automatically set when shippingAddress and external Tax Rates for all Line Items, Custom Line Items, and Shipping Methods in the Cart are set.

If a discount applies on totalPrice, this field holds the discounted values.

taxedShippingPrice

Sum of the taxedPrice field of ShippingInfo across all Shipping Methods.

discountOnTotalPrice

Discounts that apply on the total price of the Order.

taxMode

Indicates how Tax Rates are set.

Default: Platform
taxRoundingMode

Indicates how monetary values are rounded when calculating taxes for taxedPrice.

Default: HalfEven
taxCalculationMode

Indicates how taxes are calculated when calculating taxes for taxedPrice.

Default: LineItemLevel
inventoryMode

Indicates how stock quantities are tracked for Line Items in the Order.

Default: None
billingAddress

Billing address associated with the Order.

shippingAddress

Shipping address associated with the Order. Determines eligible ShippingMethod rates and Tax Rates of Line Items.

shippingMode

Indicates whether there can be one or multiple Shipping Methods.

Default: Single
shippingKey
String

key of the ShippingMethod for Single ShippingMode.

shippingInfo

Shipping-related information for Single ShippingMode. Automatically set when a Shipping Method is set.

shippingRateInput

Input used to select a ShippingRatePriceTier. The data type of this field depends on the shippingRateInputType.type configured in the Project:

shippingCustomFields

Custom Fields of the Shipping Method for Single ShippingMode.

shipping
Array of Shipping

Shipping-related information for Multiple ShippingMode. Updated automatically each time a new Shipping Method is added.

itemShippingAddresses
Array of Address

Additional shipping addresses of the Order as specified by LineItems using the shippingDetails field. Eligible Shipping Methods or applicable Tax Rates are determined by the address in shippingAddress, and not itemShippingAddresses.

discountCodes
Array of DiscountCodeInfo

Discount Codes added to the Order. An Order that has directDiscounts cannot have discountCodes.

directDiscounts
Array of DirectDiscount

Direct Discounts added to the Order. An Order that has discountCodes cannot have directDiscounts.

refusedGifts

Automatically set when a Line Item with GiftLineItem LineItemMode is removed from the Order.

paymentInfo

Payment information related to the Order.

country

Used for LineItem Price selection.

Pattern: ^[A-Z]{2}$
locale

Languages of the Order. Can only contain languages supported by the Project.

origin

Indicates the origin of the Cart from which the Order was created.

Default: Customer
cart

Reference to the Cart for an Order created from Cart. The referenced Cart will have the Ordered CartState.

quote

Reference to the Quote for an Order created from Quote.

orderState

Current status of the Order.

shipmentState

Shipment status of the Order.

paymentState

Payment status of the Order.

state

State of the Order. This reference can point to a State in a custom workflow.

syncInfo
Array of SyncInfo

Contains synchronization activity information of the Order (like export or import). Can only be set with Update SyncInfo update action.

returnInfo
Array of ReturnInfo

Contains information regarding the returns associated with the Order.

completedAt

User-defined date and time (UTC) of the Order. Present only on an Order created using Order Import.

custom

Custom Fields of the Order.

createdAt

Date and time (UTC) the Order was initially created.

createdByBETA

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt

Date and time (UTC) the Order was last updated.

lastModifiedByBETA

Present on resources created after 1 February 2019 except for events not tracked.

OrderFromCartDraft

version
Int

version of the Cart from which the Order is created.

ResourceIdentifier to the Cart from which the Order is created.

This field is required, but is marked as optional for backwards compatibility reasons.

orderNumber
String

User-defined identifier for the Order that is unique across a Project. Once set, the value cannot be changed.

purchaseOrderNumber
String

User-defined identifier for a purchase Order.

It is typically set by the Buyer and can be used with Quotes to track the purchase Order during the quote and order flow.

paymentState

Payment status for the Order.

shipmentState

Shipment status for the Order.

orderState

Current status for the Order.

Default: Open

State for the Order in a custom workflow.

custom

Custom Fields for the Order. The Custom Fields' type must match the Custom Fields' type in the referenced Cart.

  • If empty, the Custom Fields on the referenced Cart are added to the Order automatically.
  • If specified, the Custom Fields are merged with the Custom Fields on the referenced Cart and added to the Order.

OrderFromQuoteDraft

version
Int

version of the Quote from which the Order is created.

ResourceIdentifier to the Quote from which the Order is created. If the referenced Quote has expired (validTo check) or its quoteState is Accepted, Declined, or Withdrawn, the Order creation will fail.

quoteStateToAccepted
Boolean

If true, the quoteState of the referenced Quote will be set to Accepted.

Default: false
orderNumber
String

User-defined identifier for the Order that is unique across a Project. Once set, the value cannot be changed.

paymentState

Payment status for the Order.

shipmentState

Shipment status for the Order.

orderState

Current status for the Order.

Default: Open

State of the Order in a custom workflow.

OrderPagedQueryResponse

PagedQueryResult with results containing an array of Order.

limit
Int
offset
Int

Number of elements skipped.

count
Int

Actual number of results returned.

total
Int

Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.

results
Array of Order

Orders matching the query.

OrderReference

id
String

Unique identifier of the referenced Order.

typeId
String
"order"

References an Order.

obj

Contains the representation of the expanded Order. Only present in responses to requests with Reference Expansion for Orders.

OrderState

Indicates the state of the Order.

Open

The default state of a new Order.

Confirmed

Indicates that the Order is accepted and being processed.

Complete

Indicates that the Order is fulfilled.

Cancelled

Indicates that the Order is canceled.

ShipmentState

Indicates the shipment status of the Order.

Shipped

Indicates that the Order is shipped.

Delivered

Indicates that the Order is delivered.

Ready

Indicates that the Order is ready to be shipped.

Pending

Indicates that the shipment of the Order is pending.

Delayed

Indicates that the shipment of the Order is delayed.

Partial

Indicates that items in the Order are shipped in more than one shipment.

Backorder

Indicates that items in the Order are not in stock and will be delivered once the items are restocked.

PaymentState

Indicates the payment status for the Order.

BalanceDue

Indicates that payment balance is due for the Order.

Failed

Indicates that payment for the Order has failed.

Pending

Indicates that payment for the Order is pending.

CreditOwed

Indicates that payment for the Order is made on a credit basis.

Paid

Indicates that the Order is paid for.

PaymentInfo

payments
Array of PaymentReference

References to the Payments associated with the Order.

SyncInfo

Contains synchronization activity information of the Order (like export or import).

externalId
String

Identifier of an external order instance, file, or other resource.

channel

Connection to a synchronization destination.

syncedAt

Date and time (UTC) the information was synced.

Delivery

Contains information on how items are shipped to Customers, for example, a delivery note.

id
String

Unique identifier of the Delivery.

key
String

User-defined unique identifier of the Delivery.

MinLength: 2MaxLength: 256Pattern: ^[a-zA-Z0-9_-]
items
Array of DeliveryItem

Line Items or Custom Line Items that are delivered.

parcels
Array of Parcel

Information regarding the appearance, content, and shipment of a Parcel.

address

Address to which Parcels are delivered.

custom

Custom Fields of the Delivery.

createdAt

Date and time (UTC) the Delivery was created.

DeliveryDraft

key
String

User-defined unique identifier of the Delivery.

MinLength: 2MaxLength: 256Pattern: ^[a-zA-Z0-9_-]
items
Array of DeliveryItem

Line Items or Custom Line Items to deliver. It can also be specified individually for each Parcel.

parcels
Array of ParcelDraft

Information regarding the appearance, content, and shipment of a parcel.

address

Address to which the Parcels are delivered.

custom

Custom Fields for the Delivery.

DeliveryItem

id
String

id of the LineItem or CustomLineItem delivered.

quantity
Int

Number of Line Items or Custom Line Items delivered.

Parcel

Information regarding the appearance, content, and shipment of a Parcel.

id
String

Unique identifier of the Parcel.

key
String

User-defined unique identifier of the Parcel.

MinLength: 2MaxLength: 256Pattern: ^[a-zA-Z0-9_-]
measurements

Information about the dimensions of the Parcel.

trackingData

Shipment tracking information of the Parcel.

items
Array of DeliveryItem

Line Items or Custom Line Items delivered in this Parcel.

custom

Custom Fields of the Parcel.

createdAt

Date and time (UTC) the Parcel was created.

ParcelDraft

key
String

User-defined unique identifier of the Parcel.

MinLength: 2MaxLength: 256Pattern: ^[a-zA-Z0-9_-]
measurements

Information about the dimensions for the Parcel.

trackingData

Shipment tracking information for the Parcel.

items
Array of DeliveryItem

Line Items or Custom Line Items delivered in this Parcel.

custom

Custom Fields for the Parcel.

ParcelMeasurements

heightInMillimeter
Int

Height of the Parcel.

lengthInMillimeter
Int

Length of the Parcel.

widthInMillimeter
Int

Width of the Parcel.

weightInGram
Int

Weight of the Parcel.

TrackingData

Information that helps track a Parcel.

trackingId
String

Identifier to track the Parcel.

carrier
String

Name of the carrier that delivers the Parcel.

provider
String

Name of the provider that serves as facade to several carriers.

providerTransaction
String

Transaction identifier with the provider.

isReturn
Boolean
  • If true, the Parcel is being returned.
  • If false, the Parcel is being delivered to the customer.
Default: false

Returns

The following types contain representations of returns, including what items are being returned and their current payment and shipment states.

ReturnInfo

Stores information about returns connected to an Order.

items
Array of ReturnItem

Information on the Line Items or Custom Line Items returned.

returnTrackingId
String

User-defined identifier to track the return.

returnDate

Date and time (UTC) the return is initiated.

ReturnInfoDraft

items
Array of ReturnItemDraft

Information on the Line Items or Custom Line Items returned.

returnTrackingId
String

User-defined identifier for tracking the return.

returnDate

Date and time (UTC) the return is initiated.

ReturnItem

Information on the returned Line Items or Custom Line Items; see LineItemReturnItem or CustomLineItemReturnItem respectively.

LineItemReturnItem

id
String

Unique identifier of the Return Item.

key
String

User-defined unique identifier of the LineItemReturnItem.

MinLength: 2MaxLength: 256Pattern: ^[a-zA-Z0-9_-]
quantity
Int

Number of Line Items returned.

type
String
"LineItemReturnItem"
comment
String

User-defined description for the return.

shipmentState

Shipment status of the Return Item.

paymentState

Payment status of the Return Item:

lineItemId
String

id of the returned LineItem.

custom

Custom Fields of the Return Item.

createdAt

Date and time (UTC) the Return Item was intitially created.

lastModifiedAt

Date and time (UTC) the Return Item was last updated.

CustomLineItemReturnItem

id
String

Unique identifier of the Return Item.

key
String

User-defined unique identifier of the CustomLineItemReturnItem.

MinLength: 2MaxLength: 256Pattern: ^[a-zA-Z0-9_-]
quantity
Int

Number of Custom Line Items returned.

type
String
"CustomLineItemReturnItem"
comment
String

User-defined description for the return.

shipmentState

Shipment status of the Return Item.

paymentState

Payment status of the Return Item:

customLineItemId
String

id of the returned CustomLineItem.

custom

Custom Fields of the Return Item.

createdAt

Date and time (UTC) the Return Item was intitially created.

lastModifiedAt

Date and time (UTC) the Return Item was last updated.

ReturnItemDraft

key
String

User-defined unique identifier of the Return Item.

MinLength: 2MaxLength: 256Pattern: ^[a-zA-Z0-9_-]
quantity
Int

Number of Line Items or Custom Line Items to return.

lineItemId
String

id of the LineItem to return.

Required if Line Items are returned, to create a LineItemReturnItem.

customLineItemId
String

id of the CustomLineItem to return.

Required if Custom Line Items are returned, to create a CustomLineItemReturnItem.

comment
String

User-defined description for the return.

shipmentState

Shipment status of the item to be returned. Can either be Advised or Returned only.

custom

Custom Fields for the Return Item.

ReturnShipmentState

Advised

Initial state for Return Items that are non-refundable.

Return Items of this state will have the NonRefundable ReturnPaymentState.

Returned

Initial state for Return Items that are refundable.

Return Items of this state will have the Initial ReturnPaymentState.

BackInStock

A state indicating that the Return Items are restocked in inventory.

Unusable

A state indicating that the Return Items are not in good condition and cannot be restocked.

Allowed state transitions:

ReturnPaymentState

NonRefundable

Initial state for Return Items for which payment cannot be refunded.

Return Items have the Advised ReturnShipmentState.

Initial

Initial state for Return Items for which payment can be refunded.

Return Items have the Returned ReturnShipmentState.

Refunded

The payment for the Return Items is refunded.

NotRefunded

The payment for the Return Items is not refunded.

Allowed state transitions:

Get Order

Get Order by ID

GET
https://api.{region}.commercetools.com/{projectKey}/orders/{id}
OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Order.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200Orderasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/orders/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Orderjson
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}

Get Order by OrderNumber

GET
https://api.{region}.commercetools.com/{projectKey}/orders/order-number={orderNumber}
OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

orderNumber
String

orderNumber of the Order. Should be provided in URL-encoded format.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200Orderasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/orders/order-number={orderNumber} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Orderjson
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}

Get Order in Store

Get Order in Store by ID

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders/{id}

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.

OAuth 2.0 Scopes:
view_orders:{projectKey} , view_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

id
String

id of the Order.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200Orderasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Orderjson
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}

Get Order in Store by OrderNumber

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders/order-number={orderNumber}

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.

OAuth 2.0 Scopes:
view_orders:{projectKey} , view_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

orderNumber
String

orderNumber of the Order. Should be provided in URL-encoded format.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200Orderasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders/order-number={orderNumber} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Orderjson
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}

Query Orders

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

GET
https://api.{region}.commercetools.com/{projectKey}/orders
OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
where
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
Any string parameter matching this regular expression

Predicate parameter values.

The parameter can be passed multiple times.
sort
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int
offset
Int

Number of elements skipped.

withTotal
Boolean

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Response:
200OrderPagedQueryResponseasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/orders -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: OrderPagedQueryResponsejson
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}
]
}

Query Orders in Store

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders
OAuth 2.0 Scopes:
view_orders:{projectKey} , view_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

Query parameters:
where
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
Any string parameter matching this regular expression

Predicate parameter values.

The parameter can be passed multiple times.
sort
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int
offset
Int

Number of elements skipped.

withTotal
Boolean

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Response:
200OrderPagedQueryResponseasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: OrderPagedQueryResponsejson
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}
]
}

Check if Order exists

Check if Order exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/orders/{id}

Checks if an Order exists for a given id. Returns a 200 OK status if the Order exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Order.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/orders/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Order exists by OrderNumber

HEAD
https://api.{region}.commercetools.com/{projectKey}/orders/order-number={orderNumber}

Checks if an Order exists for a given orderNumber. Returns a 200 OK status if the Order exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

orderNumber
String

orderNumber of the Order. Should be provided in URL-encoded format.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/orders/order-number={orderNumber} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Order exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/orders

Checks if an Order exists for a given Query Predicate. Returns a 200 OK status if any Orders match the Query Predicate or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
where
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/orders -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Order exists in Store

Check if Order exists in Store by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders/{id}

Checks if an Order exists for a given id. Returns a 200 OK status if the Order exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_orders:{projectKey} , view_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

id
String

id of the Order.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Order exists in Store by OrderNumber

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders/order-number={orderNumber}

Checks if an Order exists for a given orderNumber. Returns a 200 OK status if the Order exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_orders:{projectKey} , view_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

orderNumber
String

orderNumber of the Order. Should be provided in URL-encoded format.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders/order-number={orderNumber} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Order exists in Store by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders

Checks if an Order exists for a given Query Predicate. Returns a 200 OK status if any Orders match the Query Predicate or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_orders:{projectKey} , view_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

Query parameters:
where
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Create Order

Create Order from Cart

POST
https://api.{region}.commercetools.com/{projectKey}/orders

Before you create an Order, the Cart must have a shipping address set. The shipping address is used for tax calculation for a Cart with Platform TaxMode.

Creating an Order produces the OrderCreated Message.

Specific Error Codes:

OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:OrderFromCartDraftasapplication/json
Response:
201Orderasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/orders -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"cart" : {
"id" : "7c2e2694-aefe-43d7-888e-6a99514caaca",
"typeId" : "cart"
},
"version" : 10
}
DATA
201 Response Example: Orderjson
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}

Create Order from Quote

POST
https://api.{region}.commercetools.com/{projectKey}/orders/quotes
OAuth 2.0 Scopes:
manage_quotes:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Request Body:OrderFromQuoteDraftasapplication/json
Response:
201Orderasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/orders/quotes -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"quote" : {
"id" : "40d04a85-34d3-4769-a1b6-ecd00db2a587",
"typeId" : "quote"
},
"version" : 1
}
DATA
201 Response Example: Orderjson
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}

Create Order by Import

To import an Order without having a Cart or Quote before, see Create Order by Import.

Create Order in Store

Create Order in Store from Cart

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders

Before you create an Order, the Cart must have a shipping address set. The shipping address is used for tax calculation for a Cart with Platform TaxMode.

Creating an Order produces the OrderCreated Message.

Specific Error Codes:

OAuth 2.0 Scopes:
manage_orders:{projectKey} , manage_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:OrderFromCartDraftasapplication/json
Response:
201Orderasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"cart" : {
"id" : "7c2e2694-aefe-43d7-888e-6a99514caaca",
"typeId" : "cart"
},
"version" : 10
}
DATA
201 Response Example: Orderjson
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}

Update Order

Update Order by ID

POST
https://api.{region}.commercetools.com/{projectKey}/orders/{id}
OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Order.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
application/json
version
Int

Expected version of the Order on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions
Array of OrderUpdateAction

Update actions to be performed on the Order.

Response:
200Orderasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/orders/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeOrderState",
"orderState" : "Complete"
} ]
}
DATA
200 Response Example: Orderjson
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}

Update Order by OrderNumber

POST
https://api.{region}.commercetools.com/{projectKey}/orders/order-number={orderNumber}
OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

orderNumber
String

orderNumber of the Order. Should be provided in URL-encoded format.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
application/json
version
Int

Expected version of the Order on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions
Array of OrderUpdateAction

Update actions to be performed on the Order.

Response:
200Orderasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/orders/order-number={orderNumber} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeOrderState",
"orderState" : "Complete"
} ]
}
DATA
200 Response Example: Orderjson
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}

Update Order in Store

Update Order in Store by ID

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders/{id}

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.

OAuth 2.0 Scopes:
manage_orders:{projectKey} , manage_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

id
String

id of the Order.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
application/json
version
Int

Expected version of the Order on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions
Array of OrderUpdateAction

Update actions to be performed on the Order.

Response:
200Orderasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeOrderState",
"orderState" : "Complete"
} ]
}
DATA
200 Response Example: Orderjson
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}

Update Order in Store by OrderNumber

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders/order-number={orderNumber}

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.

OAuth 2.0 Scopes:
manage_orders:{projectKey} , manage_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

orderNumber
String

orderNumber of the Order. Should be provided in URL-encoded format.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
application/json
version
Int

Expected version of the Order on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions
Array of OrderUpdateAction

Update actions to be performed on the Order.

Response:
200Orderasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders/order-number={orderNumber} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeOrderState",
"orderState" : "Complete"
} ]
}
DATA
200 Response Example: Orderjson
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}

Update actions

on Order

Set Order Number

action
String
"setOrderNumber"
orderNumber
String

Value to set. Must be unique across a Project. Once set, the value cannot be changed.

Example: json
{
"action": "setOrderNumber",
"orderNumber": "myOrderNumber"
}

Set Purchase Order Number

Produces the PurchaseOrderNumberSet Message.

action
String
"setPurchaseOrderNumber"
purchaseOrderNumber
String

Value to set. If empty, any existing value is removed.

Example: json
{
"action": "setPurchaseOrderNumber",
"purchaseOrderNumber": "purchaseOrderNumberString"
}

Set Customer ID

Setting the Order's customerId does not recalculate prices or discounts on the Order. If the Customer belongs to a Customer Group, customerGroup on the Order is updated automatically.

Produces the OrderCustomerSet Message.

action
String
"setCustomerId"
customerId
String

id of an existing Customer. If empty, any existing value is removed.

Example: json
{
"action": "setCustomerId",
"customerId": "{{customer-id}}"
}

Set Customer Email

This action updates the customerEmail on the Order, but it does not change the Customer email on the Cart the Order has been created from.

Produces the Order Customer Email Set Message.

action
String
"setCustomerEmail"
email
String

Value to set. If empty, any existing value is removed.

Example: json
{
"action": "setCustomerEmail",
"email": "email@example.com"
}

Add Payment

action
String
"addPayment"

Payment to add to the PaymentInfo. Must not be assigned to another Order or active Cart already.

Example: json
{
"action": "addPayment",
"payment": {
"typeId": "payment",
"id": "{{payment-id}}"
}
}

Remove Payment

action
String
"removePayment"

Payment to remove from the PaymentInfo.

Example: json
{
"action": "removePayment",
"payment": {
"typeId": "payment",
"id": "{{payment-id}}"
}
}

Change PaymentState

Produces the Order Payment State Changed Message.

action
String
"changePaymentState"
paymentState

New payment status of the Order.

Example: json
{
"action": "changePaymentState",
"paymentState": "Failed"
}

Set Billing Address

This action updates the billingAddress on the Order, but it does not change the billing address on the referenced Cart from which the Order is created.

Produces the Order Billing Address Set Message.

action
String
"setBillingAddress"
address

Value to set. If empty, any existing value is removed.

Example: json
{
"action": "setBillingAddress",
"address": {
"key": "exampleKey",
"title": "My Address",
"salutation": "Mr.",
"firstName": "Example",
"lastName": "Person",
"streetName": "Example Street",
"streetNumber": "4711",
"additionalStreetInfo": "Backhouse",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE",
"company": "My Company Name",
"department": "Sales",
"building": "Hightower 1",
"apartment": "247",
"pOBox": "2471",
"phone": "+49 89 12345678",
"mobile": "+49 171 2345678",
"email": "email@example.com",
"fax": "+49 89 12345679",
"additionalAddressInfo": "no additional Info",
"externalId": "Information not needed"
}
}

Set Shipping Address

This action updates the shippingAddress on the Order, but it does not change the shipping address on the referenced Cart from which the Order is created. Also, it does not recalculate the Cart as taxes may not fit to the shipping address anymore.

Produces the Order Shipping Address Set Message.

action
String
"setShippingAddress"
address

Value to set. If empty, any existing value is removed.

Example: json
{
"action": "setShippingAddress",
"address": {
"key": "exampleKey",
"title": "My Address",
"salutation": "Mr.",
"firstName": "Example",
"lastName": "Person",
"streetName": "Example Street",
"streetNumber": "4711",
"additionalStreetInfo": "Backhouse",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE",
"company": "My Company Name",
"department": "Sales",
"building": "Hightower 1",
"apartment": "247",
"pOBox": "2471",
"phone": "+49 89 12345678",
"mobile": "+49 171 2345678",
"email": "email@example.com",
"fax": "+49 89 12345679",
"additionalAddressInfo": "no additional Info",
"externalId": "Information not needed"
}
}

Add ItemShippingAddress

Adds an address to an Order when shipping to multiple addresses is desired.

action
String
"addItemShippingAddress"
address

Address to append to itemShippingAddresses. The new Address must have a key that is unique across this Order.

Example: json
{
"action": "addItemShippingAddress",
"address": {
"key": "exampleKey",
"title": "My Address",
"salutation": "Mr.",
"firstName": "Example",
"lastName": "Person",
"streetName": "Example Street",
"streetNumber": "4711",
"additionalStreetInfo": "Backhouse",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE",
"company": "My Company Name",
"department": "Sales",
"building": "Hightower 1",
"apartment": "247",
"pOBox": "2471",
"phone": "+49 89 12345678",
"mobile": "+49 171 2345678",
"email": "email@example.com",
"fax": "+49 89 12345679",
"additionalAddressInfo": "no additional Info",
"externalId": "Information not needed"
}
}

Remove ItemShippingAddress

An address can only be removed if it is not referenced in any ItemShippingTarget of the Cart. In such case, change the Line Item shipping address to a different addressKey first using the Set LineItemShippingDetails update action, before you remove the obsolete address.

action
String
"removeItemShippingAddress"
addressKey
String

key of the Address to remove from itemShippingAddresses.

Example: json
{
"action": "removeItemShippingAddress",
"addressKey": "addressKey"
}

Update ItemShippingAddress

Updates an address in itemShippingAddresses by keeping the Address key.

action
String
"updateItemShippingAddress"
address

The new Address with the same key as the Address it will replace.

Example: json
{
"action": "updateItemShippingAddress",
"address": {
"key": "exampleKey",
"title": "My Address",
"salutation": "Mr.",
"firstName": "Example",
"lastName": "Person",
"streetName": "Example Street",
"streetNumber": "4711",
"additionalStreetInfo": "Backhouse",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE",
"company": "My Company Name",
"department": "Sales",
"building": "Hightower 1",
"apartment": "247",
"pOBox": "2471",
"phone": "+49 89 12345678",
"mobile": "+49 171 2345678",
"email": "email@example.com",
"fax": "+49 89 12345679",
"additionalAddressInfo": "no additional Info",
"externalId": "Information not needed"
}
}

Add Delivery

A Delivery can only be added to an Order if its shippingInfo (for shippingMode = Single), or its shipping (for shippingMode = Multiple) exists.

Produces the Delivery Added Message.

action
String
"addDelivery"
deliveryKey
String

key of an existing Delivery.

shippingKey
String

key of the ShippingMethod, required for Multiple ShippingMode.

items
Array of DeliveryItem

Line Items or Custom Line Items to be included in the Delivery.

address

Address the parcels should be delivered to.

parcels
Array of ParcelDraft

Parcels of the Delivery.

If provided, this update action produces the Parcel Added To Delivery Message.

custom

Custom Fields for the Delivery.

Example: json
{
"action": "addDelivery",
"items": [
{
"id": "{{lineItemId}}",
"quantity": 1
}
],
"address": {
"key": "exampleKey",
"title": "My Address",
"salutation": "Mr.",
"firstName": "Example",
"lastName": "Person",
"streetName": "Example Street",
"streetNumber": "4711",
"additionalStreetInfo": "Backhouse",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE",
"company": "My Company Name",
"department": "Sales",
"building": "Hightower 1",
"apartment": "247",
"pOBox": "2471",
"phone": "+49 89 12345678",
"mobile": "+49 171 2345678",
"email": "email@example.com",
"fax": "+49 89 12345679",
"additionalAddressInfo": "no additional Info",
"externalId": "Information not needed"
},
"parcels": [
{
"measurements": {
"heightInMillimeter": 11,
"widthInMillimeter": 11
},
"trackingData": {
"trackingId": "{{trackingId}}",
"carrier": "TNT",
"provider": "providerName",
"providerTransaction": "{{transactionId}}",
"isReturn": false
}
}
]
}

Remove Delivery

Produces the DeliveryRemoved Message.

action
String
"removeDelivery"
deliveryId
String

id of an existing Delivery.

Either deliveryId or deliveryKey must be provided.

deliveryKey
String

key of an existing Delivery.

Either deliveryId or deliveryKey must be provided.

Example: json
{
"action": "removeDelivery",
"deliveryId": "{{deliveryId}}"
}

Change ShipmentState

Produces the Order Shipment State Changed Message.

action
String
"changeShipmentState"
shipmentState

New shipment status of the Order.

Example: json
{
"action": "changeShipmentState",
"shipmentState": "Ready"
}

Add ReturnInfo

Produces the Return Info Added Message.

action
String
"addReturnInfo"
returnTrackingId
String

Value to set.

items
Array of ReturnItemDraft

Items to be returned. Must not be empty.

MinItems: 1
returnDate

Value to set. If not set, it defaults to the current date and time.

Example: json
{
"action": "addReturnInfo",
"items": [
{
"quantity": 1,
"lineItemId": "{{lineItemId}}",
"shipmentState": "Returned"
}
]
}

Set ReturnInfo

Produces the Return Info Set Message.

action
String
"setReturnInfo"
items
Array of ReturnInfoDraft

Value to set. If empty, any existing value is removed.

Example: json
{
"action": "setReturnInfo",
"items": [
{
"items": [
{
"quantity": 1,
"lineItemId": "{{lineItemId}}",
"comment": "any comment",
"shipmentState": "Returned"
}
],
"returnTrackingId": "returnTrackingId-example",
"returnDate": "2021-04-30T09:21:15.003Z"
}
]
}

Set ReturnShipmentState

To set a ReturnShipmentState, the Order returnInfo must have at least one ReturnItem.

Produces the Order Return Shipment State Changed Message.

action
String
"setReturnShipmentState"
returnItemId
String

id of the ReturnItem to update. Either returnItemId or returnItemKey is required.

returnItemKey
String

key of the ReturnItem to update. Either returnItemId or returnItemKey is required.

shipmentState

New shipment state of the ReturnItem.

Example: json
{
"action": "setReturnShipmentState",
"returnItemId": "{{returnItemId}}",
"shipmentState": "BackInStock"
}

Set ReturnPaymentState

To set a ReturnPaymentState, the Order returnInfo must have at least one ReturnItem.

action
String
"setReturnPaymentState"
returnItemId
String

id of the ReturnItem to update. Either returnItemId or returnItemKey is required.

returnItemKey
String

key of the ReturnItem to update. Either returnItemId or returnItemKey is required.

paymentState

New Payment status of the ReturnItem.

Example: json
{
"action": "setReturnPaymentState",
"returnItemId": "{{returnItemId}}",
"paymentState": "NotRefunded"
}

Change OrderState

Produces the Order State Changed Message.

action
String
"changeOrderState"
orderState

New status of the Order.

Example: json
{
"action": "changeOrderState",
"orderState": "Open"
}

Transition State

If the existing State has set transitions, there must be a direct transition to the new State. If transitions is not set, no validation is performed.

This update action produces the Order State Transition Message.

action
String
"transitionState"

Value to set. If there is no State yet, the new State must be an initial State.

force
Boolean

Set to true to turn off validation.

Default: false
Example: json
{
"action": "transitionState",
"state": {
"typeId": "state",
"id": "{{state-id}}"
}
}

Update SyncInfo

action
String
"updateSyncInfo"
externalId
String

Set this to identify an external order instance, file, or other resource.

The synchronization destination to set. Must not be empty. The referenced Channel must have the Channel Role OrderExport or OrderImport. Otherwise this update action returns an InvalidInput error.

syncedAt

If not set, it defaults to the current date and time.

Example: json
{
"action": "updateSyncInfo",
"channel": {
"typeId": "channel",
"id": "{{channel-id}}"
}
}

Set Locale

action
String
"setLocale"
locale

Value to set. Must be one of the Project's languages. If empty, any existing value is removed.

Example: json
{
"action": "setLocale",
"locale": "de-DE"
}

Set Store

Sets the Store the Order is assigned to. It should be used to migrate Orders to a new Store. No validations are performed (such as that the Customer is allowed to create Orders in the Store).

Produces the Order Store Set Message. Returns a 400 error if store references the same Store the Order is currently assigned to, including if you try to remove the value when no Store is currently assigned.

action
String
"setStore"

Value to set. If empty, any existing value is removed.

If store references the same Store the Order is currently assigned to or if you try to remove the value when no Store is currently assigned, a 400 error is returned.

Example: json
{
"action": "setStore",
"store": {
"key": "{{store-key}}",
"typeId": "store"
}
}

Set Custom Type

action
String
"setCustomType"

Defines the Type that extends the Order with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Order.

fields

Sets the Custom Fields fields for the Order.

Example: json
{
"action": "setCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set CustomField

action
String
"setCustomField"
name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action": "setCustomField",
"name": "ExampleStringTypeField",
"value": "TextString"
}

on LineItem

Set LineItem ShippingDetails

action
String
"setLineItemShippingDetails"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

shippingDetails

Value to set. If empty, the existing value is removed.

Example: json
{
"action": "setLineItemShippingDetails",
"lineItemId": "{{lineItemId}}",
"shippingDetails": {
"targets": [
{
"addressKey": "AddressKeyStringFromAddress",
"quantity": 2
}
]
}
}

Set LineItem Custom Type

action
String
"setLineItemCustomType"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

Defines the Type that extends the Line Item with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Line Item.

fields

Sets the Custom Fields fields for the Line Item.

Example: json
{
"action": "setLineItemCustomType",
"lineItemId": "{{lineItemId}}",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set LineItem CustomField

action
String
"setLineItemCustomField"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action": "setLineItemCustomField",
"lineItemId": "{{lineItemId}}",
"name": "ExampleStringTypeField",
"value": "TextString"
}

Transition LineItem State

Produces the Line Item State Transition Message.

action
String
"transitionLineItemState"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

quantity
Int

Number of Line Items that should transition State.

State the Line Item should transition from.

State the Line Item should transition to.

actualTransitionDate

Date and time (UTC) to perform the State transition.

Example: json
{
"action": "transitionLineItemState",
"lineItemId": "{{lineItemId}}",
"quantity": 3,
"fromState": {
"typeId": "state",
"id": "{{state-id}}"
},
"toState": {
"typeId": "state",
"id": "{{state-id}}"
}
}

Import LineItem State

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 Line Items states' quantities.

action
String
"importLineItemState"
lineItemId
String

id of the LineItem to update. Either lineItemId or lineItemKey is required.

lineItemKey
String

key of the LineItem to update. Either lineItemId or lineItemKey is required.

state
Array of ItemState

New status of the Line Items.

Example: json
{
"action": "importLineItemState",
"lineItemId": "{{lineItemId}}",
"state": [
{
"quantity": 5,
"state": {
"typeId": "state",
"id": "{{state-id}}"
}
}
]
}

on Custom LineItem

Set CustomLineItem ShippingDetails

action
String
"setCustomLineItemShippingDetails"
customLineItemId
String

id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

customLineItemKey
String

key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

shippingDetails

Value to set. If empty, any existing value is removed.

Example: json
{
"action": "setCustomLineItemShippingDetails",
"customLineItemId": "{{customLineItemId}}",
"shippingDetails": {
"targets": [
{
"addressKey": "{{addressKey}}",
"quantity": 2
}
]
}
}

Transition CustomLineItem State

Produces the Custom Line Item State Transition Message.

action
String
"transitionCustomLineItemState"
customLineItemId
String

id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

customLineItemKey
String

key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

quantity
Int

Number of Custom Line Items that should transition State.

State the Custom Line Item should transition from.

State the Custom Line Item should transition to.

actualTransitionDate

Date and time (UTC) to perform the State transition.

Example: json
{
"action": "transitionCustomLineItemState",
"customLineItemId": "{{customLineItemId}}",
"quantity": 6,
"fromState": {
"typeId": "state",
"id": "{{state-id}}"
},
"toState": {
"typeId": "state",
"id": "{{state-id}}"
}
}

Import CustomLineItem State

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 Custom Line Item states' quantities.

action
String
"importCustomLineItemState"
customLineItemId
String

id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

customLineItemKey
String

key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

state
Array of ItemState

New status of the Custom Line Items.

Example: json
{
"action": "importCustomLineItemState",
"customLineItemId": "{{customLineItemId}}",
"state": [
{
"quantity": 6,
"state": {
"typeId": "state",
"id": "{{state-id}}"
}
}
]
}

Set CustomLineItem Custom Type

action
String
"setCustomLineItemCustomType"
customLineItemId
String

id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

customLineItemKey
String

key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

Defines the Type that extends the Custom Line Item with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Custom Line Item.

fields

Sets the Custom Fields fields for the Custom Line Item.

Example: json
{
"action": "setCustomLineItemCustomType",
"customLineItemId": "{{customLineItemId}}",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set CustomLineItem CustomField

action
String
"setCustomLineItemCustomField"
customLineItemId
String

id of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

customLineItemKey
String

key of the CustomLineItem to update. Either customLineItemId or customLineItemKey is required.

name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action": "setCustomLineItemCustomField",
"customLineItemId": "{{customLineItemId}}",
"name": "ExampleStringTypeField",
"value": "TextString"
}

on Billing Address

Set Billing Address Custom Type

action
String
"setBillingAddressCustomType"

Defines the Type that extends the billingAddress with Custom Fields. If absent, any existing Type and Custom Fields are removed from the billingAddress.

fields

Sets the Custom Fields fields for the billingAddress.

Example: json
{
"action": "setBillingAddressCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set Billing Address CustomField

action
String
"setBillingAddressCustomField"
name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action": "setBillingAddressCustomField",
"name": "ExampleStringTypeField",
"value": "TextString"
}

on Shipping Address

Set Shipping Address Custom Type

action
String
"setShippingAddressCustomType"

Defines the Type that extends the shippingAddress with Custom Fields. If absent, any existing Type and Custom Fields are removed from the shippingAddress.

fields

Sets the Custom Fields fields for the shippingAddress.

Example: json
{
"action": "setShippingAddressCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set Shipping Address CustomField

action
String
"setShippingAddressCustomField"
name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action": "setShippingAddressCustomField",
"name": "ExampleStringTypeField",
"value": "TextString"
}

on ItemShipping Address

Set ItemShipping Address Custom Type

action
String
"setItemShippingAddressCustomType"
addressKey
String

key of the Address in itemShippingAddresses.

Defines the Type that extends the itemShippingAddress with Custom Fields. If absent, any existing Type and Custom Fields are removed from the itemShippingAddress.

fields

Sets the Custom Fields fields for the itemShippingAddress.

Example: json
{
"action": "setItemShippingAddressCustomType",
"addressKey": "{{address-key}}",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set ItemShipping Address CustomField

action
String
"setItemShippingAddressCustomField"
addressKey
String

key of the Address in itemShippingAddresses.

name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action": "setItemShippingAddressCustomField",
"addressKey": "{{address-key}}",
"name": "ExampleStringTypeField",
"value": "TextString"
}

on Delivery

Set Delivery Address

Produces the DeliveryAddressSet Message.

action
String
"setDeliveryAddress"
deliveryId
String

id of an existing Delivery.

Either deliveryId or deliveryKey must be provided.

deliveryKey
String

key of an existing Delivery.

Either deliveryId or deliveryKey must be provided.

address

Value to set. If empty, any existing value is removed.

Example: json
{
"action": "setDeliveryAddress",
"deliveryId": "{{deliveryId}}",
"address": {
"key": "exampleKey",
"title": "My Address",
"salutation": "Mr.",
"firstName": "Example",
"lastName": "Person",
"streetName": "Example Street",
"streetNumber": "4711",
"additionalStreetInfo": "Backhouse",
"postalCode": "80933",
"city": "Exemplary City",
"region": "Exemplary Region",
"state": "Exemplary State",
"country": "DE",
"company": "My Company Name",
"department": "Sales",
"building": "Hightower 1",
"apartment": "247",
"pOBox": "2471",
"phone": "+49 89 12345678",
"mobile": "+49 171 2345678",
"email": "email@example.com",
"fax": "+49 89 12345679",
"additionalAddressInfo": "no additional Info",
"externalId": "Information not needed"
}
}

Add Parcel to Delivery

To add a Parcel, at least one Delivery must exist.

Produces the Parcel Added To Delivery Message.

action
String
"addParcelToDelivery"
deliveryId
String

id of an existing Delivery.

Either deliveryId or deliveryKey must be provided.

deliveryKey
String

key of an existing Delivery.

Either deliveryId or deliveryKey must be provided.

parcelKey
String

key of an existing Parcel.

measurements

Value to set.

trackingData

Value to set.

items
Array of DeliveryItem

Value to set.

custom

Custom Fields for the Parcel.

Example: json
{
"action": "addParcelToDelivery",
"deliveryId": "{{deliveryId}}",
"measurements": {
"heightInMillimeter": 11,
"widthInMillimeter": 11
},
"trackingData": {
"trackingId": "{{trackingId}}",
"carrier": "TNT",
"provider": "providerName",
"providerTransaction": "{{transactionId}}",
"isReturn": false
},
"items": {
"id": "{{lineItemId}}",
"quantity": 2
}
}

Remove Parcel from Delivery

Produces the ParcelRemovedFromDelivery Message.

action
String
"removeParcelFromDelivery"
parcelId
String

id of an existing Parcel.

Either parcelId or parcelKey must be provided.

parcelKey
String

key of an existing Parcel.

Either parcelId or parcelKey must be provided.

Example: json
{
"action": "removeParcelFromDelivery",
"parcelId": "{{parcelId}}"
}

Set Delivery Items

Produces the Delivery Items Updated Message.

action
String
"setDeliveryItems"
deliveryId
String

id of an existing Delivery.

Either deliveryId or deliveryKey must be provided.

deliveryKey
String

key of an existing Delivery.

Either deliveryId or deliveryKey must be provided.

items
Array of DeliveryItem

Value to set. If empty, any existing value is removed.

Example: json
{
"action": "setDeliveryItems",
"deliveryId": "{{deliveryId}}",
"items": [
{
"id": "{{itemId}}",
"quantity": 2
}
]
}

Set Delivery Custom Type

action
String
"setDeliveryCustomType"
deliveryId
String

id of an existing Delivery.

Either deliveryId or deliveryKey must be provided.

deliveryKey
String

key of an existing Delivery.

Either deliveryId or deliveryKey must be provided.

Defines the Type that extends the Delivery with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Delivery.

fields

Sets the Custom Fields fields for the Delivery.

Example: json
{
"action": "setDeliveryCustomType",
"deliveryId": "exampleDeliveryID",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set Delivery CustomField

action
String
"setDeliveryCustomField"
deliveryId
String

id of an existing Delivery.

Either deliveryId or deliveryKey must be provided.

deliveryKey
String

key of an existing Delivery.

Either deliveryId or deliveryKey must be provided.

name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action": "setDeliveryCustomField",
"deliveryId": "exampleDeliveryID",
"name": "ExampleStringTypeField",
"value": "TextString"
}

on Parcel

Set Parcel Measurements

Produces the ParcelMeasurementsUpdated Message.

action
String
"setParcelMeasurements"
parcelId
String

id of an existing Parcel.

Either parcelId or parcelKey must be provided.

parcelKey
String

key of an existing Parcel.

Either parcelId or parcelKey must be provided.

measurements

Value to set. If empty, any existing value is removed.

Example: json
{
"action": "setParcelMeasurements",
"parcelId": "{{parcelId}}",
"measurements": {
"heightInMillimeter": 11,
"lengthInMillimeter": 11
}
}

Set Parcel Tracking Data

Produces the ParcelTrackingDataUpdated Message.

action
String
"setParcelTrackingData"
parcelId
String

id of an existing Parcel.

Either parcelId or parcelKey must be provided.

parcelKey
String

key of an existing Parcel.

Either parcelId or parcelKey must be provided.

trackingData

Value to set. If empty, any existing value is removed.

Example: json
{
"action": "setParcelTrackingData",
"parcelId": "{{parcelId}}",
"trackingData": {
"trackingId": "{{trackingId}}",
"carrier": "TNT",
"provider": "providerName",
"providerTransaction": "{{transactionId}}",
"isReturn": false
}
}

Set Parcel Items

Produces the ParcelItemsUpdated Message.

action
String
"setParcelItems"
parcelId
String

id of an existing Parcel.

Either parcelId or parcelKey must be provided.

parcelKey
String

key of an existing Parcel.

Either parcelId or parcelKey must be provided.

items
Array of DeliveryItem

Value to set. If empty, any existing value is removed.

Example: json
{
"action": "setParcelItems",
"parcelId": "{{parcelId}}",
"items": [
{
"id": "{{lineItemId}}",
"quantity": 2
}
]
}

Set Parcel Custom Type

action
String
"setParcelCustomType"
parcelId
String

id of an existing Parcel.

Either parcelId or parcelKey must be provided.

parcelKey
String

key of an existing Parcel.

Either parcelId or parcelKey must be provided.

Defines the Type that extends the Parcel with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Parcel.

fields

Sets the Custom Fields fields for the Parcel.

Example: json
{
"action": "setParcelCustomType",
"parcelId": "exampleParcelID",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set Parcel CustomField

action
String
"setParcelCustomField"
parcelId
String

id of an existing Parcel.

Either parcelId or parcelKey must be provided.

parcelKey
String

key of an existing Parcel.

Either parcelId or parcelKey must be provided.

name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action": "setParcelCustomField",
"parcelId": "exampleParcelID",
"name": "ExampleStringTypeField",
"value": "TextString"
}

on Delivery Address

Set Delivery Address Custom Type

action
String
"setDeliveryAddressCustomType"
deliveryId
String

id of an existing Delivery.

Either deliveryId or deliveryKey must be provided.

deliveryKey
String

key of an existing Delivery.

Either deliveryId or deliveryKey must be provided.

Defines the Type that extends the Delivery address with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Delivery address.

fields

Sets the Custom Fields fields for the Delivery address.

Example: json
{
"action": "setDeliveryAddressCustomType",
"deliveryId": "{{delivery-id}}",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set Delivery Address CustomField

action
String
"setDeliveryAddressCustomField"
deliveryId
String

id of an existing Delivery.

Either deliveryId or deliveryKey must be provided.

deliveryKey
String

key of an existing Delivery.

Either deliveryId or deliveryKey must be provided.

name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action": "setDeliveryAddressCustomField",
"deliveryId": "{{delivery-id}}",
"name": "ExampleStringTypeField",
"value": "TextString"
}

on ReturnItem

Set ReturnItem Custom Type

action
String
"setReturnItemCustomType"
returnItemId
String

id of the ReturnItem to update. Either returnItemId or returnItemKey is required.

returnItemKey
String

key of the ReturnItem to update. Either returnItemId or returnItemKey is required.

Defines the Type that extends the Return Item with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Return Item.

fields

Sets the Custom Fields fields for the Return Item.

Example: json
{
"action": "setReturnItemCustomType",
"returnItemId": "exampleReturnItemID",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set ReturnItem CustomField

action
String
"setReturnItemCustomField"
returnItemId
String

id of the ReturnItem to update. Either returnItemId or returnItemKey is required.

returnItemKey
String

key of the ReturnItem to update. Either returnItemId or returnItemKey is required.

name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action": "setReturnItemCustomField",
"returnItemId": "exampleReturnItemID",
"name": "ExampleStringTypeField",
"value": "TextString"
}

Delete Order

Delete Order by ID

Only Orders created for testing must be deleted.

If a DiscountCode with a maxApplications or maxApplicationsPerCustomer limit has been applied to the Order, the deleted Order is still counted towards that limit.

DELETE
https://api.{region}.commercetools.com/{projectKey}/orders/{id}

Deleting an Order produces the OrderDeleted Message.

OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Order.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
dataErasure
Boolean

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:
200Orderasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/orders/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Orderjson
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}

Delete Order by OrderNumber

Only Orders created for testing must be deleted.

If a DiscountCode with a maxApplications or maxApplicationsPerCustomer limit has been applied to the Order, the deleted Order is still counted towards that limit.

DELETE
https://api.{region}.commercetools.com/{projectKey}/orders/order-number={orderNumber}

Deleting an Order produces the OrderDeleted Message.

OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

orderNumber
String

orderNumber of the Order. Should be provided in URL-encoded format.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
dataErasure
Boolean

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:
200Orderasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/orders/order-number={orderNumber}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Orderjson
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}

Delete Order in Store

Delete Order in Store by ID

Only Orders created for testing must be deleted.

If a DiscountCode with a maxApplications or maxApplicationsPerCustomer limit has been applied to the Order, the deleted Order is still counted towards that limit.

DELETE
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders/{id}

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.

Deleting an Order produces the OrderDeleted Message.

OAuth 2.0 Scopes:
manage_orders:{projectKey} , manage_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

id
String

id of the Order.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
dataErasure
Boolean

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:
200Orderasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Orderjson
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}

Delete Order in Store by OrderNumber

Only Orders created for testing must be deleted.

If a DiscountCode with a maxApplications or maxApplicationsPerCustomer limit has been applied to the Order, the deleted Order is still counted towards that limit.

DELETE
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders/order-number={orderNumber}

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.

Deleting an Order produces the OrderDeleted Message.

OAuth 2.0 Scopes:
manage_orders:{projectKey} , manage_orders:{projectKey}:{storeKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

storeKey
String

key of the Store.

orderNumber
String

orderNumber of the Order. Should be provided in URL-encoded format.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
dataErasure
Boolean

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:
200Orderasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/orders/order-number={orderNumber}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Orderjson
{
"type": "Order",
"id": "92f5a867-bf19-47ab-982c-6720a03a3921",
"version": 1,
"createdAt": "2017-01-04T19:54:49.797Z",
"lastModifiedAt": "2017-01-04T19:54:49.797Z",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"orderState": "Open",
"syncInfo": [],
"returnInfo": [],
"refusedGifts": [],
"taxMode": "External",
"inventoryMode": "None",
"taxRoundingMode": "HalfEven",
"customerId": "7297c742-d8b0-484b-aadc-1d0ba6769dc9",
"businessUnit": {
"typeId": "business-unit",
"key": "ba-france-123"
},
"lineItems": [
{
"id": "7297c742-d8b0-484b-aadc-1d0ba1869dc9",
"productId": "c5c75935-595a-4cc3-a80e-24e9a9c55094",
"name": {
"en": "MyProduct"
},
"productType": {
"typeId": "product-type",
"id": "a5c7e173-9754-4f02-9b18-a600896ae0e1",
"version": 21
},
"productSlug": {
"de": "neues-produkt-slug-1234678",
"en": "new-product-slug-12345678"
},
"variant": {
"id": 1,
"sku": "some-sku-123",
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"id": "6d36dc85-6131-495d-9f20-d00f411d4124"
}
],
"images": [],
"attributes": [
{
"name": "text",
"value": "attribute-value"
},
{
"name": "enum",
"value": {
"key": "test",
"label": "test"
}
}
],
"assets": []
},
"price": {
"id": "6d36dc85-6131-495d-9f20-d00f411d4124",
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
}
},
"quantity": 1,
"discountedPricePerQuantity": [],
"taxRate": {
"name": "Bla",
"amount": 0.1,
"includedInPrice": false,
"country": "DE",
"subRates": []
},
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1000
},
"totalGross": {
"type": "centPrecision",
"fractionDigits": 2,
"currencyCode": "EUR",
"centAmount": 1100
}
},
"perMethodTaxRate": [],
"taxedPricePortions": []
}
],
"customLineItems": [],
"discountCodes": [],
"origin": "Customer",
"shipping": [],
"shippingMode": "Single"
}