Shopping List Manager

Manage shopping list items — view, add/remove products, and bulk operations.

Access via grocy.shopping_list.

items = grocy.shopping_list.items(get_details=True)
for item in items:
    print(f"{item.product.name}: {item.amount}")

grocy.shopping_list.add_product(product_id=1, amount=3)
grocy.shopping_list.add_missing_products()

Class Reference

ShoppingListManager(api_client)

Manage shopping lists and their items.

Access via grocy.shopping_list.

items(get_details=False, query_filters=None)

Get all items on the shopping list.

Parameters:

Name	Type	Description	Default
get_details	bool	Fetch full product details for each item.	False
query_filters	list[str] | None	Optional Grocy API query filters.	None

add_product(product_id, shopping_list_id=None, amount=None, quantity_unit_id=None)

Add a product to a shopping list.

Parameters:

Name	Type	Description	Default
product_id	int	The Grocy product ID.	required
shopping_list_id	int | None	Target shopping list. Defaults to the first list.	None
amount	float | None	Quantity to add.	None
quantity_unit_id	int | None	Override the default quantity unit.	None

remove_product(product_id, shopping_list_id=1, amount=1)

Remove a product from a shopping list.

Parameters:

Name	Type	Description	Default
product_id	int	The Grocy product ID.	required
shopping_list_id	int	Target shopping list.	1
amount	float	Quantity to remove.	1

mark_item_done(shopping_list_item_id, done=True)

Mark a shopping list item as done or not done.

Parameters:

Name	Type	Description	Default
shopping_list_item_id	int	The shopping list item ID.	required
done	bool	Whether to mark as done (True) or not done (False).	True

clear(shopping_list_id=1)

Remove all items from a shopping list.

Parameters:

Name	Type	Description	Default
shopping_list_id	int	The shopping list ID.	1

add_missing_products(shopping_list_id=1)

Add all missing products to the shopping list.

Parameters:

Name	Type	Description	Default
shopping_list_id	int	The shopping list ID.	1

add_overdue_products(shopping_list_id=1)

Add all overdue products to the shopping list.

Parameters:

Name	Type	Description	Default
shopping_list_id	int	The shopping list ID.	1

add_expired_products(shopping_list_id=1)

Add all expired products to the shopping list.

Parameters:

Name	Type	Description	Default
shopping_list_id	int	The shopping list ID.	1