Groceries

Fields marked * are required. Updates keep every field they are not given. An AI app can ask vritto_describe for the same details, filtered to what its connection may use.

Grocery Item`grocery_item`

One thing on a grocery list. The same operations reach shopping lists for a day and store (type 'list'), food and supplies on hand in the pantry, fridge or freezer (type 'inventory'), stores (type 'store') and receipts (type 'receipt').

groceries_findFindthrough vritto_find

Read Groceries: one record by id, or records of a type filtered by list, dates, status, storage or text; view 'low_stock', 'expiring' or 'restock'. No filter gives the week's lists, needed items, low stock and expiring food. A search with no type reads every type.

Note: Set type for lists, pantry items, stores or receipts. view 'low_stock', 'expiring' or 'restock' reads the pantry; no filter gives the week's overview.

Field	Type	Description
type	one of item, list, inventory, store, receipt	Which records to read. Omit for the overview, or with query to search every type.
id	string	Return just this record.
view	one of needed, low_stock, expiring, restock	'needed' items still to buy; 'low_stock' pantry items at or below their threshold; 'expiring' pantry items expiring within a week; 'restock' suggested restocks.
listName	string	Type 'item': the items on this list, by the name the person uses.
listId	string	Type 'item': the items on this list.
storeId	string	Record ID from a prior groceries_find result, never invented.
status	one of planned, active, shopping, completed, archived, needed, bought, skipped, moved, draft, needs_review, applied, failed	A list is planned, active, shopping or completed; an item needed, bought or skipped; a receipt draft, needs_review, applied or failed.
storageLocation	one of pantry, fridge, freezer, household, other	Type 'inventory': only what is kept here.
from	string	Earliest date, inclusive: a list's shopping day, a pantry item's expiry, a receipt's purchase day.
to	string	Latest date, inclusive, on the same dates. ALWAYS pass from/to when the question concerns a period.
query	string	Text to match: a name, store, category or note.
includeArchived	boolean
limit	integer	Rows to return.
start	string	Older form of from, for lists.
end	string	Older form of to, for lists.
expiringBefore	string	Older form of to, for pantry items.
lowStockOnly	boolean	Older form of view 'low_stock'.

Example input

{
  "type": "item",
  "listName": "Costco run"
}

groceries_addCreatethrough vritto_create

Add one record: an item on a list (name, plus listName as the person said it; no lookup first), a list (type 'list': title, shoppingDate, store), a pantry item (type 'inventory'), a store, or a receipt (rawText is parsed into lines for review).

Note: Pass an item's list by name (listName) as the person said it; no lookup needed. Set type for a list, pantry item, store or receipt.

