Pick and Pack enables item-level fulfillment by coordinating products, store-level inventory, and delivery providers.

​
Quick Start

1

Set up your Product Catalog

Define your master product data with names, images, categories, and identifiers
2

Configure Store Inventory

Track per-store availability, pricing, and aisle locations for efficient picking
3

Process Pick and Pack Orders

Handle substitutions, track picking status, and manage item-level fulfillment

​
Product Catalog

Your product catalog serves as the master data source for all items across your stores. It defines the core product information that drives inventory management, order processing, and picking operations. Product Catalog Products are managed in bulk and referenced throughout your fulfillment workflow by inventory and orders.

​
Key fields

  • Required fields: name, imageUrls[], categories[], weight, dimensions{depth,height,width}, identifiers[{type,value}].
  • Optional fields: externalIdentifier, sku, description, attributes[] (e.g., WEIGHTED), and details (sizeSpecification, packSizeSpecification, weightedItemInfo).

​
API Endpoints

​
Store Inventory

Store inventory tracks the real-time availability, pricing, and location of products within each of your store locations. This data powers accurate order fulfillment by ensuring pickers know exactly what’s available and where to find it. Store Inventory Each inventory entry links a product to a specific store location using your external identifiers, enabling precise per-store inventory management.

​
Key fields

  • Required field: available (boolean).
  • Common fields: externalProductId, externalStoreLocationId, quantity, valueCents, currency, location{aisle,bay,shelf}.

​
Weighted Items

For variable-weight products (produce, deli items, etc.):
  1. Set the product attribute to WEIGHTED in your product catalog
  2. Use details.weightedItemInfo.valueCentsPerMeasurementUnit for per-unit pricing (e.g., price per pound)

​
API Endpoints

  • Create/Update Inventory: POST /v1/inventory - Bulk inventory updates
  • Get Inventory: GET /v1/inventory - Query inventory with filters:
    • externalStoreLocationId: Filter by store location
    • externalProductId: Filter by product
    • Pagination: pageIndex, numResultsPerPage

​
Pick and Pack Orders

Orders with Pick and Pack enabled leverage your product catalog and store inventory to enable precise item-level fulfillment. The system tracks exactly what was requested, what was picked, and any substitutions made during the process.
To enable Pick and Pack functionality, include pick_and_pack in the order.requirements array when creating orders. See the complete list in Order Requirements.

​
Order Lifecycle

  1. Order Creation: Customer places order with specific items with substitution preferences
  2. Picking: 3rd party courier picks items, handling substitutions as needed
  3. Status Updates: Real-time updates on picking progress
  4. Delivery: Order handed off to delivery provider once picking is complete

​
Sub-item fields

  • item.subItems[].sku: optional SKU for the specific sub-item being picked.
  • item.subItems[].substitution: object describing substitution preferences and chosen replacements.
    • preference: e.g., refund or substitute.
    • source: who made the decision (e.g., merchant, customer).
    • substituteItems[]: list of { sku, quantity, weight } representing the chosen replacements.

​
Status

  • items_pick_complete: emitted when item picking for the order has finished and it is ready for handoff to delivery. Track this status via your order retrieval endpoints and/or subscribe to status change events in Webhooks.

​
Picked items

Capture exactly what was picked using deliver.pickedItems[]. Each picked-item represents a picked unit or substituted item.
  • Array item fields: sku, requested_sku, id, requested_id, quantity, scanned_code, substitution_type, substitution_source, weight.

​
Example: Complete Picked Item

{
  "delivery": {
    "pickedItems": [
      {
        "sku": "organic_bananas_001",
        "requested_sku": "bananas_001", 
        "id": "e3c1f28a-2162-49ac-82ef-f80a62e74204",
        "requested_id": "3f74e35a-fe9b-4bee-bc2a7bbbc2ebb282",
        "quantity": 1,
        "scanned_code": "012345678905",
        "substitution_type": "substitute",
        "substitution_source": "merchant",
        "weight": 1.2
      },
      {
        "sku": "milk_2pct_001",
        "requested_sku": "milk_2pct_001",
        "id": "f4d2g39b-3273-50bd-93fg-g91b73f85315",
        "requested_id": "f4d2g39b-3273-50bd-93fg-g91b73f85315", 
        "quantity": 1,
        "scanned_code": "987654321098",
        "substitution_type": null,
        "substitution_source": null,
        "weight": null
      }
    ]
  }
}
This example shows:
  • A substitution where regular bananas were replaced with organic bananas (merchant decision)
  • A standard pick with no substitutions for milk
  • Weight tracking for the variable-weight banana item