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

ActionWhat it does
Add products to restockPut the products below their minimum stock, past their best-before date or expired on a shopping list.
Add purchaseBook a purchase into stock, with its best-before date, price and where it's put away.
Add recipe to shopping listPut what a recipe needs and isn't in stock on a shopping list.
Add to shopping listPut a product, or anything else written as a note such as Birthday candles, on a shopping list.
Clear shopping listTake every item off a shopping list, or only the ones ticked off.
Complete taskMark a task done, now or at a time.
Create productAdd a product to Grocy, with where it's kept, its unit, minimum stock and a barcode.
Create shopping listMake a shopping list, such as for a party.
Create taskAdd a task, with a due date, a category and who it's for.
Delete productDelete a product, with its stock and barcodes.
Delete shopping listDelete a shopping list with its items.
Delete taskDelete a task.
Find product by barcodeFind the product a barcode belongs to, such as one scanned on a phone, with its stock.
Find productsFind products by words in their name, location or product group, with how much of each is in stock.
Get expiring and low stockGet the products due soon, past their best-before date, expired and below their minimum stock, with a summary ready for a message.
Get productGet a product with how much is in stock, opened, its next due date, prices and barcodes.
Get shopping listGet a shopping list's items, and the list as text to send to whoever does the shopping.
Get stockGet 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 batteriesList batteries, such as smoke alarms', with when each was last charged or changed and is next due.
List choresList the household's chores with when each was last done and is next due, such as for a morning message.
List recipesList recipes with whether everything each needs is in stock, such as to choose what to cook tonight.
List tasksList tasks with when each is due: those not done, done or all.
Mark chore doneMark a chore done, or skipped, now or at a time.
Mark product openedMark an amount of a product as opened, such as a jar of jam.
Move productMove an amount of a product from one location to another, such as from the fridge to the freezer.
Record battery chargeRecord that a battery was charged or changed, now or at a time.
Remove from shopping listTake an item off a shopping list, or take some of its amount off.
Reopen taskMark a done task as not done.
Undo battery chargeUndo a battery charge, by the charge ID 'Record battery charge' returned.
Undo choreUndo a chore marked done, by the execution ID 'Mark chore done' returned.
Undo stock changeUndo a purchase, use, opening or move, by the transaction ID the step that made it returned.
Update productChange a product's name, location, unit, minimum stock or other details, or add a barcode.
Use productTake 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 listshopping_listtextRequired
The shopping list: pick one, or give its number from another Grocy step or its name.
Which productswhichtext
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

ProductproducttextRequired
The product: pick one, or give its number from another Grocy step or its name, such as Milk.
AmountamountnumberRequired
How much, in the product's stock unit, such as 2 for two bottles.From 0 to 1000000.
Best-before datebest_before_datedate
When it's due. Leave blank for the product's default due days.
Pricepricenumber
The price per unit, such as 1.29.From 0 to 1000000.
Locationlocationtext
Where it's put away. Leave blank for the product's default.
Storestoretext
Where it was bought.
Notenotetext
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

ReciperecipetextRequired
The recipe: pick one, or give its number from another Grocy step or its name.
Shopping listshopping_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 listshopping_listtextRequired
The shopping list: pick one, or give its number from another Grocy step or its name.
Productproducttext
The product: pick one, or give its number from another Grocy step or its name. Leave blank to add a note instead.
Notenotetext
What to buy when it's not a product, or a note on the product.
Amountamountnumber
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 listshopping_listtextRequired
The shopping list: pick one, or give its number from another Grocy step or its name.
Only done itemsdone_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

TasktasktextRequired
The task: pick one, or give its number from another Grocy step or its name.
Done atdone_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