Field	Type	Description
type	one of item, list, inventory, store, receipt	Record type: 'item' (default) one thing on a shopping list; 'list' a shopping list for a day and store; 'inventory' food or supplies on hand in the pantry, fridge or freezer; 'store' a store the person shops at; 'receipt' a captured receipt and its lines.
record	object	The record's fields.
record.name	string	The item, pantry item or store's name. Required for those.
record.title	string	Type 'list': its title, e.g. 'Saturday Costco run'. Required for a list.
record.listName	string	Type 'item': the list as the person names it ('grocery list', 'Costco run'), matched against open lists; never look a list up just to get its ID.
record.listId	string	Type 'item': the list's ID, only when already known; else listName.
record.shoppingDate	string	Type 'list': the planned shopping day.
record.storeId	string	Lists, items and receipts: the store's ID when known.
record.storeName	string	Lists, items and receipts: the store as named.
record.status	one of planned, active, shopping, completed, archived, needed, bought, skipped, moved, draft, needs_review, applied, failed	A list is planned, active, shopping or completed; an item needed, bought or skipped; a receipt draft, needs_review, applied or failed.
record.priority	one of low, normal, high, urgent	Lists and items, only when the person signals urgency: 'we're out' urgent, 'running low' high, 'no rush' low.
record.quantity	number	Type 'item': how many to buy (default 1).
record.unit	string
record.category	string	Department or category.
record.aisle	string	Type 'item': aisle or section.
record.priceEstimate	number	Type 'item': expected price, with priceCurrency.
record.priceCurrency	string	ISO currency of priceEstimate.
record.barcode	string
record.productType	one of food, beauty, pet_food, household, general, other
record.productId	string	Product cache or provider product ID.
record.inventoryItemId	string	Type 'item': the pantry item it restocks.
record.position	number	Type 'item': manual order on its list.
record.sortRank	number	Type 'list': manual order.
record.reminderAt	string	Lists and items: ISO date-time of a shopping reminder.
record.source	object	Type 'item': the record in another module it came from (a recipe).
record.quantityOnHand	number	Type 'inventory': how much is on hand (default 1).
record.storageLocation	one of pantry, fridge, freezer, household, other	Type 'inventory': where it is kept (default pantry).
record.storageDetail	string	Type 'inventory': shelf or bin.
record.expiryDate	string	Type 'inventory': schedules a reminder reminderLeadDays before (default 3).
record.openedDate	string	Calendar date, YYYY-MM-DD.
record.reminderLeadDays	integer
record.lowStockThreshold	number	Type 'inventory': at or below this it is low stock.
record.targetStockLevel	number
record.autoAddToList	boolean	Type 'inventory': suggest it for every restock.
record.lastPurchasedAt	string	Calendar date, YYYY-MM-DD.
record.product	object	Type 'inventory': product data from a barcode or catalog lookup.
record.retailerKey	string	Type 'store': retailer key, e.g. 'target'.
record.address	string
record.placeKey	string	Type 'store': Places key when known.
record.aisleOrder	list of string	Type 'store': aisle names in walking order.
record.preferred	boolean
record.purchasedOn	string	Type 'receipt': purchase day.
record.total	number	Type 'receipt': with currency.
record.currency	string	Type 'receipt': ISO currency as printed.
record.rawText	string	Type 'receipt': receipt text, parsed into lines for review when no lines are sent.
record.imageAssetId	string	Record ID from a prior groceries_find result, never invented.
record.lines	list of object	Type 'receipt': line items. On a change, sent lines REPLACE the stored set.
record.notes	string
record.tags	list of string
record.idempotencyKey	string	Stable dedupe key; a retry with it never duplicates.
item	object	Older form of record, for an item or a pantry item.
item.name	string
list	object	Older form of record, for a list.
list.title	string
store	object	Older form of record, for a store.
store.name	string
receipt	object	Older form of record, for a receipt.
receipt.storeName	string

Example input

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

groceries_changeUpdatethrough vritto_update

Change one record by record.id; sent fields merge. An item bought is status 'bought'; a pantry item used up is delta (-2); finish true completes a list and checks off its needed items; itemIds with targetListId moves items; apply true applies a reviewed receipt. Resolve ids with groceries_find first.

Note: A receipt's sent lines replace the stored lines. finish true completes a list; delta adjusts a pantry item; apply true applies a reviewed receipt.

