# Grocy

> 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.

App · 33 actions. Web page: https://docs.lodol.com/docs/integrations/grocy

## Actions

### 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_list`, text, required): The shopping list: pick one, or give its number from another Grocy step or its name.
- Which products (`which`, text): 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**

- `count` (number): How many items changed
- `items` (list): The items added, or added to
- `link` (text): Where the list opens in Grocy
- `list_id` (number): The list's number
- `list_name` (text): The list's name
- `which` (text): Which products: below_min, overdue, expired or all

**Example output**

```json
{
  "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 (`product`, text, required): The product: pick one, or give its number from another Grocy step or its name, such as Milk.
- Amount (`amount`, number, required): How much, in the product's stock unit, such as 2 for two bottles. From 0 to 1000000.
- Best-before date (`best_before_date`, date): When it's due. Leave blank for the product's default due days.
- Price (`price`, number): The price per unit, such as 1.29. From 0 to 1000000.
- Location (`location`, text): Where it's put away. Leave blank for the product's default.
- Store (`store`, text): Where it was bought.
- Note (`note`, text): A note on this stock, such as Opened at work.

**Outputs**

- `amount` (number): How much was booked, in the product's unit
- `best_before_date` (text): The date of the stock it touched (YYYY-MM-DD)
- `link` (text): Where the product opens in Grocy
- `next_due_date` (text): The soonest date in stock now, or blank
- `price` (number): The price per unit of that stock
- `product_id` (number): The product's number
- `product_name` (text): The product's name
- `stock_amount` (number): How much is in stock now
- `stock_amount_opened` (number): How much of it is opened now
- `transaction_id` (text): The change's transaction ID, which 'Undo stock change' takes
- `unit` (text): The product's unit

**Example output**

```json
{
  "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 (`recipe`, text, required): The recipe: pick one, or give its number from another Grocy step or its name.
- Shopping list (`shopping_list`, text): The list to put them on. Leave blank for Grocy's own list.

**Outputs**

- `count` (number): How many items changed (0 when nothing was missing)
- `items` (list): The items added, or added to
- `link` (text): Where the list opens in Grocy
- `list_id` (number): The list's number
- `list_name` (text): The list's name
- `recipe_id` (number): The recipe's number
- `recipe_name` (text): The recipe's name

**Example output**

```json
{
  "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_list`, text, required): The shopping list: pick one, or give its number from another Grocy step or its name.
- Product (`product`, text): The product: pick one, or give its number from another Grocy step or its name. Leave blank to add a note instead.
- Note (`note`, text): What to buy when it's not a product, or a note on the product.
- Amount (`amount`, number): How much, in the product's stock unit. Defaults to 1. From 0 to 1000000.

**Outputs**

- `amount` (number): How much to buy
- `done` (true/false): Whether it's ticked off
- `id` (number): The item's number, which 'Remove item' takes
- `link` (text): Where the list opens in Grocy
- `list_id` (number): The shopping list's number
- `list_name` (text): The list's name
- `note` (text): The item's note, or the item itself when it's not a product
- `product_id` (number): The product's number (0 for a note)
- `product_name` (text): The product's name (blank for a note)
- `text` (text): The item as the list shows it, such as 6 Pieces Eggs
- `unit` (text): The unit, for a product

**Example output**

```json
{
  "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_list`, text, required): The shopping list: pick one, or give its number from another Grocy step or its name.
- Only done items (`done_only`, true/false): Take off only the ticked items. Default: `false`.

**Outputs**

- `done_only` (true/false): Whether only done items were taken off
- `items_left` (number): How many are left
- `link` (text): Where the list opens in Grocy
- `list_id` (number): The list's number
- `list_name` (text): The list's name
- `removed` (number): How many items came off

**Example output**

