> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Store catalog

> The store catalog combines a master product catalog and per-store inventory to power item-level fulfillment. Learn how products and inventory fit together, how pick & pack works, and what item-level details an order can carry.

The **store catalog** is the master data behind item-level fulfillment. It pairs a **product catalog** — your canonical list of items — with **store inventory** that tracks what each [store location](/reference/store-locations) actually has on the shelf. Together they let Nash support **pick & pack**, where a courier picks the requested items, handles substitutions, and hands off the packed order for delivery.

## Products & inventory

The catalog has two layers:

* **Products** are the master records for the items you sell — names, images, categories, identifiers, weight, and dimensions. They are organization-wide and referenced by both inventory and orders.
* **Store inventory** links a product to a specific store location and records its real-time **availability**, **pricing**, **quantity**, and physical **location** (aisle, bay, shelf) for efficient picking.

<Tabs>
  <Tab title="Products">
    Manage products in bulk with [Create or update products](/api-reference/store-catalog/create-or-update-products) (`POST /v1/products`) and read them back with [Get products](/api-reference/store-catalog/get-products) (`GET /v1/products`).

    Required fields include `name`, `categories[]`, `weight`, `dimensions{depth,height,width}`, and `identifiers[{type,value}]`. Optional fields include `imageUrls[]`, `externalIdentifier`, `sku`, `description`, `attributes[]` (such as `WEIGHTED`), and `details`.

    Limits: up to **1,000 products** per request, **10 requests per second** per organization.
  </Tab>

  <Tab title="Inventory">
    Update inventory in bulk with [Create or update inventory](/api-reference/store-catalog/create-or-update-inventory) (`POST /v1/inventory`) and query it with [Get inventory](/api-reference/store-catalog/get-inventory) (`GET /v1/inventory`).

    Each entry ties a product to a store using your external identifiers (`externalProductId`, `externalStoreLocationId`). The only required field is `available` (boolean); common fields include `quantity`, `valueCents`, `currency`, and `location{aisle,bay,shelf}`. Query by `externalStoreLocationId` or `externalProductId`, with `pageIndex` / `numResultsPerPage` pagination.

    Limits: up to **10,000 inventory items** per request, **10 requests per second** per organization.
  </Tab>
</Tabs>

<Note>
  For variable-weight products such as produce or deli items, set the product's `attributes` to `WEIGHTED`, and set per-unit pricing on the store-inventory entry's `details.weightedItemInfo.valueCentsPerMeasurementUnit` (for example, price per pound).
</Note>

## Pick & pack

Pick & pack turns an order into an item-level fulfillment job (delivery): the catalog and inventory tell a courier what to pick and where to find it, and the system tracks what was requested, what was picked, and any substitutions.

Enable it by including `pick_and_pack` in the order's `requirements` array when you create the order — see [Order requirements](/api-reference/order/order-requirements). The lifecycle is:

<Steps>
  <Step title="Order creation">
    The customer places an order with specific items and substitution preferences.
  </Step>

  <Step title="Picking">
    A courier picks the items, handling substitutions as needed.
  </Step>

  <Step title="Status updates">
    Picking progress is reported in real time. When picking finishes, the order reaches `items_pick_complete` and is ready for handoff to delivery.
  </Step>

  <Step title="Delivery">
    Once picking is complete, the order is handed to the delivery provider.
  </Step>
</Steps>

Each delivery carries a `pickedItems` array describing what the picker actually put in the bag, including the picked `sku`, `quantity`, `requestedQuantity`, `weight`, `priceCents`, and any scanned barcode data. For the full field reference and worked examples — straight picks, weighted items, substitutions, and multi-scan items — see the [Pick and Pack](/api-reference/store-catalog/pick-and-pack) background page.

<Info>
  You can track the `items_pick_complete` status via your order retrieval endpoints, or subscribe to status-change events through [Webhooks](/reference/webhooks).
</Info>

## Item-level details

When you create an order, each package's `items` array describes the individual items in that package. Per item you can set:

| Field          | Type    | Description                                           |
| -------------- | ------- | ----------------------------------------------------- |
| `id`           | string  | The merchant ID of the item                           |
| `description`  | string  | The description of the item                           |
| `count`        | integer | The quantity of the item                              |
| `dimensions`   | object  | `height`, `width`, `depth` (in centimeters)           |
| `weight`       | number  | The weight of the item in kilograms (kg)              |
| `valueCents`   | integer | The value of the item in cents                        |
| `category`     | string  | The category of the item                              |
| `requirements` | array   | Requirements specific to this item                    |
| `barcode`      | string  | Barcode value for this item                           |
| `metadata`     | object  | Key-value data to attach to the item                  |
| `subItems`     | array   | Nested sub-items (used for pick & pack substitutions) |

<Note>
  Each item carries a single `barcode` value. The richer parsed barcode payloads (format, variable weight, price, expiration) appear on the `pickedItems` results after picking, not on the items you submit — see the [Pick and Pack](/api-reference/store-catalog/pick-and-pack) page.
</Note>

For pick & pack orders, the `subItems` array supports substitution handling: a sub-item can carry a `sku` and a `substitution` object describing the `preference` (such as `refund` or `substitute`), the `source` of the decision, and the chosen `substituteItems[]`.

## Next steps

<CardGroup cols={2}>
  <Card title="Create or update products" icon="boxes-stacked" href="/api-reference/store-catalog/create-or-update-products">
    Bulk-manage your master product catalog.
  </Card>

  <Card title="Create or update inventory" icon="warehouse" href="/api-reference/store-catalog/create-or-update-inventory">
    Track per-store availability, pricing, and aisle location.
  </Card>

  <Card title="Pick and Pack" icon="basket-shopping" href="/api-reference/store-catalog/pick-and-pack">
    The full pick-and-pack model and picked-items reference.
  </Card>

  <Card title="Get inventory" icon="magnifying-glass" href="/api-reference/store-catalog/get-inventory">
    Query inventory by store or product.
  </Card>
</CardGroup>