Field	Type	Description
type	one of item, list, inventory, store, receipt	Record type: 'item' (default) one thing on a shopping list; 'list' a shopping list for a day and store; 'inventory' food or supplies on hand in the pantry, fridge or freezer; 'store' a store the person shops at; 'receipt' a captured receipt and its lines.
record	object	The record's id plus the fields to change.
record.id*	string	Record ID from a prior groceries_find result, never invented.
record.name	string	The item, pantry item or store's name. Required for those.
record.title	string	Type 'list': its title, e.g. 'Saturday Costco run'. Required for a list.
record.listName	string	Type 'item': the list as the person names it ('grocery list', 'Costco run'), matched against open lists; never look a list up just to get its ID.
record.listId	string	Type 'item': the list's ID, only when already known; else listName.
record.shoppingDate	string	Type 'list': the planned shopping day.
record.storeId	string	Lists, items and receipts: the store's ID when known.
record.storeName	string	Lists, items and receipts: the store as named.
record.status	one of planned, active, shopping, completed, archived, needed, bought, skipped, moved, draft, needs_review, applied, failed	A list is planned, active, shopping or completed; an item needed, bought or skipped; a receipt draft, needs_review, applied or failed.
record.priority	one of low, normal, high, urgent	Lists and items, only when the person signals urgency: 'we're out' urgent, 'running low' high, 'no rush' low.
record.quantity	number	Type 'item': how many to buy (default 1).
record.unit	string
record.category	string	Department or category.
record.aisle	string	Type 'item': aisle or section.
record.priceEstimate	number	Type 'item': expected price, with priceCurrency.
record.priceCurrency	string	ISO currency of priceEstimate.
record.barcode	string
record.productType	one of food, beauty, pet_food, household, general, other
record.productId	string	Product cache or provider product ID.
record.inventoryItemId	string	Type 'item': the pantry item it restocks.
record.position	number	Type 'item': manual order on its list.
record.sortRank	number	Type 'list': manual order.
record.reminderAt	string	Lists and items: ISO date-time of a shopping reminder.
record.source	object	Type 'item': the record in another module it came from (a recipe).
record.quantityOnHand	number	Type 'inventory': how much is on hand (default 1).
record.storageLocation	one of pantry, fridge, freezer, household, other	Type 'inventory': where it is kept (default pantry).
record.storageDetail	string	Type 'inventory': shelf or bin.
record.expiryDate	string	Type 'inventory': schedules a reminder reminderLeadDays before (default 3).
record.openedDate	string	Calendar date, YYYY-MM-DD.
record.reminderLeadDays	integer
record.lowStockThreshold	number	Type 'inventory': at or below this it is low stock.
record.targetStockLevel	number
record.autoAddToList	boolean	Type 'inventory': suggest it for every restock.
record.lastPurchasedAt	string	Calendar date, YYYY-MM-DD.
record.product	object	Type 'inventory': product data from a barcode or catalog lookup.
record.retailerKey	string	Type 'store': retailer key, e.g. 'target'.
record.address	string
record.placeKey	string	Type 'store': Places key when known.
record.aisleOrder	list of string	Type 'store': aisle names in walking order.
record.preferred	boolean
record.purchasedOn	string	Type 'receipt': purchase day.
record.total	number	Type 'receipt': with currency.
record.currency	string	Type 'receipt': ISO currency as printed.
record.rawText	string	Type 'receipt': receipt text, parsed into lines for review when no lines are sent.
record.imageAssetId	string	Record ID from a prior groceries_find result, never invented.
record.lines	list of object	Type 'receipt': line items. On a change, sent lines REPLACE the stored set.
record.notes	string
record.tags	list of string
record.idempotencyKey	string	Stable dedupe key; a retry with it never duplicates.
record.archived	boolean	Type 'store' or 'receipt': archive or restore it.
delta	number	Type 'inventory': signed change to the quantity on hand, floored at zero.
finish	boolean	Type 'list': true finishes the shopping run.
apply	boolean	Type 'receipt': true applies its accepted lines (record.lines, when sent, instead of the stored ones), only after the person confirmed them.
itemIds	list of string	Several items to move together.
targetListId	string	With itemIds: the list they move to.
targetStoreId	string	Record ID from a prior groceries_find result, never invented.
targetStoreName	string
targetPosition	number	With itemIds: order position of the first.
expectedRevision	integer	Concurrency guard: the revision last read.
itemId	string	Older name for the item or pantry item id.
listId	string	Older name for the list id.
storeId	string	Older name for the store id.
receiptId	string	Older name for the receipt id.
patch	object	Older form of record.
patch.notes	string
lines	list of object	Older form of record.lines, with receiptId: the lines to apply.
status	one of planned, active, shopping, completed, archived, needed, bought, skipped, moved, draft, needs_review, applied, failed	Older form of record.status, with itemId.
shoppingDate	string	Older form of record.shoppingDate, with listId.
storeName	string	Older form of record.storeName, with listId.
sortRank	number	Older form of record.sortRank, with listId.

Example input

{
  "type": "item",
  "record": {
    "id": "gi_oatmilk",
    "status": "bought"
  }
}

groceries_removeDeletethrough vritto_delete

Delete (archive) one record by id: a grocery list, an item on one, a pantry item, a store or a receipt. Only for explicit removals: a bought item is a groceries_change. Resolve the id first.

Note: Archives the record. Set type for a list, pantry item, store or receipt.

Field	Type	Description
type	one of item, list, inventory, store, receipt	Record type: 'item' (default) one thing on a shopping list; 'list' a shopping list for a day and store; 'inventory' food or supplies on hand in the pantry, fridge or freezer; 'store' a store the person shops at; 'receipt' a captured receipt and its lines.
id	string	The record to remove.
expectedRevision	integer	Concurrency guard: the revision last read.
itemId	string	Older name for the item or pantry item id.
listId	string	Older name for the list id.
storeId	string	Older name for the store id.
receiptId	string	Older name for the receipt id.

Food Product Catalog`food_catalog`

Open Food Facts product reference data.

groceries_searchGroceryProductsLook Upthrough vritto_lookup

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

Field	Type	Description
query*	string	Product search text.
limit	integer	Max results (default 10).

Kept in the Vritto app

groceries_analyzeGroceryReceipt: Runs Vritto's own AI; the calling assistant is already an AI.
groceries_lookupGroceryProductByBarcode: Background upkeep Vritto already runs on its own.

Groceries

Grocery Itemgrocery_item

Food Product Catalogfood_catalog

Kept in the Vritto app

Grocery Item`grocery_item`

Food Product Catalog`food_catalog`