Stock Manager

Manage product stock — query, add, consume, open, transfer, and inventory products.

Access via grocy.stock.

# Get all products currently in stock
for product in grocy.stock.current():
    print(f"{product.name}: {product.available_amount}")

# Add, consume, open
grocy.stock.add(product_id=1, amount=5, price=2.99)
grocy.stock.consume(product_id=1, amount=1)
grocy.stock.open(product_id=1)

Class Reference

StockManager(api_client)

Manage product stock levels, entries, and transactions.

Access via grocy.stock.

current()

Get all products currently in stock.

due_products(get_details=False)

Get products that are due soon.

Parameters:

Name	Type	Description	Default
get_details	bool	Fetch full product details for each item.	False

overdue_products(get_details=False)

Get products that are past their best-before date.

Parameters:

Name	Type	Description	Default
get_details	bool	Fetch full product details for each item.	False

expired_products(get_details=False)

Get products that have expired.

Parameters:

Name	Type	Description	Default
get_details	bool	Fetch full product details for each item.	False

missing_products(get_details=False)

Get products that are below their minimum stock amount.

Parameters:

Name	Type	Description	Default
get_details	bool	Fetch full product details for each item.	False

product(product_id)

Get a single product by ID.

Parameters:

Name	Type	Description	Default
product_id	int	The Grocy product ID.	required

product_by_barcode(barcode)

Get a single product by barcode.

Parameters:

Name	Type	Description	Default
barcode	str	The product barcode.	required

all_products()

Get all products regardless of stock status.

add(product_id, amount, price, best_before_date=None, transaction_type=TransactionType.PURCHASE)

Add stock for a product.

Parameters:

Name	Type	Description	Default
product_id	int	The Grocy product ID.	required
amount	float	Quantity to add.	required
price	float	Unit price.	required
best_before_date	datetime | None	Expiry date. Defaults to the product's configured default.	None
transaction_type	TransactionType	Type of stock transaction.	PURCHASE

consume(product_id, amount=1, spoiled=False, transaction_type=TransactionType.CONSUME, allow_subproduct_substitution=False)

Consume stock for a product.

Parameters:

Name	Type	Description	Default
product_id	int	The Grocy product ID.	required
amount	float	Quantity to consume.	1
spoiled	bool	Whether the consumed amount was spoiled.	False
transaction_type	TransactionType	Type of stock transaction.	CONSUME
allow_subproduct_substitution	bool	Allow consuming from sub-products.	False

open(product_id, amount=1, allow_subproduct_substitution=False)

Mark stock of a product as opened.

Parameters:

Name	Type	Description	Default
product_id	int	The Grocy product ID.	required
amount	float	Quantity to mark as opened.	1
allow_subproduct_substitution	bool	Allow opening from sub-products.	False

transfer(product_id, amount, location_from, location_to)

Transfer stock of a product between locations.

Parameters:

Name	Type	Description	Default
product_id	int	The Grocy product ID.	required
amount	float	Quantity to transfer.	required
location_from	int	Source location ID.	required
location_to	int	Destination location ID.	required

inventory(product_id, new_amount, best_before_date=None, shopping_location_id=None, location_id=None, price=None, get_details=True)

Perform a stock inventory correction for a product.

Parameters:

Name	Type	Description	Default
product_id	int	The Grocy product ID.	required
new_amount	float	The corrected total amount.	required
best_before_date	datetime | None	Expiry date for the corrected stock.	None
shopping_location_id	int | None	Where the product was purchased.	None
location_id	int | None	Storage location ID.	None
price	float | None	Unit price.	None
get_details	bool	Fetch full product details after correction.	True

add_by_barcode(barcode, amount, price, best_before_date=None, get_details=True)

Add stock for a product identified by barcode.

Parameters:

Name	Type	Description	Default
barcode	str	Product barcode.	required
amount	float	Quantity to add.	required
price	float	Unit price.	required
best_before_date	datetime | None	Expiry date.	None
get_details	bool	Fetch full product details after adding.	True

consume_by_barcode(barcode, amount=1, spoiled=False, get_details=True)

Consume stock for a product identified by barcode.

Parameters:

Name	Type	Description	Default
barcode	str	Product barcode.	required
amount	float	Quantity to consume.	1
spoiled	bool	Whether the consumed amount was spoiled.	False
get_details	bool	Fetch full product details after consuming.	True

transfer_by_barcode(barcode, amount, location_from, location_to)

Transfer stock of a product identified by barcode.

Parameters:

Name	Type	Description	Default
barcode	str	Product barcode.	required
amount	float	Quantity to transfer.	required
location_from	int	Source location ID.	required
location_to	int	Destination location ID.	required

open_by_barcode(barcode, amount=1)

Mark stock of a product identified by barcode as opened.

Parameters:

Name	Type	Description	Default
barcode	str	Product barcode.	required
amount	float	Quantity to mark as opened.	1

inventory_by_barcode(barcode, new_amount, best_before_date=None, location_id=None, price=None, get_details=True)

Perform a stock inventory correction by barcode.

Parameters:

Name	Type	Description	Default
barcode	str	Product barcode.	required
new_amount	float	The corrected total amount.	required
best_before_date	datetime | None	Expiry date for the corrected stock.	None
location_id	int | None	Storage location ID.	None
price	float | None	Unit price.	None
get_details	bool	Fetch full product details after correction.	True

merge(product_id_keep, product_id_remove)

Merge two products, keeping one and removing the other.

Parameters:

Name	Type	Description	Default
product_id_keep	int	ID of the product to keep.	required
product_id_remove	int	ID of the product to remove.	required

entry(entry_id)

Get a single stock entry by ID.

Parameters:

Name	Type	Description	Default
entry_id	int	The stock entry ID.	required

edit_entry(entry_id, data)

Edit a stock entry.

Parameters:

Name	Type	Description	Default
entry_id	int	The stock entry ID.	required
data	dict	Fields to update.	required

product_entries(product_id)

Get all stock entries for a product.

Parameters:

Name	Type	Description	Default
product_id	int	The Grocy product ID.	required

product_locations(product_id)

Get stock locations for a product.

Parameters:

Name	Type	Description	Default
product_id	int	The Grocy product ID.	required

product_price_history(product_id)

Get price history for a product.

Parameters:

Name	Type	Description	Default
product_id	int	The Grocy product ID.	required

entries_by_location(location_id)

Get all stock entries at a given location.

Parameters:

Name	Type	Description	Default
location_id	int	The location ID.	required

booking(booking_id)

Get a stock booking by ID.

Parameters:

Name	Type	Description	Default
booking_id	int	The stock booking ID.	required

undo_booking(booking_id)

Undo a stock booking.

Parameters:

Name	Type	Description	Default
booking_id	int	The stock booking ID.	required

transaction(transaction_id)

Get all log entries for a stock transaction.

Parameters:

Name	Type	Description	Default
transaction_id	str	The transaction ID.	required

undo_transaction(transaction_id)

Undo a stock transaction.

Parameters:

Name	Type	Description	Default
transaction_id	str	The transaction ID.	required

barcode_lookup(barcode)

Look up a barcode using the external barcode lookup service.

Parameters:

Name	Type	Description	Default
barcode	str	The barcode to look up.	required

product_groups(query_filters=None)

Get all product groups.

Parameters:

Name	Type	Description	Default
query_filters	list[str] | None	Optional Grocy API query filters.	None

upload_product_picture(product_id, pic_path)

Upload a picture for a product.

Parameters:

Name	Type	Description	Default
product_id	int	The Grocy product ID.	required
pic_path	str	Local filesystem path to the image file.	required