Skip to main content

Orders

The Orders-V4 interface allows you to view orders and associated position items. You can send cancellations on order and position item level.

Fulfillment States​

A position item can stay in different fulfillment states (attribute: fulfillmentStatus):

  • ANNOUNCED
    An ordered position item which shall be reserved for the customer but shall not be shipped yet. The position item can still be cancelled by the marketplace and the customer. The address of the customer is not visible in this state.
  • PROCESSABLE
    This position item is ready to be fulfilled.
  • SENT
    This position item was shipped. It was processed by the Shipments interface.
  • RETURNED
    This position item was returned. It was processed by the Returns interface.
  • CANCELLED_BY_PARTNER
    This position item was cancelled by the partner and won't be processed any further.
  • CANCELLED_BY_MARKETPLACE
    This position item was cancelled by the marketplace and won't be processed any further. In case of a partner termination all position items in state ANNOUNCED or PROCESSABLE will be cancelled.

Possible State Transitions​

Fulfillment status transitions

The position item states determine the whole order's lifecycle state:

  • The order will be classified as ANNOUNCED, PROCESSABLE, SENT, or RETURNED if at least one position item is in an analogous state and all other position items have the same or higher state according to above-mentioned list.
  • The order will also be classified as CANCELLED_BY_MARKETPLACE or CANCELLED_BY_PARTNER if it has at least one position item in fulfillment state CANCELLED_BY_MARKETPLACE resp. CANCELLED_BY_PARTNER.

The latest lifecycle change is recorded in order attribute lifecycleChangeDate. You can choose to query by lifecycle state or position item state by using the mode

Cancellation​

Position items of an order can be cancelled. These position items must be in state PROCESSABLE or ANNOUNCED.
Partner cancellations in general lead to customer dissatisfaction and should be avoided.

Cancellation is possible for only a single position item or the whole order:

  • to cancel a single position item send a POST request /v4/orders/{salesOrderId}/positionItems/{positionItemId}/cancellation
  • to cancel the whole order send a POST request /v4/orders/{salesOrderId}/cancellation

Every position item which is in fulfillment status PROCESSABLE or ANNOUNCED will be changed to CANCELLED_BY_PARTNER. If there was a cancellation request from the customer the cancellationReason will be set to CANCELLED_ON_CUSTOMER_WISH

The cancellation operations might take a moment until the result is visible on a subsequent fetch request. Conflicts will be reported in an error response.

Common Use Cases​

Fetch open orders​

Orders can be constantly created. After the payment confirmation orders change to state PROCESSABLE. Orders can be fetched individually by salesOrderId/ orderNumber or as a list by using different filter criteria. To fetch orders after they became processable this REST call can be used

GET /v4/orders?fulfillmentStatus=PROCESSABLE

If there is a next link it can be followed until there are no new orders. To start at a certain date the fromDate can be used, which relates to the lifecycleChangeDate, which in this case is when order became PROCESSABLE.

GET /v4/orders?fulfillmentStatus=PROCESSABLE&orderColumnType=ORDER_LIFECYCLE_DATE&fromDate=2023-07-01T00:00:00Z

This works in a similar way for other status and combinations, for example

GET /v4/orders?fulfillmentStatus=PROCESSABLE,SENT

Fetch all orders for a day​

GET /v4/orders?fromOrderDate=2023-07-01T00:00:00Z&toOrderDate=2023-07-02T00:00:00Z&orderColumnType=ORDER_DATE

The next link can be followed until there are no orders left.

Fetch all orders with returned positions​

To fetch orders with at least one returned position the following query can be used

GET /v4/orders?fulfillmentStatus=RETURNED&mode=AT_LEAST_ONE&orderColumnType=LAST_MODIFIED_DATE&fromDate=2023-07-01T00:00:00Z

Fetch a single order​

By salesOrderId

GET /v4/orders/82f3e02f-2f56-448d-8f3b-d42f5a475119

By orderNumber

GET /v4/orders/v8pnyhq2nh

Performance Hints​

There can be a lot of combinations of parameters for the API which will result in varying response times. For best performance results try to use either fromDate or fromOrderDate/ toOrderDate, not both at the same time. Furthermore, the right orderColumnType can improve search performance.

  • The default orderColumnType, orderColumnType=ORDER_LIFECYCLE_DATE or orderColumnType=LAST_MODIFIED_DATE works best with fromDate
  • orderColumnType=ORDER_DATE works best with fromOrderDate/ toOrderDate.

For quicker results or with fewer data expected, a smaller limit could be used. The default limit is 128.

Pagination​

Paging will occur if the number of returned orders exceeds the current limit (request parameter limit).

Example​

{
      "resources": [
        { 
          ...
        }
        ...
      ],
      "links": [
        {
          "href": "/v4/orders?nextcursor=eyJmZiI6MTY4ODU0Mzk5MDUxMCwicGlmIjoiMTAwNjI1MCIsIm0iOiJCVUNLRVQiLCJvY3QiOiJPUkRFUl9MSUZFQ1lDTEVfREFURSIsIm9kIjoiQVNDIiwic3RmIjoic2FsZXNPcmRlcklkIiwibHNvaSI6ImUxM2IwYTMyLWU1ZTMtNDEwYi05YWQ2LTliZWRlY2MwNzVjNiIsInNvaWNyIjpmYWxzZX0",
          "rel": "next"
        }
      ]
}

Using /v4/orders?nextcursor=eyJmZiI6MTY4ODU0Mzk5MDUxMCwicGlmIjoiMTAwNjI1MCIsIm0iOiJCVUNLRVQiLCJvY3QiOiJPUkRFUl9MSUZFQ1lDTEVfREFURSIsIm9kIjoiQVNDIiwic3RmIjoic2FsZXNPcmRlcklkIiwibHNvaSI6ImUxM2IwYTMyLWU1ZTMtNDEwYi05YWQ2LTliZWRlY2MwNzVjNiIsInNvaWNyIjpmYWxzZX0 here would receive the next slice of records; a missing next link indicates no further records.

Cancellation​

Position items of an order can be cancelled. These position items must be in state PROCESSABLE or ANNOUNCED.
Partner cancellations in general lead to customer dissatisfaction and should be avoided.

Cancellation is possible for only a single position item or the whole order:

  • to cancel a single position item send a POST request /v4/orders/{salesOrderId}/positionItems/{positionItemId}/cancellation
  • to cancel the whole order send a POST request /v4/orders/{salesOrderId}/cancellation

Every position item which is in fulfillment status PROCESSABLE or ANNOUNCED will be changed to CANCELLED_BY_PARTNER. If there was a cancellation request from the customer the cancellationReason will be set to CANCELLED_ON_CUSTOMER_WISH

The cancellation operations might take a moment until the result is visible on a subsequent fetch request. Conflicts will be reported in an error response.

Glossary​

  • Sales Order - The sales order is a customer's order with items from different partners.
  • Order Number - The order number is a unique identifier for a sales order knows from customer.
  • Partner Order - The partner order refers to a customer's order containing only the positions of a single partner.
  • Position Item - The position item is the physical product a customer has ordered. A checkout with a product quantity greater than one will produce unique position items within the partner order.

ON THIS PAGE