Fulfillment API

Creates a pick work order for one or more fulfillment-order line items at a single location.

When to use this

Call this when you want to create a pick manually. In many setups the Fulfillment App auto-creates picks on allocation (when auto_create_picks is enabled in the location's Fulfillment App settings), so a manual create is only needed when auto-creation is off or when you want fine-grained control over which items go into which pick.

Behavior

Carriyo determines the pick type from the items you supply:

On success, Carriyo:

1. Moves each referenced fulfillment-order line item from allocated to pick_in_progress. If the requested quantity is less than the line item's total, the line item is split: the original keeps the remaining quantity as allocated, and a new line item is created with the requested quantity as pick_in_progress.
2. Assigns a picker (if not provided in the request, assignment uses the configured strategy: work_load or manual).
3. Generates a pick list document (PDF) attached to the pick.

Validation

• location_id is required. All items must belong to fulfillment orders at this location.
• At least one item is required.
• Each line item must be in allocated status.
• Each line item must not already belong to another active (non-terminal) pick.
• quantity must not exceed the line item's available allocated quantity.
• If picker is provided, the user must have pick permission for the location.

Returns the full pick record, including all items, documents, and timestamps.

Use this endpoint when you need the complete pick data. The list endpoints (/order/{orderId}, /fulfillment-order/{foId}) return lookup records with only summary fields (pick_id, location_id, status, creation_date); they do not include items, documents, or detailed timestamps.

Returns all picks associated with an order.

These are lookup records containing only summary fields: pick_id, tenant, location_id, status, and creation_date. To get the full pick (items, documents, timestamps), call Get pick with the pick_id.

Returns all picks associated with a fulfillment order.

These are lookup records containing only summary fields: pick_id, tenant, location_id, status, and creation_date. To get the full pick (items, documents, timestamps), call Get pick with the pick_id.

Transitions the pick from open to processing. The picker is now walking the floor.

Validation

• The pick must be in open status.
• A picker must already be assigned (set at creation or via Reassign pick).

No request body is required.

Cancels the pick. The outcome depends on the current status and whether any items have been picked.

Behavior

A stopped pick means items were partially picked and the pick was cancelled mid-flow. You can cancel a stopped pick again to fully cancel it and revert line items.

Picks in completed or cancelled status cannot be cancelled.

The request body is optional. If provided, reason_code is stored on the pick for auditing.

Reassigns the pick to a different picker.

Validation

• The pick must be in open status.
• The new picker must have pick permission for the pick's location.

Completes the pick and hands it over to packing. This is the handover step.

Validation

• The pick must be in processing status.
• Every item must be fully accounted for: quantity_picked + sum(mispick quantities) == quantity for each item.

Behavior

On completion, Carriyo updates each fulfillment-order line item based on what was picked:

If every item in the pick has quantity_picked = 0 (all mispicked), the pick status becomes cancelled instead of completed, and all line items revert to allocated.

No request body is required.

Records that the picker has collected items from the shelf. Call this incrementally as the picker works through the list.

Behavior

For each item in the request, Carriyo increments quantity_picked on the matching pick item. The fulfillment-order line items stay in pick_in_progress until you call Complete pick.

You can call this endpoint multiple times. Each call adds to the running total.

Validation

• The pick must be in processing status.
• Each item must exist in the pick (matched by fulfillment_order_id + line_item_id).
• quantity must not exceed item.quantity - item.quantity_picked - sum(mispick quantities).

Reverses a previous pick action, putting items back on the shelf. Use this when items were picked in error.

Behavior

Decrements quantity_picked on each matching pick item. If the fulfillment-order line item was already moved to picked (e.g. in a prior partial completion), it reverts to pick_in_progress.

Validation

• The pick must be in processing or stopped status.
• quantity must not exceed the item's current quantity_picked.

Records items that could not be picked: out of stock, damaged, wrong item, or any other warehouse-floor issue.

Behavior

Appends a mispick record (quantity + reason) to the matching pick item's mispicks array. The fulfillment-order line item status does not change until Complete pick.

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.

Validation

• The pick must be in processing status.
• quantity must not exceed item.quantity - item.quantity_picked - sum(existing mispick quantities).
• reason is a free-text string describing why the item couldn't be picked.

Creates a pack work order for one or more fulfillment-order line items at a single location.

When to use this

Call this after items have been picked (or directly after allocation if your workflow skips the pick stage). Each item in the request must be in allocated or picked status.

Behavior

On success, Carriyo:

1. Moves each referenced line item from allocated or picked to pack_in_progress. If the requested quantity is less than the line item's total, the line item is split.
2. Generates a packing list document (PDF) attached to the pack.
3. Creates one default empty package per unique fulfillment order in the pack.

Validation

• location_id is required. All items must belong to fulfillment orders at this location.
• At least one item is required.
• Each line item must be in allocated or picked status.
• Each line item must not already belong to another active (non-terminal) pack.
• quantity must not exceed the line item's available quantity.
• If pick_id is provided on an item, the referenced pick must be in completed status.

Returns the full pack record, including all items, packages, documents, and timestamps.

The list endpoints (/order/{orderId}, /fulfillment-order/{foId}, /pick/{pickId}) return lookup records with only summary fields. Use this endpoint for the complete data.

Returns all packs associated with an order. These are lookup records with only summary fields. Use Get pack for the full record.

Returns all packs associated with a fulfillment order. These are lookup records with only summary fields. Use Get pack for the full record.

Returns all packs that reference a given pick. Use this to find which packs were created from a completed pick.

Transitions the pack from open to processing. The packer is now at the station building parcels.

Validation

• The pack must be in open status.
• Both packing_station and packer must be set (either at creation or via Reassign pack).

No request body is required.

Reassigns the pack to a different packer and/or packing station. At least one of packing_station or packer must be provided.

Validation

• The pack must be in open status.
• If packing_station is provided, it must be a valid station for the location.
• If packer is provided, the user must have pack permission for the location.

Adds a new physical package (parcel) to the pack. Each package is assigned a unique package_id (prefixed PKG_).

A pack can have many packages. Each package belongs to one order and one fulfillment order. Items are placed into packages via Pack items.

Behavior

The package is created empty with the provided dimensions and weight constraints. You then use Pack items to assign line items into it.

Validation

• The pack must be in open or processing status.
• order_id and fulfillment_order_id are required and must match items in the pack.

Updates the physical properties of a package (carton type, dimensions, weight). All fields are optional; only provided fields are updated.

Validation

• The pack must be in open or processing status.
• The package must not have an active (non-cancelled) shipment. Once a shipment is booked for a package, update the shipment directly.

Removes a package from the pack. Any items in the package are unpacked first (their quantity_packed on the pack item is decremented).

Validation

• The pack must be in open or processing status.
• The package must not have an active (non-cancelled) shipment.

Clears all packing progress and replaces all packages with one default empty package per unique fulfillment order in the pack.

Use this when the packer needs to start over. All items are unpacked (quantity_packed reset to 0) and existing packages are deleted.

Validation

• The pack must be in open or processing status.
• No package in the pack can have an active (non-cancelled) shipment.

No request body is required.

Places line items into a specific package. Call this as the packer scans or places each item into a parcel.

Behavior

For each item in the request, Carriyo increments quantity_packed on the matching pack item and adds a PackageItem entry to the target package's items array.

You can call this endpoint multiple times. Each call adds to the running total.

Validation

• The pack must be in processing status.
• Each package_id must exist in the pack and belong to the same fulfillment order as the line item.
• quantity must not exceed item.quantity - item.quantity_packed.