NamenametextRequired
What the product is called, such as Oat milk.
LocationlocationtextRequired
Where it's kept by default, such as Fridge.
Unitquantity_unittextRequired
What it's counted and bought in, such as Bottle or Piece.
Minimum stockmin_stock_amountnumber
The least you want at home. Below it, the product shows as running low.From 0 to 1000000.
Default due daysdefault_best_before_daysnumber
How many days a purchase keeps, such as 7; -1 for never goes off.From -1 to 36500.
Date typedate_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 groupproduct_grouptext
Its product group, such as Dairy.
Descriptiondescriptiontext
A note about the product.
Barcodebarcodetext
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

NamenametextRequired
What the list is called.
Descriptiondescriptiontext
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

NamenametextRequired
What needs doing.
Descriptiondescriptiontext
More about it.
Due datedue_datedate
When it's due.
Categorycategorytext
Its category, such as Home.
Assigned toassigned_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

ProductproducttextRequired
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 listshopping_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

TasktasktextRequired
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

BarcodebarcodetextRequired
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

Wordswordstext
Words in the name, such as milk.
Locationlocationtext
Only this location, such as Fridge.
Product groupproduct_grouptext
Only this product group, such as Dairy.
How manylimitnumber
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 aheaddaysnumber
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

ProductproducttextRequired
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 listshopping_listtextRequired
The shopping list: pick one, or give its number from another Grocy step or its name.
Itemsshowtext
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

Locationlocationtext
Only this location, such as Fridge.
Product groupproduct_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 daysdue_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 daysdue_within_daysnumber
Only those due within this many days, 0 for today and overdue. Leave blank for all.From 0 to 365.
Assigned toassigned_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

Wordswordstext
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

Statusstatustext
Which tasks. Defaults to those not done.One of: open (Not done), done, all. Default: open.
Due within daysdue_within_daysnumber
Only those due within this many days, 0 for today and overdue. Leave blank for all.From 0 to 365.
Categorycategorytext
Only this category.
Assigned toassigned_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

ChorechoretextRequired
The chore: pick one, or give its number from another Grocy step or its name.
Done atdone_atdate and time
When it was done. Leave blank for now.
Done bydone_bytext
Who did it. Leave blank for you.
Skippedskippedtrue/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

ProductproducttextRequired
The product: pick one, or give its number from another Grocy step or its name, such as Milk.
AmountamountnumberRequired
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

ProductproducttextRequired
The product: pick one, or give its number from another Grocy step or its name, such as Milk.
AmountamountnumberRequired
How much, in the product's stock unit, such as 2 for two bottles.From 0 to 1000000.
Fromfrom_locationtextRequired
Where it is now, such as Fridge.
Toto_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

BatterybatterytextRequired
The battery: pick one, or give its number from another Grocy step or its name.
Charged atcharged_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 listshopping_listtextRequired
The shopping list: pick one, or give its number from another Grocy step or its name.
ItemitemtextRequired
The item: its number from another Grocy step, or its product or note as the list shows it, such as Eggs.
Amountamountnumber
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

TasktasktextRequired
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

Chargecharge_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

ExecutionexecutiontextRequired
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

TransactiontransactiontextRequired
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

ProductproducttextRequired
The product: pick one, or give its number from another Grocy step or its name, such as Milk.
Namenametext
What the product is called, such as Oat milk.
Locationlocationtext
Where it's kept by default, such as Fridge.
Unitquantity_unittext
What it's counted and bought in, such as Bottle or Piece.
Minimum stockmin_stock_amountnumber
The least you want at home. Below it, the product shows as running low.From 0 to 1000000.
Default due daysdefault_best_before_daysnumber
How many days a purchase keeps, such as 7; -1 for never goes off.From -1 to 36500.
Date typedate_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 groupproduct_grouptext
Its product group, such as Dairy.
Descriptiondescriptiontext
A note about the product.
Barcodebarcodetext
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

ProductproducttextRequired
The product: pick one, or give its number from another Grocy step or its name, such as Milk.
AmountamountnumberRequired
How much, in the product's stock unit, such as 2 for two bottles.From 0 to 1000000.
Spoiledspoiledtrue/false
Book it as thrown away rather than used.Default: false.
Locationlocationtext
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"
}

On this page