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:

sequenceDiagram
  autonumber
  actor User
  participant OpenApp
  participant Merchant
  Merchant->>User: show OpenApp widget
  User->>User: scan widget
  User->>+OpenApp: load basket
  OpenApp->>+Merchant: retrieve basket
  Merchant->>-OpenApp: send basket
  OpenApp->>User: send basket
  User->>+OpenApp: confirm
  OpenApp->>OpenApp: validate payment
  OpenApp->>+Merchant: place order
  Merchant->>-OpenApp: confirm
  OpenApp->>-User: confirm
  Merchant->>OpenApp: fulfillment callback
  OpenApp->>User: send notification

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

stateDiagram-v2
  state if_state2 <<choice>>
  [*] --> ORDERED
  ORDERED --> FULFILLED
  FULFILLED --> SHIPPED
  SHIPPED --> if_state2
  if_state2 --> READY_FOR_PICKUP: APM or store pick-up
  if_state2 --> IN_DELIVERY: door delivery
  READY_FOR_PICKUP --> DELIVERED
  IN_DELIVERY --> DELIVERED
  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:

Example responseSchema

Fulfillment update request
{
  "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"
  }
}

Fulfillment update request

{
    "additionalProperties": false,
    "type": "object",
    "properties": {
        "oaOrderId": {
            "type": "string",
            "title": "oaOrderId"
        },
        "shopOrderId": {
            "type": "string",
            "title": "shopOrderId"
        },
        "status": {
            "$ref": "#/definitions/StoreDeliveryStatus",
            "title": "status"
        },
        "notes": {
            "type": "string",
            "title": "notes"
        },
        "shipping": {
            "additionalProperties": false,
            "$ref": "#/definitions/OrderShipment",
            "title": "shipping"
        }
    },
    "required": [
        "notes",
        "oaOrderId",
        "shopOrderId",
        "status"
    ],
    "definitions": {
        "StoreDeliveryStatus": {
            "title": "StoreDeliveryStatus",
            "enum": [
                "CANCELLED_MERCHANT",
                "DELIVERED",
                "FULFILLED",
                "IN_DELIVERY",
                "ORDERED",
                "READY_FOR_PICKUP",
                "SHIPPED"
            ],
            "type": "string"
        },
        "OrderShipment": {
            "additionalProperties": false,
            "title": "OrderShipment",
            "type": "object",
            "properties": {
                "operator": {
                    "description": "The operator of the shipment",
                    "maxLength": 64,
                    "type": "string",
                    "title": "operator"
                },
                "trackingCode": {
                    "description": "The tracking code.",
                    "maxLength": 64,
                    "type": "string",
                    "title": "trackingCode"
                },
                "trackingUrl": {
                    "description": "The tracking URL.",
                    "maxLength": 255,
                    "type": "string",
                    "title": "trackingUrl"
                }
            }
        }
    },
    "$schema": "http://json-schema.org/draft-07/schema#"
}

Response¶

In reponse, OpenApp will confirm the status.

Errors¶

Error name	Code
`IncorrectDeliveryStatusException`	400
`OrderNotFoundException`	404
`MerchantOrderOwnershipException`	404

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).