Grocy
App · 33 actions
Keep your household's Grocy up to date from anywhere: book purchases, use and move stock, look up barcodes, send the shopping list, put what's running low on it, and tick off chores, tasks and battery changes. Start a workflow when food is about to go off or runs low, or a chore, task or battery is due.
Actions
| Action | What it does |
|---|---|
| Add products to restock | Put the products below their minimum stock, past their best-before date or expired on a shopping list. |
| Add purchase | Book a purchase into stock, with its best-before date, price and where it's put away. |
| Add recipe to shopping list | Put what a recipe needs and isn't in stock on a shopping list. |
| Add to shopping list | Put a product, or anything else written as a note such as Birthday candles, on a shopping list. |
| Clear shopping list | Take every item off a shopping list, or only the ones ticked off. |
| Complete task | Mark a task done, now or at a time. |
| Create product | Add a product to Grocy, with where it's kept, its unit, minimum stock and a barcode. |
| Create shopping list | Make a shopping list, such as for a party. |
| Create task | Add a task, with a due date, a category and who it's for. |
| Delete product | Delete a product, with its stock and barcodes. |
| Delete shopping list | Delete a shopping list with its items. |
| Delete task | Delete a task. |
| Find product by barcode | Find the product a barcode belongs to, such as one scanned on a phone, with its stock. |
| Find products | Find products by words in their name, location or product group, with how much of each is in stock. |
| Get expiring and low stock | Get the products due soon, past their best-before date, expired and below their minimum stock, with a summary ready for a message. |
| Get product | Get a product with how much is in stock, opened, its next due date, prices and barcodes. |
| Get shopping list | Get a shopping list's items, and the list as text to send to whoever does the shopping. |
| Get stock | Get what's in stock at home, with each product's amount and next best-before date, everywhere or at one location such as the freezer. |
| List batteries | List batteries, such as smoke alarms', with when each was last charged or changed and is next due. |
| List chores | List the household's chores with when each was last done and is next due, such as for a morning message. |
| List recipes | List recipes with whether everything each needs is in stock, such as to choose what to cook tonight. |
| List tasks | List tasks with when each is due: those not done, done or all. |
| Mark chore done | Mark a chore done, or skipped, now or at a time. |
| Mark product opened | Mark an amount of a product as opened, such as a jar of jam. |
| Move product | Move an amount of a product from one location to another, such as from the fridge to the freezer. |
| Record battery charge | Record that a battery was charged or changed, now or at a time. |
| Remove from shopping list | Take an item off a shopping list, or take some of its amount off. |
| Reopen task | Mark a done task as not done. |
| Undo battery charge | Undo a battery charge, by the charge ID 'Record battery charge' returned. |
| Undo chore | Undo a chore marked done, by the execution ID 'Mark chore done' returned. |
| Undo stock change | Undo a purchase, use, opening or move, by the transaction ID the step that made it returned. |
| Update product | Change a product's name, location, unit, minimum stock or other details, or add a barcode. |
| Use product | Take an amount of a product out of stock, used or thrown away as spoiled. |
Add products to restock
Put the products below their minimum stock, past their best-before date or expired on a shopping list.
Inputs
- Shopping list
shopping_listtextRequired - The shopping list: pick one, or give its number from another Grocy step or its name.
- Which products
whichtext - Which products to add. Defaults to those below minimum stock.One of:
below_min(Below minimum stock),overdue(Past their due date),expired,all(All of these). Default:below_min.
Outputs
countnumber- How many items changed
itemslist- The items added, or added to
linktext- Where the list opens in Grocy
list_idnumber- The list's number
list_nametext- The list's name
whichtext- Which products: below_min, overdue, expired or all
Example output
{
"count": 1,
"items": [
{
"added_amount": 3,
"amount": 3,
"done": false,
"id": 12,
"link": "https://grocy.example.com/shoppinglist?list=1",
"list_id": 1,
"note": "",
"product_id": 6,
"product_name": "Chopped tomatoes",
"text": "3 Cans Chopped tomatoes",
"unit": "Can"
}
],
"link": "https://grocy.example.com/shoppinglist?list=1",
"list_id": 1,
"list_name": "Shopping list",
"which": "below_min"
}Add purchase
Book a purchase into stock, with its best-before date, price and where it's put away.
Inputs
- Product
producttextRequired - The product: pick one, or give its number from another Grocy step or its name, such as Milk.
- Amount
amountnumberRequired - How much, in the product's stock unit, such as 2 for two bottles.From 0 to 1000000.
- Best-before date
best_before_datedate - When it's due. Leave blank for the product's default due days.
- Price
pricenumber - The price per unit, such as 1.29.From 0 to 1000000.
- Location
locationtext - Where it's put away. Leave blank for the product's default.
- Store
storetext - Where it was bought.
- Note
notetext - A note on this stock, such as Opened at work.
Outputs
amountnumber- How much was booked, in the product's unit
best_before_datetext- The date of the stock it touched (YYYY-MM-DD)
linktext- Where the product opens in Grocy
next_due_datetext- The soonest date in stock now, or blank
pricenumber- The price per unit of that stock
product_idnumber- The product's number
product_nametext- The product's name
stock_amountnumber- How much is in stock now
stock_amount_openednumber- How much of it is opened now
transaction_idtext- The change's transaction ID, which 'Undo stock change' takes
unittext- The product's unit
Example output
{
"amount": 2,
"best_before_date": "2026-11-19",
"link": "https://grocy.example.com/product/1",
"next_due_date": "2026-11-14",
"price": 1.29,
"product_id": 1,
"product_name": "Milk",
"stock_amount": 3,
"stock_amount_opened": 0,
"transaction_id": "6af63f498ed35",
"unit": "Bottle"
}Add recipe to shopping list
Put what a recipe needs and isn't in stock on a shopping list.
Inputs
- Recipe
recipetextRequired - The recipe: pick one, or give its number from another Grocy step or its name.
- Shopping list
shopping_listtext - The list to put them on. Leave blank for Grocy's own list.
Outputs
countnumber- How many items changed (0 when nothing was missing)
itemslist- The items added, or added to
linktext- Where the list opens in Grocy
list_idnumber- The list's number
list_nametext- The list's name
recipe_idnumber- The recipe's number
recipe_nametext- The recipe's name
Example output
{
"count": 1,
"items": [
{
"added_amount": 1,
"amount": 1,
"done": false,
"id": 13,
"link": "https://grocy.example.com/shoppinglist?list=1",
"list_id": 1,
"note": "",
"product_id": 7,
"product_name": "Butter",
"text": "1 Pack Butter",
"unit": "Pack"
}
],
"link": "https://grocy.example.com/shoppinglist?list=1",
"list_id": 1,
"list_name": "Shopping list",
"recipe_id": 1,
"recipe_name": "Pancakes"
}Add to shopping list
Put a product, or anything else written as a note such as Birthday candles, on a shopping list. A product already on it gets more.
Inputs
- Shopping list
shopping_listtextRequired - The shopping list: pick one, or give its number from another Grocy step or its name.
- Product
producttext - The product: pick one, or give its number from another Grocy step or its name. Leave blank to add a note instead.
- Note
notetext - What to buy when it's not a product, or a note on the product.
- Amount
amountnumber - How much, in the product's stock unit. Defaults to 1.From 0 to 1000000.
Outputs
amountnumber- How much to buy
donetrue/false- Whether it's ticked off
idnumber- The item's number, which 'Remove item' takes
linktext- Where the list opens in Grocy
list_idnumber- The shopping list's number
list_nametext- The list's name
notetext- The item's note, or the item itself when it's not a product
product_idnumber- The product's number (0 for a note)
product_nametext- The product's name (blank for a note)
texttext- The item as the list shows it, such as 6 Pieces Eggs
unittext- The unit, for a product
Example output
{
"amount": 6,
"done": false,
"id": 9,
"link": "https://grocy.example.com/shoppinglist?list=1",
"list_id": 1,
"list_name": "Shopping list",
"note": "",
"product_id": 2,
"product_name": "Eggs",
"text": "6 Pieces Eggs",
"unit": "Piece"
}Clear shopping list
Take every item off a shopping list, or only the ones ticked off.
Inputs
- Shopping list
shopping_listtextRequired - The shopping list: pick one, or give its number from another Grocy step or its name.
- Only done items
done_onlytrue/false - Take off only the ticked items.Default:
false.
Outputs
done_onlytrue/false- Whether only done items were taken off
items_leftnumber- How many are left
linktext- Where the list opens in Grocy
list_idnumber- The list's number
list_nametext- The list's name
removednumber- How many items came off
Example output
{
"done_only": true,
"items_left": 2,
"link": "https://grocy.example.com/shoppinglist?list=1",
"list_id": 1,
"list_name": "Shopping list",
"removed": 4
}Complete task
Mark a task done, now or at a time.
Inputs
- Task
tasktextRequired - The task: pick one, or give its number from another Grocy step or its name.
- Done at
done_atdate and time - When it was done. Leave blank for now.
Outputs
assigned_totext- Who it's assigned to
assigned_to_idnumber- Their user number (0 when no one)
categorytext- Its category
days_until_duenumber- Days until it's due (negative when overdue), empty with no schedule
descriptiontext- Its description
donetrue/false- Whether it's done
done_attext- When it was done (Grocy's time), or blank
due_datetext- When it's due (YYYY-MM-DD), or blank
due_todaytrue/false- Whether it's due today
idnumber- The task's number, which other Grocy steps take
linktext- Where the task opens in Grocy
nametext- What needs doing
overduetrue/false- Whether it's overdue
Example output
{
"assigned_to": "Sam",
"assigned_to_id": 2,
"category": "Home",
"days_until_due": 1,
"description": "The kitchen tap drips.",
"done": false,
"done_at": "",
"due_date": "2026-11-13",
"due_today": false,
"id": 4,
"link": "https://grocy.example.com/task/4",
"name": "Call the plumber",
"overdue": false
}Create product
Add a product to Grocy, with where it's kept, its unit, minimum stock and a barcode.
Inputs
- Name
nametextRequired - What the product is called, such as Oat milk.
- Location
locationtextRequired - Where it's kept by default, such as Fridge.
- Unit
quantity_unittextRequired - What it's counted and bought in, such as Bottle or Piece.
- Minimum stock
min_stock_amountnumber - The least you want at home. Below it, the product shows as running low.From 0 to 1000000.
- Default due days
default_best_before_daysnumber - How many days a purchase keeps, such as 7; -1 for never goes off.From -1 to 36500.
- Date type
date_typetext - Whether its dates are best-before dates (still fine after) or expiration dates. Defaults to best before.One of:
best_before(Best before),expires(Expiration date). Default:best_before. - Product group
product_grouptext - Its product group, such as Dairy.
- Description
descriptiontext - A note about the product.
- Barcode
barcodetext - A barcode to add to it, such as 4006381333931.
Outputs
activetrue/false- Whether the product is in use (not turned off)
amount_texttext- The amount in stock with its unit, such as 2 Bottles
average_pricenumber- The average price per unit of what's in stock
barcodeslist- Its barcodes
below_min_stocktrue/false- Whether there's less than the minimum in stock
date_typetext- best_before or expires: what its dates mean
default_best_before_daysnumber- Days a purchase keeps by default (-1 for never goes off)
descriptiontext- Its description
idnumber- The product's number, which other Grocy steps take
last_pricenumber- The price per unit paid last time
last_purchasedtext- When it was last bought (YYYY-MM-DD)
last_usedtext- When it was last used (YYYY-MM-DD)
linktext- Where it opens in Grocy
locationtext- Where it's kept by default, such as Fridge
location_idnumber- That location's number
min_stock_amountnumber- The least the household wants in stock
nametext- The product's name
next_due_datetext- The soonest date in stock (YYYY-MM-DD), or blank
product_group_idnumber- Its product group's number (0 when none)
purchase_unittext- The unit it's bought in
stock_amountnumber- How much is in stock
stock_amount_openednumber- How much of it is opened
stock_valuenumber- What the stock is worth
unittext- The unit stock is counted in, such as Bottle
Example output
{
"active": true,
"amount_text": "2 Bottles",
"average_price": 1.29,
"barcodes": [
"4006381333931"
],
"below_min_stock": false,
"date_type": "best_before",
"default_best_before_days": 7,
"description": "",
"id": 1,
"last_price": 1.29,
"last_purchased": "2026-11-12",
"last_used": "2026-11-11",
"link": "https://grocy.example.com/product/1",
"location": "Fridge",
"location_id": 2,
"min_stock_amount": 2,
"name": "Milk",
"next_due_date": "2026-11-14",
"product_group_id": 1,
"purchase_unit": "Bottle",
"stock_amount": 2,
"stock_amount_opened": 1,
"stock_value": 2.58,
"unit": "Bottle"
}Create shopping list
Make a shopping list, such as for a party.
Inputs
- Name
nametextRequired - What the list is called.
- Description
descriptiontext - A note about the list.
Outputs
descriptiontext- Its description
idnumber- The new list's number, which other Grocy steps take
linktext- Where it opens in Grocy
nametext- Its name
Example output
{
"description": "",
"id": 3,
"link": "https://grocy.example.com/shoppinglist?list=3",
"name": "Party"
}Create task
Add a task, with a due date, a category and who it's for.
Inputs
- Name
nametextRequired - What needs doing.
- Description
descriptiontext - More about it.
- Due date
due_datedate - When it's due.
- Category
categorytext - Its category, such as Home.
- Assigned to
assigned_totext - Who it's for.
Outputs
assigned_totext- Who it's assigned to
assigned_to_idnumber- Their user number (0 when no one)
categorytext- Its category
days_until_duenumber- Days until it's due (negative when overdue), empty with no schedule
descriptiontext- Its description
donetrue/false- Whether it's done
done_attext- When it was done (Grocy's time), or blank
due_datetext- When it's due (YYYY-MM-DD), or blank
due_todaytrue/false- Whether it's due today
idnumber- The task's number, which other Grocy steps take
linktext- Where the task opens in Grocy
nametext- What needs doing
overduetrue/false- Whether it's overdue
Example output
{
"assigned_to": "Sam",
"assigned_to_id": 2,
"category": "Home",
"days_until_due": 1,
"description": "The kitchen tap drips.",
"done": false,
"done_at": "",
"due_date": "2026-11-13",
"due_today": false,
"id": 4,
"link": "https://grocy.example.com/task/4",
"name": "Call the plumber",
"overdue": false
}Delete product
Delete a product, with its stock and barcodes. It can't be brought back from Lodol.
Inputs
- Product
producttextRequired - The product: pick one, or give its number from another Grocy step or its name, such as Milk.
Outputs
deletedtrue/false- Always true
idnumber- The product's number
nametext- The product's name
stock_amount_deletednumber- How much stock was deleted with it
Example output
{
"deleted": true,
"id": 9,
"name": "Oat milk",
"stock_amount_deleted": 0
}Delete shopping list
Delete a shopping list with its items. Grocy's own first list can't be deleted, and a deleted list can't be brought back from Lodol.
Inputs
- Shopping list
shopping_listtextRequired - The shopping list: pick one, or give its number from another Grocy step or its name.
Outputs
deletedtrue/false- Always true
idnumber- The list's number
items_deletednumber- How many items went with it
nametext- The list's name
Example output
{
"deleted": true,
"id": 3,
"items_deleted": 5,
"name": "Party"
}Delete task
Delete a task. It can't be brought back from Lodol.
Inputs
- Task
tasktextRequired - The task: pick one, or give its number from another Grocy step or its name.
Outputs
deletedtrue/false- Always true
idnumber- The task's number
nametext- What it was
Example output
{
"deleted": true,
"id": 4,
"name": "Call the plumber"
}Find product by barcode
Find the product a barcode belongs to, such as one scanned on a phone, with its stock. Says so when no product has it.
Inputs
- Barcode
barcodetextRequired - The barcode's number, such as 4006381333931.
Outputs
activetrue/false- Whether the product is in use (not turned off)
amount_texttext- The amount in stock with its unit, such as 2 Bottles
average_pricenumber- The average price per unit of what's in stock
barcodetext- The barcode looked up
barcodeslist- Its barcodes
below_min_stocktrue/false- Whether there's less than the minimum in stock
date_typetext- best_before or expires: what its dates mean
default_best_before_daysnumber- Days a purchase keeps by default (-1 for never goes off)
descriptiontext- Its description
foundtrue/false- Whether a product has the barcode; the rest is blank when not
idnumber- The product's number, which other Grocy steps take
last_pricenumber- The price per unit paid last time
last_purchasedtext- When it was last bought (YYYY-MM-DD)
last_usedtext- When it was last used (YYYY-MM-DD)
linktext- Where it opens in Grocy
locationtext- Where it's kept by default, such as Fridge
location_idnumber- That location's number
min_stock_amountnumber- The least the household wants in stock
nametext- The product's name
next_due_datetext- The soonest date in stock (YYYY-MM-DD), or blank
product_group_idnumber- Its product group's number (0 when none)
purchase_unittext- The unit it's bought in
stock_amountnumber- How much is in stock
stock_amount_openednumber- How much of it is opened
stock_valuenumber- What the stock is worth
unittext- The unit stock is counted in, such as Bottle
Example output
{
"active": true,
"amount_text": "2 Bottles",
"average_price": 1.29,
"barcode": "4006381333931",
"barcodes": [
"4006381333931"
],
"below_min_stock": false,
"date_type": "best_before",
"default_best_before_days": 7,
"description": "",
"found": true,
"id": 1,
"last_price": 1.29,
"last_purchased": "2026-11-12",
"last_used": "2026-11-11",
"link": "https://grocy.example.com/product/1",
"location": "Fridge",
"location_id": 2,
"min_stock_amount": 2,
"name": "Milk",
"next_due_date": "2026-11-14",
"product_group_id": 1,
"purchase_unit": "Bottle",
"stock_amount": 2,
"stock_amount_opened": 1,
"stock_value": 2.58,
"unit": "Bottle"
}Find products
Find products by words in their name, location or product group, with how much of each is in stock.
Inputs
- Words
wordstext - Words in the name, such as milk.
- Location
locationtext - Only this location, such as Fridge.
- Product group
product_grouptext - Only this product group, such as Dairy.
- How many
limitnumber - The most to list. Defaults to 100.From 1 to 500.
Outputs
countnumber- How many are listed
productslist- The products found, A to Z
totalnumber- How many matched, before the limit
Example output
{
"count": 1,
"products": [
{
"amount_text": "2 Bottles",
"below_min_stock": false,
"description": "",
"id": 1,
"link": "https://grocy.example.com/product/1",
"location": "Fridge",
"min_stock_amount": 2,
"name": "Milk",
"next_due_date": "2026-11-14",
"product_group": "Dairy",
"stock_amount": 2,
"unit": "Bottle"
}
],
"total": 1
}Get expiring and low stock
Get the products due soon, past their best-before date, expired and below their minimum stock, with a summary ready for a message.
Inputs
- Days ahead
daysnumber - How many days ahead counts as due soon. Defaults to 5.From 0 to 365.
Outputs
below_min_stocklist- Products below their minimum stock
below_min_stock_countnumber- How many are below minimum stock
daysnumber- The days looked ahead for 'due soon'
due_soonlist- Products whose date is within the days chosen
due_soon_countnumber- How many are due soon
expiredlist- Products past their expiration date
expired_countnumber- How many have expired
linktext- Grocy's stock overview
overduelist- Products past their best-before date
overdue_countnumber- How many are past their best-before date
texttext- All of it as text, ready for a message
Example output
{
"below_min_stock": [
{
"amount_missing": 3,
"amount_text": "3 Cans",
"link": "https://grocy.example.com/product/6",
"location": "Pantry",
"min_stock_amount": 4,
"name": "Chopped tomatoes",
"partly_in_stock": true,
"product_id": 6,
"unit": "Can"
}
],
"below_min_stock_count": 1,
"days": 5,
"due_soon": [
{
"amount": 2,
"amount_opened": 1,
"amount_text": "2 Bottles",
"below_min_stock": false,
"date_type": "best_before",
"days_until_due": 2,
"link": "https://grocy.example.com/product/1",
"location": "Fridge",
"min_stock_amount": 2,
"name": "Milk",
"next_due_date": "2026-11-14",
"product_group": "Dairy",
"product_id": 1,
"unit": "Bottle",
"value": 5
}
],
"due_soon_count": 1,
"expired": [
{
"amount": 2,
"amount_opened": 0,
"amount_text": "2 Packs",
"below_min_stock": false,
"date_type": "expires",
"days_until_due": -1,
"link": "https://grocy.example.com/product/3",
"location": "Fridge",
"min_stock_amount": 0,
"name": "Yogurt",
"next_due_date": "2026-11-11",
"product_group": "Dairy",
"product_id": 3,
"unit": "Pack",
"value": 5
}
],
"expired_count": 1,
"link": "https://grocy.example.com/stockoverview",
"overdue": [
{
"amount": 1,
"amount_opened": 0,
"amount_text": "1 Pack",
"below_min_stock": false,
"date_type": "best_before",
"days_until_due": -2,
"link": "https://grocy.example.com/product/4",
"location": "Pantry",
"min_stock_amount": 1,
"name": "Bread",
"next_due_date": "2026-11-10",
"product_group": "Baking",
"product_id": 4,
"unit": "Pack",
"value": 5
}
],
"overdue_count": 1,
"text": "Due within 5 days:\n- Milk: 2 Bottles, best before 2026-11-14, Fridge\n\nPast their best-before date:\n- Bread: 1 Pack, best before 2026-11-10, Pantry\n\nExpired:\n- Yogurt: 2 Packs, expires 2026-11-11, Fridge\n\nBelow minimum stock:\n- Chopped tomatoes: 3 Cans short"
}Get product
Get a product with how much is in stock, opened, its next due date, prices and barcodes.
Inputs
- Product
producttextRequired - The product: pick one, or give its number from another Grocy step or its name, such as Milk.
Outputs
activetrue/false- Whether the product is in use (not turned off)
amount_texttext- The amount in stock with its unit, such as 2 Bottles
average_pricenumber- The average price per unit of what's in stock
barcodeslist- Its barcodes
below_min_stocktrue/false- Whether there's less than the minimum in stock
date_typetext- best_before or expires: what its dates mean
default_best_before_daysnumber- Days a purchase keeps by default (-1 for never goes off)
descriptiontext- Its description
idnumber- The product's number, which other Grocy steps take
last_pricenumber- The price per unit paid last time
last_purchasedtext- When it was last bought (YYYY-MM-DD)
last_usedtext- When it was last used (YYYY-MM-DD)
linktext- Where it opens in Grocy
locationtext- Where it's kept by default, such as Fridge
location_idnumber- That location's number
min_stock_amountnumber- The least the household wants in stock
nametext- The product's name
next_due_datetext- The soonest date in stock (YYYY-MM-DD), or blank
product_group_idnumber- Its product group's number (0 when none)
purchase_unittext- The unit it's bought in
stock_amountnumber- How much is in stock
stock_amount_openednumber- How much of it is opened
stock_valuenumber- What the stock is worth
unittext- The unit stock is counted in, such as Bottle
Example output
{
"active": true,
"amount_text": "2 Bottles",
"average_price": 1.29,
"barcodes": [
"4006381333931"
],
"below_min_stock": false,
"date_type": "best_before",
"default_best_before_days": 7,
"description": "",
"id": 1,
"last_price": 1.29,
"last_purchased": "2026-11-12",
"last_used": "2026-11-11",
"link": "https://grocy.example.com/product/1",
"location": "Fridge",
"location_id": 2,
"min_stock_amount": 2,
"name": "Milk",
"next_due_date": "2026-11-14",
"product_group_id": 1,
"purchase_unit": "Bottle",
"stock_amount": 2,
"stock_amount_opened": 1,
"stock_value": 2.58,
"unit": "Bottle"
}Get shopping list
Get a shopping list's items, and the list as text to send to whoever does the shopping.
Inputs
- Shopping list
shopping_listtextRequired - The shopping list: pick one, or give its number from another Grocy step or its name.
- Items
showtext - Every item, or only those not done yet. Defaults to every item.One of:
all(All items),to_buy(Not done yet). Default:all.
Outputs
countnumber- How many items are listed
donenumber- How many items are done
idnumber- The list's number
itemslist- Its items, still to buy first
linktext- Where it opens in Grocy
nametext- The list's name
texttext- The list as text, to send to someone
to_buynumber- How many items aren't done
Example output
{
"count": 1,
"done": 0,
"id": 1,
"items": [
{
"amount": 6,
"done": false,
"id": 9,
"link": "https://grocy.example.com/shoppinglist?list=1",
"list_id": 1,
"note": "",
"product_id": 2,
"product_name": "Eggs",
"text": "6 Pieces Eggs",
"unit": "Piece"
}
],
"link": "https://grocy.example.com/shoppinglist?list=1",
"name": "Shopping list",
"text": "Shopping list\n- 6 Pieces Eggs",
"to_buy": 1
}Get stock
Get what's in stock at home, with each product's amount and next best-before date, everywhere or at one location such as the freezer.
Inputs
- Location
locationtext - Only this location, such as Fridge.
- Product group
product_grouptext - Only this product group, such as Dairy.
Outputs
countnumber- How many products are listed
linktext- Grocy's stock overview
productslist- Each product in stock, A to Z
texttext- The list as text, one product per line, to send to someone
total_valuenumber- What the listed stock is worth
Example output
{
"count": 1,
"link": "https://grocy.example.com/stockoverview",
"products": [
{
"amount": 2,
"amount_opened": 1,
"amount_text": "2 Bottles",
"below_min_stock": false,
"date_type": "best_before",
"days_until_due": 2,
"link": "https://grocy.example.com/product/1",
"location": "Fridge",
"min_stock_amount": 2,
"name": "Milk",
"next_due_date": "2026-11-14",
"product_group": "Dairy",
"product_id": 1,
"unit": "Bottle",
"value": 5
}
],
"text": "- Milk: 2 Bottles, 1 opened, best before 2026-11-14, Fridge",
"total_value": 5
}List batteries
List batteries, such as smoke alarms', with when each was last charged or changed and is next due.
Inputs
- Due within days
due_within_daysnumber - Only those due within this many days, 0 for today and overdue. Leave blank for all.From 0 to 365.
Outputs
batterieslist- The batteries, soonest due first
countnumber- How many are listed
linktext- Grocy's batteries overview
overduenumber- How many are overdue
texttext- The batteries as text, one per line
Example output
{
"batteries": [
{
"charge_interval_days": 180,
"days_until_due": -20,
"description": "",
"due_today": false,
"id": 1,
"last_charged": "2026-04-26 10:00:00",
"link": "https://grocy.example.com/battery/1",
"name": "Smoke alarm (hallway)",
"next_charge_date": "2026-10-23",
"next_charge_due": "2026-10-23 10:00:00",
"overdue": true,
"used_in": "Hallway"
}
],
"count": 1,
"link": "https://grocy.example.com/batteriesoverview",
"overdue": 1,
"text": "- Smoke alarm (hallway): overdue since 2026-10-23"
}List chores
List the household's chores with when each was last done and is next due, such as for a morning message.
Inputs
- Due within days
due_within_daysnumber - Only those due within this many days, 0 for today and overdue. Leave blank for all.From 0 to 365.
- Assigned to
assigned_totext - Only those assigned to this person.
Outputs
choreslist- The chores, soonest due first
countnumber- How many are listed
linktext- Grocy's chores overview
overduenumber- How many are overdue
texttext- The chores as text, one per line
Example output
{
"chores": [
{
"assigned_to": "Sam",
"assigned_to_id": 2,
"days_until_due": -1,
"due_today": false,
"id": 1,
"last_done": "2026-11-08 19:30:00",
"link": "https://grocy.example.com/chore/1",
"name": "Water the plants",
"next_due": "2026-11-11 19:30:00",
"next_due_date": "2026-11-11",
"overdue": true,
"scheduled": true
}
],
"count": 1,
"link": "https://grocy.example.com/choresoverview",
"overdue": 1,
"text": "- Water the plants: overdue since 2026-11-11"
}List recipes
List recipes with whether everything each needs is in stock, such as to choose what to cook tonight.
Inputs
- Words
wordstext - Words in the name, such as milk.
Outputs
countnumber- How many are listed
ready_to_cooknumber- How many have everything in stock
recipeslist- The recipes, A to Z
Example output
{
"count": 1,
"ready_to_cook": 0,
"recipes": [
{
"costs": 12.5,
"description": "Fluffy weekend pancakes.",
"enough_in_stock": false,
"enough_with_shopping_list": false,
"id": 1,
"ingredients": [
"Milk",
"Eggs",
"Flour",
"Butter"
],
"link": "https://grocy.example.com/recipes?recipe=1",
"missing_products_count": 2,
"name": "Pancakes",
"servings": 4
}
]
}List tasks
List tasks with when each is due: those not done, done or all.
Inputs
- Status
statustext - Which tasks. Defaults to those not done.One of:
open(Not done),done,all. Default:open. - Due within days
due_within_daysnumber - Only those due within this many days, 0 for today and overdue. Leave blank for all.From 0 to 365.
- Category
categorytext - Only this category.
- Assigned to
assigned_totext - Only those assigned to this person.
Outputs
countnumber- How many are listed
linktext- Grocy's tasks page
overduenumber- How many are overdue
taskslist- The tasks, soonest due first
texttext- The tasks as text, one per line
Example output
{
"count": 1,
"link": "https://grocy.example.com/tasks",
"overdue": 0,
"tasks": [
{
"assigned_to": "Sam",
"assigned_to_id": 2,
"category": "Home",
"days_until_due": 1,
"description": "The kitchen tap drips.",
"done": false,
"done_at": "",
"due_date": "2026-11-13",
"due_today": false,
"id": 4,
"link": "https://grocy.example.com/task/4",
"name": "Call the plumber",
"overdue": false
}
],
"text": "- Call the plumber: due 2026-11-13"
}Mark chore done
Mark a chore done, or skipped, now or at a time. Grocy works out when it's next due.
Inputs
- Chore
choretextRequired - The chore: pick one, or give its number from another Grocy step or its name.
- Done at
done_atdate and time - When it was done. Leave blank for now.
- Done by
done_bytext - Who did it. Leave blank for you.
- Skipped
skippedtrue/false - Mark it skipped rather than done.Default:
false.
Outputs
assigned_totext- Who does it next, if assigned
assigned_to_idnumber- Their user number (0 when no one)
days_until_duenumber- Days until it's due (negative when overdue), empty with no schedule
done_bytext- Who did it
due_todaytrue/false- Whether it's due today
execution_idnumber- This execution's number, which 'Undo chore' takes
idnumber- The chore's number, which other Grocy steps take
last_donetext- When it was last done (YYYY-MM-DD HH:MM:SS, Grocy's time)
linktext- Where the chore opens in Grocy
nametext- The chore's name
next_duetext- When it's next due (Grocy's time), blank with no schedule
next_due_datetext- The day it's next due (YYYY-MM-DD)
overduetrue/false- Whether it's overdue
scheduledtrue/false- Whether it has a schedule (not done only when needed)
skippedtrue/false- Whether it was skipped rather than done
tracked_timetext- When it was marked done (Grocy's time)
Example output
{
"assigned_to": "Sam",
"assigned_to_id": 2,
"days_until_due": 3,
"done_by": "Sam",
"due_today": false,
"execution_id": 42,
"id": 1,
"last_done": "2026-11-12 18:00:00",
"link": "https://grocy.example.com/chore/1",
"name": "Water the plants",
"next_due": "2026-11-15 18:00:00",
"next_due_date": "2026-11-15",
"overdue": false,
"scheduled": true,
"skipped": false,
"tracked_time": "2026-11-12 18:00:00"
}Mark product opened
Mark an amount of a product as opened, such as a jar of jam.
Inputs
- Product
producttextRequired - The product: pick one, or give its number from another Grocy step or its name, such as Milk.
- Amount
amountnumberRequired - How much, in the product's stock unit, such as 2 for two bottles.From 0 to 1000000.
Outputs
amountnumber- How much was booked, in the product's unit
best_before_datetext- The date of the stock it touched (YYYY-MM-DD)
linktext- Where the product opens in Grocy
next_due_datetext- The soonest date in stock now, or blank
pricenumber- The price per unit of that stock
product_idnumber- The product's number
product_nametext- The product's name
stock_amountnumber- How much is in stock now
stock_amount_openednumber- How much of it is opened now
transaction_idtext- The change's transaction ID, which 'Undo stock change' takes
unittext- The product's unit
Example output
{
"amount": 2,
"best_before_date": "2026-11-19",
"link": "https://grocy.example.com/product/1",
"next_due_date": "2026-11-14",
"price": 1.29,
"product_id": 1,
"product_name": "Milk",
"stock_amount": 3,
"stock_amount_opened": 0,
"transaction_id": "6af63f498ed35",
"unit": "Bottle"
}Move product
Move an amount of a product from one location to another, such as from the fridge to the freezer.
Inputs
- Product
producttextRequired - The product: pick one, or give its number from another Grocy step or its name, such as Milk.
- Amount
amountnumberRequired - How much, in the product's stock unit, such as 2 for two bottles.From 0 to 1000000.
- From
from_locationtextRequired - Where it is now, such as Fridge.
- To
to_locationtextRequired - Where it goes, such as Freezer.
Outputs
amountnumber- How much was booked, in the product's unit
best_before_datetext- The date of the stock it touched (YYYY-MM-DD)
from_locationtext- Where it was moved from
linktext- Where the product opens in Grocy
next_due_datetext- The soonest date in stock now, or blank
pricenumber- The price per unit of that stock
product_idnumber- The product's number
product_nametext- The product's name
stock_amountnumber- How much is in stock now
stock_amount_openednumber- How much of it is opened now
to_locationtext- Where it was moved to
transaction_idtext- The change's transaction ID, which 'Undo stock change' takes
unittext- The product's unit
Example output
{
"amount": 1,
"best_before_date": "2026-11-19",
"from_location": "Fridge",
"link": "https://grocy.example.com/product/1",
"next_due_date": "2026-11-14",
"price": 1.29,
"product_id": 1,
"product_name": "Milk",
"stock_amount": 3,
"stock_amount_opened": 0,
"to_location": "Freezer",
"transaction_id": "6af63f498ed35",
"unit": "Bottle"
}Record battery charge
Record that a battery was charged or changed, now or at a time.
Inputs
- Battery
batterytextRequired - The battery: pick one, or give its number from another Grocy step or its name.
- Charged at
charged_atdate and time - When. Leave blank for now.
Outputs
charge_cycle_idnumber- This charge's number, which 'Undo battery charge' takes
charge_interval_daysnumber- Days between charges (0 when not set)
days_until_duenumber- Days until it's due (negative when overdue), empty with no schedule
descriptiontext- Its description
due_todaytrue/false- Whether it's due today
idnumber- The battery's number, which other Grocy steps take
last_chargedtext- When it was last charged (Grocy's time)
linktext- Where the battery opens in Grocy
nametext- The battery's name
next_charge_datetext- The day it's next due a charge (YYYY-MM-DD)
next_charge_duetext- When it's next due a charge, blank when not set
overduetrue/false- Whether it's overdue
tracked_timetext- When it was charged (Grocy's time)
used_intext- What it's used in
Example output
{
"charge_cycle_id": 7,
"charge_interval_days": 180,
"days_until_due": 180,
"description": "",
"due_today": false,
"id": 1,
"last_charged": "2026-11-12 18:00:00",
"link": "https://grocy.example.com/battery/1",
"name": "Smoke alarm (hallway)",
"next_charge_date": "2027-05-11",
"next_charge_due": "2027-05-11 18:00:00",
"overdue": false,
"tracked_time": "2026-11-12 18:00:00",
"used_in": "Hallway"
}Remove from shopping list
Take an item off a shopping list, or take some of its amount off.
Inputs
- Shopping list
shopping_listtextRequired - The shopping list: pick one, or give its number from another Grocy step or its name.
- Item
itemtextRequired - The item: its number from another Grocy step, or its product or note as the list shows it, such as Eggs.
- Amount
amountnumber - How much to take off. Leave blank to take the whole item off.From 0 to 1000000.
Outputs
amountnumber- How much to buy
amount_leftnumber- How much is left on the list
donetrue/false- Whether it's ticked off
idnumber- The item's number, which 'Remove item' takes
linktext- Where the list opens in Grocy
list_idnumber- The shopping list's number
list_nametext- The list's name
notetext- The item's note, or the item itself when it's not a product
product_idnumber- The product's number (0 for a note)
product_nametext- The product's name (blank for a note)
removedtrue/false- Whether the whole item came off (false when some is left)
texttext- The item as the list shows it, such as 6 Pieces Eggs
unittext- The unit, for a product
Example output
{
"amount": 6,
"amount_left": 0,
"done": false,
"id": 9,
"link": "https://grocy.example.com/shoppinglist?list=1",
"list_id": 1,
"list_name": "Shopping list",
"note": "",
"product_id": 2,
"product_name": "Eggs",
"removed": true,
"text": "6 Pieces Eggs",
"unit": "Piece"
}Reopen task
Mark a done task as not done.
Inputs
- Task
tasktextRequired - The task: its number from another Grocy step, or its name.
Outputs
assigned_totext- Who it's assigned to
assigned_to_idnumber- Their user number (0 when no one)
categorytext- Its category
days_until_duenumber- Days until it's due (negative when overdue), empty with no schedule
descriptiontext- Its description
donetrue/false- Whether it's done
done_attext- When it was done (Grocy's time), or blank
due_datetext- When it's due (YYYY-MM-DD), or blank
due_todaytrue/false- Whether it's due today
idnumber- The task's number, which other Grocy steps take
linktext- Where the task opens in Grocy
nametext- What needs doing
overduetrue/false- Whether it's overdue
Example output
{
"assigned_to": "Sam",
"assigned_to_id": 2,
"category": "Home",
"days_until_due": 1,
"description": "The kitchen tap drips.",
"done": false,
"done_at": "",
"due_date": "2026-11-13",
"due_today": false,
"id": 4,
"link": "https://grocy.example.com/task/4",
"name": "Call the plumber",
"overdue": false
}Undo battery charge
Undo a battery charge, by the charge ID 'Record battery charge' returned.
Inputs
- Charge
charge_cycletextRequired - The charge ID 'Record battery charge' returned, such as 7.
Outputs
charge_cycle_idnumber- The charge undone
charge_interval_daysnumber- Days between charges (0 when not set)
days_until_duenumber- Days until it's due (negative when overdue), empty with no schedule
descriptiontext- Its description
due_todaytrue/false- Whether it's due today
idnumber- The battery's number, which other Grocy steps take
last_chargedtext- When it was last charged (Grocy's time)
linktext- Where the battery opens in Grocy
nametext- The battery's name
next_charge_datetext- The day it's next due a charge (YYYY-MM-DD)
next_charge_duetext- When it's next due a charge, blank when not set
overduetrue/false- Whether it's overdue
undonetrue/false- Always true
used_intext- What it's used in
Example output
{
"charge_cycle_id": 7,
"charge_interval_days": 180,
"days_until_due": -20,
"description": "",
"due_today": false,
"id": 1,
"last_charged": "2026-04-26 10:00:00",
"link": "https://grocy.example.com/battery/1",
"name": "Smoke alarm (hallway)",
"next_charge_date": "2026-10-23",
"next_charge_due": "2026-10-23 10:00:00",
"overdue": true,
"undone": true,
"used_in": "Hallway"
}Undo chore
Undo a chore marked done, by the execution ID 'Mark chore done' returned.
Inputs
- Execution
executiontextRequired - The execution ID 'Mark chore done' returned, such as 42.
Outputs
assigned_totext- Who does it next, if assigned
assigned_to_idnumber- Their user number (0 when no one)
days_until_duenumber- Days until it's due (negative when overdue), empty with no schedule
due_todaytrue/false- Whether it's due today
execution_idnumber- The execution undone
idnumber- The chore's number, which other Grocy steps take
last_donetext- When it was last done (YYYY-MM-DD HH:MM:SS, Grocy's time)
linktext- Where the chore opens in Grocy
nametext- The chore's name
next_duetext- When it's next due (Grocy's time), blank with no schedule
next_due_datetext- The day it's next due (YYYY-MM-DD)
overduetrue/false- Whether it's overdue
scheduledtrue/false- Whether it has a schedule (not done only when needed)
undonetrue/false- Always true
Example output
{
"assigned_to": "Sam",
"assigned_to_id": 2,
"days_until_due": -1,
"due_today": false,
"execution_id": 42,
"id": 1,
"last_done": "2026-11-08 19:30:00",
"link": "https://grocy.example.com/chore/1",
"name": "Water the plants",
"next_due": "2026-11-11 19:30:00",
"next_due_date": "2026-11-11",
"overdue": true,
"scheduled": true,
"undone": true
}Undo stock change
Undo a purchase, use, opening or move, by the transaction ID the step that made it returned.
Inputs
- Transaction
transactiontextRequired - The transaction ID from 'Add purchase', 'Use product', 'Mark product opened' or 'Move product'.
Outputs
changetext- What it was: purchase, consume, product-opened, transfer_from
linktext- Where the product opens in Grocy
product_idnumber- The product's number
product_nametext- The product's name
stock_amountnumber- How much is in stock now
transaction_idtext- The transaction undone
undonetrue/false- Always true
Example output
{
"change": "purchase",
"link": "https://grocy.example.com/product/1",
"product_id": 1,
"product_name": "Milk",
"stock_amount": 1,
"transaction_id": "6af63f498ed35",
"undone": true
}Update product
Change a product's name, location, unit, minimum stock or other details, or add a barcode. Fields left blank stay as they are.
Inputs
- Product
producttextRequired - The product: pick one, or give its number from another Grocy step or its name, such as Milk.
- Name
nametext - What the product is called, such as Oat milk.
- Location
locationtext - Where it's kept by default, such as Fridge.
- Unit
quantity_unittext - What it's counted and bought in, such as Bottle or Piece.
- Minimum stock
min_stock_amountnumber - The least you want at home. Below it, the product shows as running low.From 0 to 1000000.
- Default due days
default_best_before_daysnumber - How many days a purchase keeps, such as 7; -1 for never goes off.From -1 to 36500.
- Date type
date_typetext - Whether its dates are best-before dates (still fine after) or expiration dates. Defaults to best before.One of:
best_before(Best before),expires(Expiration date). Default:best_before. - Product group
product_grouptext - Its product group, such as Dairy.
- Description
descriptiontext - A note about the product.
- Barcode
barcodetext - A barcode to add to it, such as 4006381333931.
Outputs
activetrue/false- Whether the product is in use (not turned off)
amount_texttext- The amount in stock with its unit, such as 2 Bottles
average_pricenumber- The average price per unit of what's in stock
barcodeslist- Its barcodes
below_min_stocktrue/false- Whether there's less than the minimum in stock
date_typetext- best_before or expires: what its dates mean
default_best_before_daysnumber- Days a purchase keeps by default (-1 for never goes off)
descriptiontext- Its description
idnumber- The product's number, which other Grocy steps take
last_pricenumber- The price per unit paid last time
last_purchasedtext- When it was last bought (YYYY-MM-DD)
last_usedtext- When it was last used (YYYY-MM-DD)
linktext- Where it opens in Grocy
locationtext- Where it's kept by default, such as Fridge
location_idnumber- That location's number
min_stock_amountnumber- The least the household wants in stock
nametext- The product's name
next_due_datetext- The soonest date in stock (YYYY-MM-DD), or blank
product_group_idnumber- Its product group's number (0 when none)
purchase_unittext- The unit it's bought in
stock_amountnumber- How much is in stock
stock_amount_openednumber- How much of it is opened
stock_valuenumber- What the stock is worth
unittext- The unit stock is counted in, such as Bottle
Example output
{
"active": true,
"amount_text": "2 Bottles",
"average_price": 1.29,
"barcodes": [
"4006381333931"
],
"below_min_stock": false,
"date_type": "best_before",
"default_best_before_days": 7,
"description": "",
"id": 1,
"last_price": 1.29,
"last_purchased": "2026-11-12",
"last_used": "2026-11-11",
"link": "https://grocy.example.com/product/1",
"location": "Fridge",
"location_id": 2,
"min_stock_amount": 2,
"name": "Milk",
"next_due_date": "2026-11-14",
"product_group_id": 1,
"purchase_unit": "Bottle",
"stock_amount": 2,
"stock_amount_opened": 1,
"stock_value": 2.58,
"unit": "Bottle"
}Use product
Take an amount of a product out of stock, used or thrown away as spoiled. The soonest due goes first.
Inputs
- Product
producttextRequired - The product: pick one, or give its number from another Grocy step or its name, such as Milk.
- Amount
amountnumberRequired - How much, in the product's stock unit, such as 2 for two bottles.From 0 to 1000000.
- Spoiled
spoiledtrue/false - Book it as thrown away rather than used.Default:
false. - Location
locationtext - Take it from this location. Leave blank for anywhere.
Outputs
amountnumber- How much was booked, in the product's unit
best_before_datetext- The date of the stock it touched (YYYY-MM-DD)
linktext- Where the product opens in Grocy
next_due_datetext- The soonest date in stock now, or blank
pricenumber- The price per unit of that stock
product_idnumber- The product's number
product_nametext- The product's name
spoiledtrue/false- Whether it was thrown away as spoiled
stock_amountnumber- How much is in stock now
stock_amount_openednumber- How much of it is opened now
transaction_idtext- The change's transaction ID, which 'Undo stock change' takes
unittext- The product's unit
Example output
{
"amount": 1,
"best_before_date": "2026-11-14",
"link": "https://grocy.example.com/product/1",
"next_due_date": "2026-11-14",
"price": 1.29,
"product_id": 1,
"product_name": "Milk",
"spoiled": false,
"stock_amount": 1,
"stock_amount_opened": 0,
"transaction_id": "6af63f498ed35",
"unit": "Bottle"
}