Pick

Once a fulfillment order is allocated to a location, its line items are ready to pick. Carriyo records that work as 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.

Carriyo creates picks automatically when auto_create_picks is on for the location (a Fulfillment App setting). You can also create them via the API.

The model

A pick carries:

• pick_id. Unique identifier, prefixed PIK_ (e.g. PIK_142).
• partner_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. Bin identifiers where the SKU is stored at the location. Resolved from the location's bin locations at pick creation.
• 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.

The picking workflow

A typical pick workflow follows these steps:

1. Create the pick with the line items to pick, or let Carriyo create it (see Auto-creation below).
2. Assign a picker (at creation, through the assignment setting, or via reassign).
3. Start the pick.
4. Pick items as the picker collects them, in one or more calls.
5. Mispick items that can't be picked, with a quantity and a reason.
6. Restock items picked in error, if needed.
7. Complete the pick once every item is picked or mispicked, or cancel it.

Picking, mispicking and restocking need the pick to be processing; restocking also works on a stopped pick. A quantity above what is left to pick, mispick or restock is rejected, and nothing in that call is saved. No pick operation sends a webhook, so poll the order or read the pick to follow progress.

Effect on fulfillment-order line items

Pick operations change 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)	pick_in_progress → picked, with the quantity reduced to the picked amount. The mispicked remainder is dropped.
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 (ends cancelled)	pick_in_progress → allocated
Pick cancelled (ends stopped)	No change.

The fulfillment order's own status (open, allocated, processing, fulfilled, cancelled, closed) is recomputed from its line items after each pick event. It is processing while any line item is pick_in_progress, picked, or pack_in_progress, and the order is processing while any of its fulfillment orders is.

Pick types

Carriyo determines the pick type from the items you include:

• ORDER_PICK. All items belong to a single fulfillment order, whether or not the pick covers all of its items.
• CLUSTER_PICK. Items span several fulfillment orders, and every one of them is fully included.
• ZONE_PICK. Items span several fulfillment orders, and at least one is only partly included.

Two Fulfillment App settings, set per tenant and per location, govern what a pick may include. With cluster_picking_enabled off, a pick with more than one fulfillment order is refused. With split_picking_enabled off, a pick must include every non-terminal line item of each fulfillment order it touches, single-order picks included.

Picker assignment

When a pick is created without a picker, Carriyo follows the picker_assignment_strategy setting:

• manual. The default. Leaves the pick unassigned; you assign one via the reassign endpoint while the pick is open.
• round_robin. Not implemented yet. Behaves like manual and leaves the pick unassigned.
• work_load. Assigns the least-loaded eligible picker.

The setting is a Fulfillment App setting, per tenant and per location. 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 reduced to the picked amount. The mispicked remainder is dropped: no cancelled line item is created for it, nothing returns to allocated, and the order line is left unchanged.

If items are picked in error, the restock action (available while the pick is processing or stopped) decrements quantity_picked.

Auto-creation

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

1. Order creation. After the order is saved, for fulfillment orders with allocated line items at that location.
2. Allocation. When a fulfillment order is allocated to the location.
3. Location update. When a fulfillment order that had no location is given one.

Auto-created picks are ORDER_PICK type, one per fulfillment order, covering its allocated line items. Orders on hold are skipped.

Cascade cancellation

When an order is cancelled, Carriyo cancels its picks. When every line item of a fulfillment order is cancelled, Carriyo cancels that fulfillment order's picks. A processing pick with picked units becomes stopped rather than cancelled. Cancelling line items sends an order webhook for the cancellation; the pick changes it causes send none.

Active picks block certain fulfillment-order operations: you cannot merge, split, update the location, or update the partner references of a fulfillment order while it has an open, processing, or stopped pick.

Lookup endpoints vs full record

The list endpoints (/orders/picks/order/{orderId} and /orders/picks/fulfillment-order/{foId}) return only pick_id, tenant, partner_location_id, status and creation_date per pick; use GET /orders/picks/{pickId} for 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.