Inventory

Inventory routes

Manage green coffee inventory, generate share links, and keep stocked state accurate through session-authenticated product routes.

Inventory is where public catalog data becomes account-owned operational data. The core route is /api/beans, backed by session auth for writes and optional share-token reads for scoped external viewing.

Inventory IDs are not catalog IDs. Roast and downstream workflows use green_coffee_inv.id values.

Endpoints

RouteMethodsAuthPurpose
/api/beansGET POST PUT DELETEGET: session or share token; writes: sessionInventory CRUD plus shared-link reads
/api/sharePOSTSessionCreate share links for one bean or the whole inventory
/api/update-stocked-statusPOST PUTSessionRecalculate stocked status for one item or the entire account

Read and share behavior

  • GET /api/beans?share=<token> returns a scoped view if the token exists, is active, and has not expired.
  • Without a valid share token, GET /api/beans falls back to the current session. If no session is present, the route returns { data: [] } instead of a 401.
  • POST /api/share accepts resourceId plus an optional expiresIn value such as 7d. The response is a shareUrl under /beans?share=....
  • Share links reveal inventory data only; they do not grant broader session or account access.

Mutation behavior

  • POST /api/beans can create manual catalog entries when no catalog_id is supplied and manual_name is present.
  • PUT /api/beans requires an id query parameter and filters updates down to known inventory columns before writing.
  • DELETE /api/beans requires an id query parameter and enforces ownership before removing inventory and dependent data.
  • POST /api/update-stocked-status recalculates one item by coffee_id. PUT scans the caller's full inventory and batch-updates any mismatched stocked flags.

Inventory IDs drive roast workflows

Roast creation, Artisan imports, and several CLI commands expect green_coffee_inv.id values, not coffee_catalog IDs. Use the inventory surface or CLI inventory list to find the correct IDs.

CLI access

List stocked inventory
purvey inventory list --stocked --pretty
Inspect add flags
purvey inventory add --help

Related links

Inventory page

Manage inventory in the web app.

Platform route matrix

See inventory in context with sales, chat, and billing routes.

CLI inventory docs

Terminal workflows for listing and managing inventory.

Roast docs

Roasts consume inventory IDs and update stocked state.