Skip to main content

Order status

Status callback allows for updating the user app with his order fulfillment status. This improves user's shopping experience and likely eliminates direct contact with the store's customer service. See step 12 in the diagram:

Below is the list of order statuses available for merchants. Transition to a new status is executed by simply sending a new order status.

  • ORDERED denotes status of the order successfully placed by the user and received by the merchant's backend,
  • FULFILLED denotes status of the order picked and packed and ready for shipment,
  • SHIPPED denotes status of the order shipped to the user - either picked by the shipment operator or dispatched with merchant's own transport,
  • READY_FOR_PICKUP denotes status of the order delivered to the pickup location, either an APM or a merchant's own store,
  • DELIVERED denotes status of the order picked up by the user or delivered to his address,
  • CANCELLED_MERCHANT denotes status of the order that has been cancelled by the merchant regardless of the reason of the cancellation. This status is possible until status DELIVERED is set (either by merchant or OpenApp)

The logical flow of statuses is the following (every step of the status flow may be skipped):

NEW -> ORDERED -> FULFILLED -> SHIPPED -> READY_FOR_PICKUP -> DELIVERED

NEW -> ORDERED -> FULFILLED -> SHIPPED -> IN_DELIVERY -> DELIVERED

Order which is shipped in a single shipment​

Request​

A status update request is executed by a POST to the following endpoint:

POST {{OpenAppUrl}}/merchant/v1/orders/fulfillment

The request body contains information about the fulfillment status:

{
  "oaOrderId": "OA12345678901234",
  "shopOrderId": "WS1213ASDZXC231A",
  "status": "READY_FOR_PICKUP",
  "notes": "free text description",
  "shipping": {
    "operator": "INPOST_APM",
    "trackingCode": "z123",
    "trackingUrl": "https://example.invalid/tracking?c=z123"
  }
}

Response​

In reponse, OpenApp will confirm the status.

Errors​

Error nameCode
IncorrectDeliveryStatusException400
OrderNotFoundException404
MerchantOrderOwnershipException404

Order which is shipped in multiple shipments​

It is possible that an order will not be shipped in a single shipment, but in multiple shipments. To inform OpenApp about that, use the multi-fulfillment endpoint described here.

warning

Once you have split an order into multiple shipments, you can no longer use the endpoint for a single shipment. Additionally, every shipment you have ever created needs to be present in every call to the multi-fulfillment endpoint. So if you first split the delivery in 3 shipments, you have to keep updating the status with 3 shipments in the list. If you combine the order into 2 shipments again, you have to keep sending us 3 shipments (but you can of course indicate that the 3th shipment was cancelled).

Request​

A status update request is executed by a POST to the following endpoint:

POST {{OpenAppUrl}}/merchant/v1/orders/multiFulfillment

The request body contains information about the fulfillment status:

{
  "oaOrderId": "OA12345678901234",
  "shopOrderId": "WS1213ASDZXC231A",
  "shipments": [
    {
      "shipmentId": "hkkdf378723_1",
      "status": "READY_FOR_PICKUP",
      "notes": "free text description",
      "operator": "INPOST_APM",
      "trackingCode": "z123",
      "trackingUrl": "https://example.invalid/tracking?c=z123",
      "products": [
        {
          "id": "productxyz",
          "quantity": 5
        }
      ],
      "timing": "dec 1 - dec 2"
    },
    {
      "shipmentId": "hkkdf378723_2",
      "status": "FULFILLED"
    }
  ]
}

Response​

In response, OpenApp will confirm the status.

Errors​

Error nameCode
OrderNotFoundException404
MerchantOrderOwnershipException404