Groceries

Lists or searches saved grocery stores.

Creates a grocery store or outlet the user shops at, optionally with aisle walking order for sorted shopping.

{
  "store": {
    "name": "Costco",
    "preferred": true
  }
}

Updates fields on an existing grocery store.

Archives a grocery store (soft delete). Use only for explicit deletions.

Searches grocery lists by text, shopping-date range, store, or status.

Creates a grocery list, usually for a shopping date and store. A reminderAt time schedules a shopping notification.

{
  "list": {
    "title": "Weekend Costco run",
    "shoppingDate": "2026-09-27",
    "storeName": "Costco"
  }
}

Finishes a shopping run: marks every still-needed item on the list bought and completes the list in one transaction. Use for 'done shopping', not per-item status calls.

Moves a whole grocery list to another shopping date, store, or manual order position.

Updates fields on an existing grocery list.

Archives a grocery list (soft delete). Use only for explicit deletions.

Searches grocery list items by text, list, store, or status.

Adds an item to a grocery list in a single call. Pass the list by NAME (listName) as the user said it, no lookup needed; send listId only if you already have it.

Note: Pass the list by name (listName) as the user said it; no lookup needed.

{
  "item": {
    "listName": "Costco",
    "name": "Oat milk",
    "quantity": 2,
    "unit": "cartons"
  }
}

Moves or reorders one or more items, optionally onto another list or store. Use this (not patch) for cross-list moves.

Updates fields on an existing grocery list item.

Sets one item's status, e.g. mark bought while shopping or back to needed.

{
  "itemId": "gi_oatmilk",
  "status": "bought"
}

Archives a grocery list item (soft delete). Use only for explicit deletions.

Searches inventory by text, storage location, expiry window, or low-stock state.

Adds a pantry/fridge/freezer inventory item. Expiry dates with reminderLeadDays schedule expiry reminders; thresholds drive restock suggestions.

{
  "item": {
    "name": "Basmati rice",
    "quantityOnHand": 2,
    "unit": "kg",
    "storageLocation": "pantry",
    "lowStockThreshold": 1
  }
}

Adjusts an inventory item's quantity on hand by a signed delta (floored at zero). Use for 'used two eggs' style updates.

{
  "itemId": "inv_eggs",
  "delta": -2
}

Updates fields on an existing inventory item.

Archives an inventory item (soft delete). Use only for explicit deletions.

Lists captured receipts, newest first, optionally by status.

Captures a receipt. Provide rawText to auto-parse line items, or explicit lines; parsed receipts land in needs_review for the user to confirm before applying.

{
  "receipt": {
    "storeName": "Trader Joe's",
    "purchasedOn": "2026-09-25",
    "total": 64.37,
    "currency": "USD",
    "rawText": "BANANAS 1.99\nOAT MILK 3.49\nTOTAL 64.37"
  }
}

Applies a reviewed receipt: accepted lines increment or create inventory and mark matching needed list items bought. Only call after the user has confirmed the lines.

Corrects a captured receipt (store, date, total, currency, notes, or its lines). Sent lines REPLACE the stored set, so read the receipt first.

Note: Sent lines replace the stored lines.

Archives a receipt so it stops counting toward grocery spend. Use for a duplicate or a receipt that is not the user's.

Returns the grocery cockpit: active lists, needed items, low stock, expiring-soon inventory, receipts awaiting review, and counts.

No input.

Suggests restocks from inventory that is at or below its low-stock threshold or flagged for recurring restock.

Searches the Open Food Facts catalog by name for product metadata.