githubEdit

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.

circle-check

Prerequisites

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:

1

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

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.

2

Submit the picked quantities

Using the same action endpoint, update the picked quantities.

POST /api/pickjobs/{pickJobId}/actions

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