Pick

When a fulfillment order is allocated to a warehouse, Carriyo creates a Pick: a unit of picking work that tells an operator which items to collect from the shelves. A single pick covers one or more line items, and the operator progresses it from open through to completed as they walk the floor.

Picks can be created automatically by the Fulfillment App when auto_create_picks is enabled on the location. You can also create them manually via the API.

The model

A pick carries:

• pick_id. Unique identifier, prefixed PIK_ (e.g. PIK_142).
• location_id. The fulfillment location the work belongs to.
• picker. The user assigned to the work.
• pick_type. How Carriyo classified the pick: ORDER_PICK, CLUSTER_PICK, or ZONE_PICK (see below).
• status. The lifecycle state.
• items. The line items in the pick, with picking progress.
• documents. Attached files, typically the auto-generated pick-list PDF.

Each pick item carries product metadata copied from the fulfillment-order line item at creation, plus the picking progress:

• quantity and quantity_picked. Total requested versus collected so far.
• bin_locations. Warehouse bin identifiers where the SKU is stored. Resolved from the location's bin-location mappings at pick creation.
• selection_method. How the operator confirmed the item: SCANNER (barcode scan), CAMERA (photo recognition), or MANUAL.
• mispicks. Any quantity that couldn't be picked, with a free-text reason.
• Product fields: sku, description, barcode, image_link, weight, unit_price, origin_country, hs_code, dangerous_goods.

Pick lifecycle

open ──start──▶ processing ──complete──▶ completed  (terminal)
  │                  │
  │                  ├── cancel (no items picked) ──▶ cancelled
  │                  └── cancel (items picked) ──▶ stopped ──cancel──▶ cancelled
  │
  └── cancel ──▶ cancelled  (terminal)

Status	Meaning
open	Created, waiting for the picker to start.
processing	The picker is actively working the floor.
stopped	Cancelled mid-flow while items were partially picked. Can be cancelled again to fully cancel.
completed	All items accounted for; handed over to packing. Terminal.
cancelled	Voided. All line items revert to allocated. Terminal.

Status transitions

From	To	Trigger
open	processing	POST /orders/picks/{pickId}/start. Requires a picker to be assigned.
open	cancelled	POST /orders/picks/{pickId}/cancel.
processing	completed	POST /orders/picks/{pickId}/complete. All items must be fully accounted for (picked + mispicked = quantity).
processing	cancelled	Cancel when no items have been picked yet.
processing	stopped	Cancel when some items have been picked.
stopped	cancelled	Cancel again to fully cancel and revert line items.

Effect on fulfillment-order line items

Pick operations drive the fulfillment-order line-item status. These side effects happen automatically; you don't need to update the fulfillment order separately.

Pick event	Line-item status change
Pick created	allocated → pick_in_progress. If the pick covers a partial quantity, the line item is split.
Pick completed (item fully picked)	pick_in_progress → picked
Pick completed (item partially picked with mispicks)	picked (quantity adjusted to picked amount)
Pick completed (item fully mispicked, zero picked)	Line item cancelled
Pick completed (all items fully mispicked)	Pick becomes cancelled instead of completed; all line items revert to allocated
Pick cancelled	pick_in_progress → allocated
Restock action	If line item was picked, reverts to pick_in_progress

The fulfillment order's own status (open, allocated, processing, fulfilled, cancelled, closed) is recomputed from its line items after each pick event. When any line item is pick_in_progress or picked, the fulfillment order moves to processing.

Pick types

Carriyo determines the pick type from the items you include:

• ORDER_PICK. The default. All items belong to a single fulfillment order.
• CLUSTER_PICK. Items span multiple fulfillment orders, all fully included in the pick. Requires cluster_picking_enabled on the location's Fulfillment App settings.
• ZONE_PICK. Items span multiple fulfillment orders, but only a subset of each FO's items is included. Requires split_picking_enabled.

Picker assignment

When a pick is created, Carriyo assigns a picker based on the configured strategy:

• work_load. Assigns to the picker with the fewest active picks. The default strategy.
• round_robin. Cycles through available pickers in order.
• manual. Leaves the pick unassigned. An operator claims it from the Fulfillment App, or you assign one via the reassign endpoint.

The strategy is set per location in the Fulfillment App settings. Pickers must have pick permission for the location.

Mispicks

If an operator can't pick what's on the list (out of stock, damaged, wrong item in the bin), they record a mispick with a quantity and a free-text reason.

At completion, items that are fully mispicked (zero picked, all mispicked) are cancelled. Items with a mix of picked and mispicked quantities have their quantity adjusted to the picked amount.

If items are picked in error, the restock action decrements quantity_picked and returns items to the available pool.

Auto-creation

When auto_create_picks is enabled in the Fulfillment App settings for a location, Carriyo auto-creates picks at three points:

1. Order creation. After the order is saved, if fulfillment orders have allocated line items at a location with auto-create enabled.
2. Allocation. When a fulfillment order is allocated to a location.
3. Location update. When a fulfillment order's location is changed to one with auto-create enabled.

Auto-created picks are ORDER_PICK type, covering all allocated line items in the fulfillment order.

Cascade cancellation

When an order is cancelled, Carriyo cancels all active picks for that order. When a fulfillment order is fully cancelled, Carriyo cancels all active picks for that fulfillment order.

Active picks block certain fulfillment-order operations: you cannot merge, split, or update the location of a fulfillment order while it has an active (non-terminal) pick.

Lookup endpoints vs full record

The list endpoints (/orders/picks/order/{orderId} and /orders/picks/fulfillment-order/{foId}) return lookup records with only summary fields: pick_id, tenant, location_id, status, and creation_date. They do not include items, documents, or detailed timestamps.

Use GET /orders/picks/{pickId} to retrieve the full record.

How it fits with other modules

• Fulfillment. The parent module.
• Pack. The next stage; picked items move into the pack stage.
• Fulfillment orders. The unit of work the Pick draws from.
• Fulfillment App. The app that creates and progresses Picks for warehouse operators.