Headless picking

Headless picking refers to managing the pick job lifecycle entirely through the fulfillmenttools API, without using the fulfillmenttools Operations app. This approach is typically chosen by retailers or logistics operators who already have their own warehouse or store fulfillment applications and want to integrate fulfillmenttools as the backend order management engine while keeping their existing frontend experience for store or warehouse staff.

In this setup, your custom application is responsible for guiding pickers through the fulfillment process: displaying items to pick, capturing the quantities picked, and reporting results via the API. fulfillmenttools handles the underlying inventory logic, stock reservations, and order orchestration.

Prerequisites

Before implementing headless picking, ensure the following are in place:

Orders: Orders must be created and managed through fulfillmenttools. Pick jobs are generated automatically when an order is assigned to a facility, so order creation is a hard dependency.
Pick jobs: Your integration must be able to interact with the pick job resource via the fulfillmenttools API (/api/pickjobs). This includes reading pick job data and updating statuses and line items as described in this guide.

When an order is created and assigned to a facility, fulfillmenttools automatically generates a pick job and reduces available stock by creating a reservation.

Once your facility has physically picked the items, follow these steps via API to complete the process:

Set the pick job to IN_PROGRESS

Using the pick job action endpoint, use the name START to set the pick job to IN_PROGRESS.

Setting the status to IN_PROGRESS triggers the system to fetch the latest stock data and populate the stockRef values inside partialStockLocations for each pick line item.

POST /api/pickjobs/{pickJobId}/actions

{
  "id": "019cc21a-3b14-7538-b293-26ad30c24317",
  "version": 2,
  "created": "2026-03-06T08:00:00.000Z",
  "lastModified": "2026-03-06T08:05:00.000Z",
  "shortId": "AB42",
  "status": "IN_PROGRESS",
  "facilityRef": "Esb20gpHBL94X5NdMp3C",
  "orderRef": "LGMl2DuvPnfPoSHhYFOm",
  "tenantOrderId": "R456728546",
  "orderDate": "2026-03-06T07:50:00.000Z",
  "deliveryinformation": {
    "channel": "SHIPPING",
    "targetTime": "2026-03-07T12:00:00.000Z"
  },
  "pickLineItems": [
    {
      "id": "019cc21a-3b14-7538-b293-26ad30c24317",
      "status": "OPEN",
      "quantity": 1,
      "picked": 0,
      "article": {
        "tenantArticleId": "ART-001",
        "title": "Blue Running Shoe (Size 42)"
      },
      "partialStockLocations": [
        {
          "stockRef": "stock-7f3a1b29-e4dc-4e8a-bc12-0f5a93d1e847",
          "tenantPartialStockId": "STOCK-001",
          "quantity": 1,
          "available": 5
        }
      ]
    }
  ],
  "documentsRef": []
}

The response already contains the updated stockRef values inside partialStockLocations for each pick line item. No separate GET request is needed.

Understanding partialStockLocations:

A pick line item can have multiple partialStockLocations, each representing a stock from which the item could potentially be picked
The stock with the active reservation will have quantity set to the reserved amount
All other stocks will have quantity: 0
Use the stockRef of the entry with a non-zero quantity when submitting picked quantities in the next step

The sum of all picked pick line items must be 0 to trigger fetching the latest stock data. This is the case for newly created pick jobs via an order. You can also achieve this by restarting a pick job. If the sum isn't 0, we assume the pick job has already started. It's the user's responsibility to ensure the stock information remains correct.

Submit the picked quantities

Using the same action endpoint, update the picked quantities.

POST /api/pickjobs/{pickJobId}/actions

{
  "lineItems": [
    {
      "id": "019cc21a-3b14-7538-b293-26ad30c24317",
      "partialStockLocations": [
        {
          "picked": 1,
          "stockRef": "stock-7f3a1b29-e4dc-4e8a-bc12-0f5a93d1e847",
          "tenantPartialStockId": "STOCK-001"
        }
      ],
      "picked": 1,
      "pickedAt": "{{$isoTimestamp}}" //optional
    }
  ],
  "name": "PICK",
  "version": 2
}

picked must be set on both the root level of the line item update and inside each partialStockLocations entry.

Root level: total quantity picked for the line item
Inside partialStockLocations: quantity taken from that specific stock

If the picked value is missing or zero at the partialStockLocations level, no stock will be deducted from inventory.

{
  "id": "019cc21a-3b14-7538-b293-26ad30c24317",
  "version": 3,
  "created": "2026-03-06T08:00:00.000Z",
  "lastModified": "2026-03-06T08:05:00.000Z",
  "shortId": "AB42",
  "status": "PICKED",
  "facilityRef": "Esb20gpHBL94X5NdMp3C",
  "orderRef": "LGMl2DuvPnfPoSHhYFOm",
  "tenantOrderId": "R456728546",
  "orderDate": "2026-03-06T07:50:00.000Z",
  "deliveryinformation": {
    "channel": "SHIPPING",
    "targetTime": "2026-03-07T12:00:00.000Z"
  },
  "pickLineItems": [
    {
      "id": "019cc21a-3b14-7538-b293-26ad30c24317",
      "status": "CLOSED",
      "quantity": 1,
      "picked": 1,
      "pickedAt": "{{$isoTimestamp}}",
      "article": {
        "tenantArticleId": "ART-001",
        "title": "Blue Running Shoe (Size 42)"
      },
      "partialStockLocations": [
        {
          "stockRef": "stock-7f3a1b29-e4dc-4e8a-bc12-0f5a93d1e847",
          "tenantPartialStockId": "STOCK-001",
          "quantity": 1,
          "available": 5
        }
      ]
    }
  ],
  "documentsRef": []
}

What happens after submission:

The pick job status is automatically set to PICKED.
If all picked quantities match the ordered quantities, no rerouting is needed, and the pick job transitions to CLOSED automatically (asynchronously).
Once CLOSED, picked quantities are deducted from stock, and reservations are removed. No manual adjustment is needed.
If picked is 0 for all line items, the pick job will be set to ABORTED.
If the picked quantities are less than the ordered quantity (short-pick), the pick job will either be REROUTED or CLOSED, depending on your configuration.

An example flow of this process is below, where the numbers represent the steps above.

Last updated 8 days ago

hashtagPrerequisites

Prerequisites