```json
{
  "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 (`task`, text, required): The task: pick one, or give its number from another Grocy step or its name.
- Done at (`done_at`, date and time): When it was done. Leave blank for now.

**Outputs**

- `assigned_to` (text): Who it's assigned to
- `assigned_to_id` (number): Their user number (0 when no one)
- `category` (text): Its category
- `days_until_due` (number): Days until it's due (negative when overdue), empty with no schedule
- `description` (text): Its description
- `done` (true/false): Whether it's done
- `done_at` (text): When it was done (Grocy's time), or blank
- `due_date` (text): When it's due (YYYY-MM-DD), or blank
- `due_today` (true/false): Whether it's due today
- `id` (number): The task's number, which other Grocy steps take
- `link` (text): Where the task opens in Grocy
- `name` (text): What needs doing
- `overdue` (true/false): Whether it's overdue

**Example output**

```json
{
  "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 (`name`, text, required): What the product is called, such as Oat milk.
- Location (`location`, text, required): Where it's kept by default, such as Fridge.
- Unit (`quantity_unit`, text, required): What it's counted and bought in, such as Bottle or Piece.
- Minimum stock (`min_stock_amount`, number): The least you want at home. Below it, the product shows as running low. From 0 to 1000000.
- Default due days (`default_best_before_days`, number): How many days a purchase keeps, such as 7; -1 for never goes off. From -1 to 36500.
- Date type (`date_type`, text): 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_group`, text): Its product group, such as Dairy.
- Description (`description`, text): A note about the product.
- Barcode (`barcode`, text): A barcode to add to it, such as 4006381333931.

**Outputs**

- `active` (true/false): Whether the product is in use (not turned off)
- `amount_text` (text): The amount in stock with its unit, such as 2 Bottles
- `average_price` (number): The average price per unit of what's in stock
- `barcodes` (list): Its barcodes
- `below_min_stock` (true/false): Whether there's less than the minimum in stock
- `date_type` (text): best_before or expires: what its dates mean
- `default_best_before_days` (number): Days a purchase keeps by default (-1 for never goes off)
- `description` (text): Its description
- `id` (number): The product's number, which other Grocy steps take
- `last_price` (number): The price per unit paid last time
- `last_purchased` (text): When it was last bought (YYYY-MM-DD)
- `last_used` (text): When it was last used (YYYY-MM-DD)
- `link` (text): Where it opens in Grocy
- `location` (text): Where it's kept by default, such as Fridge
- `location_id` (number): That location's number
- `min_stock_amount` (number): The least the household wants in stock
- `name` (text): The product's name
- `next_due_date` (text): The soonest date in stock (YYYY-MM-DD), or blank
- `product_group_id` (number): Its product group's number (0 when none)
- `purchase_unit` (text): The unit it's bought in
- `stock_amount` (number): How much is in stock
- `stock_amount_opened` (number): How much of it is opened
- `stock_value` (number): What the stock is worth
- `unit` (text): The unit stock is counted in, such as Bottle

**Example output**

```json
{
  "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 (`name`, text, required): What the list is called.
- Description (`description`, text): A note about the list.

**Outputs**

- `description` (text): Its description
- `id` (number): The new list's number, which other Grocy steps take
- `link` (text): Where it opens in Grocy
- `name` (text): Its name

**Example output**

```json
{
  "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 (`name`, text, required): What needs doing.
- Description (`description`, text): More about it.
- Due date (`due_date`, date): When it's due.
- Category (`category`, text): Its category, such as Home.
- Assigned to (`assigned_to`, text): Who it's for.

**Outputs**

- `assigned_to` (text): Who it's assigned to
- `assigned_to_id` (number): Their user number (0 when no one)
- `category` (text): Its category
- `days_until_due` (number): Days until it's due (negative when overdue), empty with no schedule
- `description` (text): Its description
- `done` (true/false): Whether it's done
- `done_at` (text): When it was done (Grocy's time), or blank
- `due_date` (text): When it's due (YYYY-MM-DD), or blank
- `due_today` (true/false): Whether it's due today
- `id` (number): The task's number, which other Grocy steps take
- `link` (text): Where the task opens in Grocy
- `name` (text): What needs doing
- `overdue` (true/false): Whether it's overdue

**Example output**

```json
{
  "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 (`product`, text, required): The product: pick one, or give its number from another Grocy step or its name, such as Milk.

**Outputs**

- `deleted` (true/false): Always true
- `id` (number): The product's number
- `name` (text): The product's name
- `stock_amount_deleted` (number): How much stock was deleted with it

**Example output**

```json
{
  "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_list`, text, required): The shopping list: pick one, or give its number from another Grocy step or its name.

**Outputs**

- `deleted` (true/false): Always true
- `id` (number): The list's number
- `items_deleted` (number): How many items went with it
- `name` (text): The list's name

**Example output**

```json
{
  "deleted": true,
  "id": 3,
  "items_deleted": 5,
  "name": "Party"
}
```

### Delete task

Delete a task. It can't be brought back from Lodol.

**Inputs**

- Task (`task`, text, required): The task: pick one, or give its number from another Grocy step or its name.

**Outputs**

- `deleted` (true/false): Always true
- `id` (number): The task's number
- `name` (text): What it was

**Example output**

```json
{
  "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 (`barcode`, text, required): The barcode's number, such as 4006381333931.

**Outputs**

- `active` (true/false): Whether the product is in use (not turned off)
- `amount_text` (text): The amount in stock with its unit, such as 2 Bottles
- `average_price` (number): The average price per unit of what's in stock
- `barcode` (text): The barcode looked up
- `barcodes` (list): Its barcodes
- `below_min_stock` (true/false): Whether there's less than the minimum in stock
- `date_type` (text): best_before or expires: what its dates mean
- `default_best_before_days` (number): Days a purchase keeps by default (-1 for never goes off)
- `description` (text): Its description
- `found` (true/false): Whether a product has the barcode; the rest is blank when not
- `id` (number): The product's number, which other Grocy steps take
- `last_price` (number): The price per unit paid last time
- `last_purchased` (text): When it was last bought (YYYY-MM-DD)
- `last_used` (text): When it was last used (YYYY-MM-DD)
- `link` (text): Where it opens in Grocy
- `location` (text): Where it's kept by default, such as Fridge
- `location_id` (number): That location's number
- `min_stock_amount` (number): The least the household wants in stock
- `name` (text): The product's name
- `next_due_date` (text): The soonest date in stock (YYYY-MM-DD), or blank
- `product_group_id` (number): Its product group's number (0 when none)
- `purchase_unit` (text): The unit it's bought in
- `stock_amount` (number): How much is in stock
- `stock_amount_opened` (number): How much of it is opened
- `stock_value` (number): What the stock is worth
- `unit` (text): The unit stock is counted in, such as Bottle

**Example output**

```json
{
  "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 (`words`, text): Words in the name, such as milk.
- Location (`location`, text): Only this location, such as Fridge.
- Product group (`product_group`, text): Only this product group, such as Dairy.
- How many (`limit`, number): The most to list. Defaults to 100. From 1 to 500.

**Outputs**

- `count` (number): How many are listed
- `products` (list): The products found, A to Z
- `total` (number): How many matched, before the limit

**Example output**

```json
{
  "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 (`days`, number): How many days ahead counts as due soon. Defaults to 5. From 0 to 365.

**Outputs**

- `below_min_stock` (list): Products below their minimum stock
- `below_min_stock_count` (number): How many are below minimum stock
- `days` (number): The days looked ahead for 'due soon'
- `due_soon` (list): Products whose date is within the days chosen
- `due_soon_count` (number): How many are due soon
- `expired` (list): Products past their expiration date
- `expired_count` (number): How many have expired
- `link` (text): Grocy's stock overview
- `overdue` (list): Products past their best-before date
- `overdue_count` (number): How many are past their best-before date
- `text` (text): All of it as text, ready for a message

**Example output**

```json
{
  "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 (`product`, text, required): The product: pick one, or give its number from another Grocy step or its name, such as Milk.

**Outputs**

- `active` (true/false): Whether the product is in use (not turned off)
- `amount_text` (text): The amount in stock with its unit, such as 2 Bottles
- `average_price` (number): The average price per unit of what's in stock
- `barcodes` (list): Its barcodes
- `below_min_stock` (true/false): Whether there's less than the minimum in stock
- `date_type` (text): best_before or expires: what its dates mean
- `default_best_before_days` (number): Days a purchase keeps by default (-1 for never goes off)
- `description` (text): Its description
- `id` (number): The product's number, which other Grocy steps take
- `last_price` (number): The price per unit paid last time
- `last_purchased` (text): When it was last bought (YYYY-MM-DD)
- `last_used` (text): When it was last used (YYYY-MM-DD)
- `link` (text): Where it opens in Grocy
- `location` (text): Where it's kept by default, such as Fridge
- `location_id` (number): That location's number
- `min_stock_amount` (number): The least the household wants in stock
- `name` (text): The product's name
- `next_due_date` (text): The soonest date in stock (YYYY-MM-DD), or blank
- `product_group_id` (number): Its product group's number (0 when none)
- `purchase_unit` (text): The unit it's bought in
- `stock_amount` (number): How much is in stock
- `stock_amount_opened` (number): How much of it is opened
- `stock_value` (number): What the stock is worth
- `unit` (text): The unit stock is counted in, such as Bottle

**Example output**

```json
{
  "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_list`, text, required): The shopping list: pick one, or give its number from another Grocy step or its name.
- Items (`show`, text): 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**

- `count` (number): How many items are listed
- `done` (number): How many items are done
- `id` (number): The list's number
- `items` (list): Its items, still to buy first
- `link` (text): Where it opens in Grocy
- `name` (text): The list's name
- `text` (text): The list as text, to send to someone
- `to_buy` (number): How many items aren't done

**Example output**

```json
{
  "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 (`location`, text): Only this location, such as Fridge.
- Product group (`product_group`, text): Only this product group, such as Dairy.

**Outputs**

- `count` (number): How many products are listed
- `link` (text): Grocy's stock overview
- `products` (list): Each product in stock, A to Z
- `text` (text): The list as text, one product per line, to send to someone
- `total_value` (number): What the listed stock is worth

**Example output**

```json
{
  "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_days`, number): Only those due within this many days, 0 for today and overdue. Leave blank for all. From 0 to 365.

**Outputs**

- `batteries` (list): The batteries, soonest due first
- `count` (number): How many are listed
- `link` (text): Grocy's batteries overview
- `overdue` (number): How many are overdue
- `text` (text): The batteries as text, one per line

**Example output**

```json
{
  "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_days`, number): Only those due within this many days, 0 for today and overdue. Leave blank for all. From 0 to 365.
- Assigned to (`assigned_to`, text): Only those assigned to this person.

**Outputs**

- `chores` (list): The chores, soonest due first
- `count` (number): How many are listed
- `link` (text): Grocy's chores overview
- `overdue` (number): How many are overdue
- `text` (text): The chores as text, one per line

**Example output**

```json
{
  "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 (`words`, text): Words in the name, such as milk.

**Outputs**

- `count` (number): How many are listed
- `ready_to_cook` (number): How many have everything in stock
- `recipes` (list): The recipes, A to Z

**Example output**

```json
{
  "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 (`status`, text): Which tasks. Defaults to those not done. One of: `open` (Not done), `done`, `all`. Default: `open`.
- Due within days (`due_within_days`, number): Only those due within this many days, 0 for today and overdue. Leave blank for all. From 0 to 365.
- Category (`category`, text): Only this category.
- Assigned to (`assigned_to`, text): Only those assigned to this person.

**Outputs**

- `count` (number): How many are listed
- `link` (text): Grocy's tasks page
- `overdue` (number): How many are overdue
- `tasks` (list): The tasks, soonest due first
- `text` (text): The tasks as text, one per line

**Example output**

```json
{
  "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 (`chore`, text, required): The chore: pick one, or give its number from another Grocy step or its name.
- Done at (`done_at`, date and time): When it was done. Leave blank for now.
- Done by (`done_by`, text): Who did it. Leave blank for you.
- Skipped (`skipped`, true/false): Mark it skipped rather than done. Default: `false`.

**Outputs**

- `assigned_to` (text): Who does it next, if assigned
- `assigned_to_id` (number): Their user number (0 when no one)
- `days_until_due` (number): Days until it's due (negative when overdue), empty with no schedule
- `done_by` (text): Who did it
- `due_today` (true/false): Whether it's due today
- `execution_id` (number): This execution's number, which 'Undo chore' takes
- `id` (number): The chore's number, which other Grocy steps take
- `last_done` (text): When it was last done (YYYY-MM-DD HH:MM:SS, Grocy's time)
- `link` (text): Where the chore opens in Grocy
- `name` (text): The chore's name
- `next_due` (text): When it's next due (Grocy's time), blank with no schedule
- `next_due_date` (text): The day it's next due (YYYY-MM-DD)
- `overdue` (true/false): Whether it's overdue
- `scheduled` (true/false): Whether it has a schedule (not done only when needed)
- `skipped` (true/false): Whether it was skipped rather than done
- `tracked_time` (text): When it was marked done (Grocy's time)

**Example output**

```json
{
  "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 (`product`, text, required): The product: pick one, or give its number from another Grocy step or its name, such as Milk.
- Amount (`amount`, number, required): How much, in the product's stock unit, such as 2 for two bottles. From 0 to 1000000.

**Outputs**

- `amount` (number): How much was booked, in the product's unit
- `best_before_date` (text): The date of the stock it touched (YYYY-MM-DD)
- `link` (text): Where the product opens in Grocy
- `next_due_date` (text): The soonest date in stock now, or blank
- `price` (number): The price per unit of that stock
- `product_id` (number): The product's number
- `product_name` (text): The product's name
- `stock_amount` (number): How much is in stock now
- `stock_amount_opened` (number): How much of it is opened now
- `transaction_id` (text): The change's transaction ID, which 'Undo stock change' takes
- `unit` (text): The product's unit

**Example output**

```json
{
  "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 (`product`, text, required): The product: pick one, or give its number from another Grocy step or its name, such as Milk.
- Amount (`amount`, number, required): How much, in the product's stock unit, such as 2 for two bottles. From 0 to 1000000.
- From (`from_location`, text, required): Where it is now, such as Fridge.
- To (`to_location`, text, required): Where it goes, such as Freezer.

**Outputs**

- `amount` (number): How much was booked, in the product's unit
- `best_before_date` (text): The date of the stock it touched (YYYY-MM-DD)
- `from_location` (text): Where it was moved from
- `link` (text): Where the product opens in Grocy
- `next_due_date` (text): The soonest date in stock now, or blank
- `price` (number): The price per unit of that stock
- `product_id` (number): The product's number
- `product_name` (text): The product's name
- `stock_amount` (number): How much is in stock now
- `stock_amount_opened` (number): How much of it is opened now
- `to_location` (text): Where it was moved to
- `transaction_id` (text): The change's transaction ID, which 'Undo stock change' takes
- `unit` (text): The product's unit

**Example output**

```json
{
  "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 (`battery`, text, required): The battery: pick one, or give its number from another Grocy step or its name.
- Charged at (`charged_at`, date and time): When. Leave blank for now.

**Outputs**

- `charge_cycle_id` (number): This charge's number, which 'Undo battery charge' takes
- `charge_interval_days` (number): Days between charges (0 when not set)
- `days_until_due` (number): Days until it's due (negative when overdue), empty with no schedule
- `description` (text): Its description
- `due_today` (true/false): Whether it's due today
- `id` (number): The battery's number, which other Grocy steps take
- `last_charged` (text): When it was last charged (Grocy's time)
- `link` (text): Where the battery opens in Grocy
- `name` (text): The battery's name
- `next_charge_date` (text): The day it's next due a charge (YYYY-MM-DD)
- `next_charge_due` (text): When it's next due a charge, blank when not set
- `overdue` (true/false): Whether it's overdue
- `tracked_time` (text): When it was charged (Grocy's time)
- `used_in` (text): What it's used in

**Example output**

```json
{
  "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_list`, text, required): The shopping list: pick one, or give its number from another Grocy step or its name.
- Item (`item`, text, required): The item: its number from another Grocy step, or its product or note as the list shows it, such as Eggs.
- Amount (`amount`, number): How much to take off. Leave blank to take the whole item off. From 0 to 1000000.

**Outputs**

- `amount` (number): How much to buy
- `amount_left` (number): How much is left on the list
- `done` (true/false): Whether it's ticked off
- `id` (number): The item's number, which 'Remove item' takes
- `link` (text): Where the list opens in Grocy
- `list_id` (number): The shopping list's number
- `list_name` (text): The list's name
- `note` (text): The item's note, or the item itself when it's not a product
- `product_id` (number): The product's number (0 for a note)
- `product_name` (text): The product's name (blank for a note)
- `removed` (true/false): Whether the whole item came off (false when some is left)
- `text` (text): The item as the list shows it, such as 6 Pieces Eggs
- `unit` (text): The unit, for a product

**Example output**

```json
{
  "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 (`task`, text, required): The task: its number from another Grocy step, or its name.

**Outputs**

- `assigned_to` (text): Who it's assigned to
- `assigned_to_id` (number): Their user number (0 when no one)
- `category` (text): Its category
- `days_until_due` (number): Days until it's due (negative when overdue), empty with no schedule
- `description` (text): Its description
- `done` (true/false): Whether it's done
- `done_at` (text): When it was done (Grocy's time), or blank
- `due_date` (text): When it's due (YYYY-MM-DD), or blank
- `due_today` (true/false): Whether it's due today
- `id` (number): The task's number, which other Grocy steps take
- `link` (text): Where the task opens in Grocy
- `name` (text): What needs doing
- `overdue` (true/false): Whether it's overdue

**Example output**

```json
{
  "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_cycle`, text, required): The charge ID 'Record battery charge' returned, such as 7.

**Outputs**

- `charge_cycle_id` (number): The charge undone
- `charge_interval_days` (number): Days between charges (0 when not set)
- `days_until_due` (number): Days until it's due (negative when overdue), empty with no schedule
- `description` (text): Its description
- `due_today` (true/false): Whether it's due today
- `id` (number): The battery's number, which other Grocy steps take
- `last_charged` (text): When it was last charged (Grocy's time)
- `link` (text): Where the battery opens in Grocy
- `name` (text): The battery's name
- `next_charge_date` (text): The day it's next due a charge (YYYY-MM-DD)
- `next_charge_due` (text): When it's next due a charge, blank when not set
- `overdue` (true/false): Whether it's overdue
- `undone` (true/false): Always true
- `used_in` (text): What it's used in

**Example output**

```json
{
  "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 (`execution`, text, required): The execution ID 'Mark chore done' returned, such as 42.

**Outputs**

- `assigned_to` (text): Who does it next, if assigned
- `assigned_to_id` (number): Their user number (0 when no one)
- `days_until_due` (number): Days until it's due (negative when overdue), empty with no schedule
- `due_today` (true/false): Whether it's due today
- `execution_id` (number): The execution undone
- `id` (number): The chore's number, which other Grocy steps take
- `last_done` (text): When it was last done (YYYY-MM-DD HH:MM:SS, Grocy's time)
- `link` (text): Where the chore opens in Grocy
- `name` (text): The chore's name
- `next_due` (text): When it's next due (Grocy's time), blank with no schedule
- `next_due_date` (text): The day it's next due (YYYY-MM-DD)
- `overdue` (true/false): Whether it's overdue
- `scheduled` (true/false): Whether it has a schedule (not done only when needed)
- `undone` (true/false): Always true

**Example output**

```json
{
  "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 (`transaction`, text, required): The transaction ID from 'Add purchase', 'Use product', 'Mark product opened' or 'Move product'.

**Outputs**

- `change` (text): What it was: purchase, consume, product-opened, transfer_from
- `link` (text): Where the product opens in Grocy
- `product_id` (number): The product's number
- `product_name` (text): The product's name
- `stock_amount` (number): How much is in stock now
- `transaction_id` (text): The transaction undone
- `undone` (true/false): Always true

**Example output**

```json
{
  "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 (`product`, text, required): The product: pick one, or give its number from another Grocy step or its name, such as Milk.
- Name (`name`, text): What the product is called, such as Oat milk.
- Location (`location`, text): Where it's kept by default, such as Fridge.
- Unit (`quantity_unit`, text): What it's counted and bought in, such as Bottle or Piece.
- Minimum stock (`min_stock_amount`, number): The least you want at home. Below it, the product shows as running low. From 0 to 1000000.
- Default due days (`default_best_before_days`, number): How many days a purchase keeps, such as 7; -1 for never goes off. From -1 to 36500.
- Date type (`date_type`, text): 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_group`, text): Its product group, such as Dairy.
- Description (`description`, text): A note about the product.
- Barcode (`barcode`, text): A barcode to add to it, such as 4006381333931.

**Outputs**

- `active` (true/false): Whether the product is in use (not turned off)
- `amount_text` (text): The amount in stock with its unit, such as 2 Bottles
- `average_price` (number): The average price per unit of what's in stock
- `barcodes` (list): Its barcodes
- `below_min_stock` (true/false): Whether there's less than the minimum in stock
- `date_type` (text): best_before or expires: what its dates mean
- `default_best_before_days` (number): Days a purchase keeps by default (-1 for never goes off)
- `description` (text): Its description
- `id` (number): The product's number, which other Grocy steps take
- `last_price` (number): The price per unit paid last time
- `last_purchased` (text): When it was last bought (YYYY-MM-DD)
- `last_used` (text): When it was last used (YYYY-MM-DD)
- `link` (text): Where it opens in Grocy
- `location` (text): Where it's kept by default, such as Fridge
- `location_id` (number): That location's number
- `min_stock_amount` (number): The least the household wants in stock
- `name` (text): The product's name
- `next_due_date` (text): The soonest date in stock (YYYY-MM-DD), or blank
- `product_group_id` (number): Its product group's number (0 when none)
- `purchase_unit` (text): The unit it's bought in
- `stock_amount` (number): How much is in stock
- `stock_amount_opened` (number): How much of it is opened
- `stock_value` (number): What the stock is worth
- `unit` (text): The unit stock is counted in, such as Bottle

**Example output**

```json
{
  "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 (`product`, text, required): The product: pick one, or give its number from another Grocy step or its name, such as Milk.
- Amount (`amount`, number, required): How much, in the product's stock unit, such as 2 for two bottles. From 0 to 1000000.
- Spoiled (`spoiled`, true/false): Book it as thrown away rather than used. Default: `false`.
- Location (`location`, text): Take it from this location. Leave blank for anywhere.

**Outputs**

- `amount` (number): How much was booked, in the product's unit
- `best_before_date` (text): The date of the stock it touched (YYYY-MM-DD)
- `link` (text): Where the product opens in Grocy
- `next_due_date` (text): The soonest date in stock now, or blank
- `price` (number): The price per unit of that stock
- `product_id` (number): The product's number
- `product_name` (text): The product's name
- `spoiled` (true/false): Whether it was thrown away as spoiled
- `stock_amount` (number): How much is in stock now
- `stock_amount_opened` (number): How much of it is opened now
- `transaction_id` (text): The change's transaction ID, which 'Undo stock change' takes
- `unit` (text): The product's unit

**Example output**

```json
{
  "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"
}
```
