Locked Orders

There are use-cases where not every order should be fulfilled as soon as possible. In some cases it might me necessary to do some manual checks on an order, e.g. customer verification or fraud detect

This is where a "locked" order comes in plance. Locked orders are routed to a facility but do not result in a pickjob until they are unlocked. The unlocking can be done manually via the backoffice or via API.

Since a locked order does not create a pickjob such an order is not effected by a time triggered reroute.

Create locked Orders

Here's an example on how to create a Click-and-Collect order:

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/orders' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "consumer": {
    "addresses": [
      {
        "salutation": "Mr.",
        "firstName": "Test",
        "lastName": "Customer",
        "street": "Domstr.",
        "houseNumber": "20",
        "postalCode": "50668",
        "city": "Köln",
        "country": "DE"
      }
    ],
    "email": "[e-mail]"
  },
  "orderDate": "2023-03-06T17:30:00Z",
  "status": "LOCKED",
  "statusReasons": [{
        "status": "LOCKED",
        "reason": "Fraud check necessary."
  }],
  "tenantOrderId": "order-111",
  "customAttributes": {
    "someInternalId": "xyz-123"
  },
  "deliveryPreferences": {
    "targetTime": "2023-03-08T14:00:00Z",
    "collect": [
      {
        "paid": true,
        "facilityRef": "<facility-id>"
      }
    ]
  },
  "orderLineItems": [
    {
      "quantity": 2,
      "article": {
        "tenantArticleId": "111222333",
        "title": "T-Shirt",
        "imageUrl": "https://loremflickr.com/320/240/shirt",
        "attributes": [
          {
            "key": "%%subtitle%%",
            "value": "Super Brand",
            "category": "descriptive",
            "priority": 100
          },
          {
            "key": "Color",
            "value": "white",
            "category": "descriptive",
            "priority": 101
          },
          {
            "key": "Size",
            "value": "M",
            "category": "descriptive",
            "priority": 102
          }
        ]
      },
      "scannableCodes": [
        "5714500878421"
      ],
      "customAttributes": {
        "someInternalId": "0815"
      }
    }
  ]
}'

Some details on the example:

• A locked order has the same details and properties as a order that should be fulfilled the standard way.

• The status is LOCKED which means, that there are no further operational entities, e.g. pick jobs are created.

• In the optional statusReasons, you can set a reason per status you set the order in.

Unlock locked orders

To unlock an order, call the orders action UNLOCK:

curl -sSL -X POST 'https://ocff-weirdweasel-git.api.fulfillmenttools.com/api/orders/YOUR-ORDER-ID/actions' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "UNLOCK",
    "version": 1
}'

Order Events

ORDER_CREATED

If you have subscribed to ORDER_CREATED webhook events as described in the Eventing tutorial, your service will be notified when a new order has been created. You can evaluate the information from this event, e.g. to start other business processes.

The OrderCreatedWebHookEvent has all the details about the order:

{
  "event": "ORDER_CREATED",
  "eventId": "4395488122884786",
  "payload": {
    "id": "287ce844-fb3d-43f1-bc52-d667db8cbbb5",
    "status": "OPEN",
    "tenantOrderId": "abc-111",
    "processId": "2c4a43f2-7f69-40df-9cef-e8665012ec73",
    …
  }
}

As you can see here, the status is LOCKED, so, evaluating the status field you can subscribe on the creation of locked orders.

ORDER_UNLOCKED

The is an ORDER_UNLOCKED event you can subscribed to to receive notifications, when an order is manually unlocked and ready for fulfillment.

The OrderUnlockedWebHookEvent also contains all the details about the order:

{
  "event": "ORDER_UNLOCKED",
  "eventId": "4395488122884786",
  "payload": {
    "id": "287ce844-fb3d-43f1-bc52-d667db8cbbb5",
    "status": "OPEN",
    "tenantOrderId": "abc-111",
    "processId": "2c4a43f2-7f69-40df-9cef-e8665012ec73",
    …
  }
}

The status (previously LOCKED) is now OPEN.

Reference

• Full specification of the orders endpoint in our fulfillmenttools API

• Specification of the unlock endpoint: fulfillmenttools API - Unlock order