Grocy Custom Component for Home Assistant

A Home Assistant custom integration for Grocy - the self-hosted groceries & household management solution.

---

IMPORTANT INFORMATION

The integration supports Grocy version 3.2 and above.

At least Home Assistant version 2021.12 is required for the integration from v4.3.3 and above.

You must have Grocy software already installed and running. This integration only communicates with an existing installation of Grocy. You can install Grocy using the Grocy add-on or another installation method found at the Grocy website.

---

Installation

HACS (Recommended)

The easiest way to install this integration is with HACS.

1. Install HACS if you don't have it yet
2. In Home Assistant, go to HACS → 3 dot menu → "Custom repositories"
3. Add this repository URL: https://github.com/iamkarlson/grocy
4. Select "Integration" as the type
5. Find "Grocy custom component" in the list and click on it
6. Click "Download" → "Download" → Restart Home Assistant
7. Install the Grocy integration

Future integration updates will appear automatically within Home Assistant via HACS.

Manual Installation

1. Update Home Assistant to version 2025.02 or newer
2. Download this repository
3. Copy the custom_components/grocy folder into your Home Assistant's custom_components folder
4. Restart Home Assistant

Configuration

Adding the Integration

1. Go to Settings → Devices & Services → Add Integration
2. Search for "Grocy" and select it
3. Configure according to your setup:

For Grocy Add-on Users

If you use the official Grocy add-on:

1. Install Grocy from the add-on store if you haven't already
2. In the add-on 'Configuration', set the Network port to 9192 (see screenshot)
3. Save changes and restart the add-on
4. Use port 9192 when configuring the integration

Configuration Parameters

• URL: Your Grocy instance URL (e.g., http://192.168.1.100 or https://grocy.example.com)
  • Start with http:// or https://
  • Do not include the port in the URL field
  • Subdomains are supported
• API Key: Generate in Grocy via the wrench icon → "Manage API keys"
• Port:
  • 9192 for Grocy add-on (without https)
  • 80 for http or 443 for https (or your custom port)
• Verify SSL: Check if using HTTPS with valid certificate

All entities are disabled by default. Enable the entities you want to use in Home Assistant.

Entities

All entities are disabled from the start. You have to manually enable the entities you want to use in Home Assistant. You get a sensor each for chores, meal plan, shopping list, stock, tasks and batteries. You get a binary sensor each for overdue, expired, expiring and missing products and for overdue tasks, overdue chores and overdue batteries.

If you enable a certain entity (like todo), you should also enable a sensor. Otherwise, you may have errors in Home Assistant stating that the "entity is unknown".

Services

The following services come with the integration. For all available options check the Developer Tools: Services within Home Assistant.

• Grocy: Add Generic (grocy.add_generic)

Adds a single object of the given entity type.

• Grocy: Add Product To Stock (grocy.add_product_to_stock)

Adds a given amount of a product to the stock.

• Grocy: Open Product (grocy.open_product)

Opens a given amount of a product in stock.

• Grocy: Track Battery (grocy.track_battery)

Tracks the given battery.

• Grocy: Complete Task (grocy.complete_task)

Completes the given task.

• Grocy: Consume Product From Stock (grocy.consume_product_from_stock)

Consumes a given amount of a product from the stock.

• Grocy: Execute Chore (grocy.execute_chore)

Executes the given chore with an optional timestamp and executor.

• Grocy: Consume Recipe (grocy.consume_recipe)

Consumes the given recipe.

• Grocy: Add Missing Products to Shopping List (grocy.add_missing_products_to_shopping_list)

Adds currently missing products to a given shopping list.

• Grocy: Remove Product in Shopping List (grocy.remove_product_in_shopping_list)

Removes a product in the given shopping list.

Translations

Before this was forked, translation was done using paid service lokalise.com. However, it's now just bunch of json files in custom_components/grocy/translations/ directory. Feel free to open a PR if there's an error in translation.

Troubleshooting

If you experience issues with the integration:

1. Enable debug logging by adding this to your configuration.yaml:

   logger:
     default: info
     logs:
       pygrocy.grocy_api_client: debug
       custom_components.grocy: debug

2. Ensure compatibility: Use the latest version of the integration, Grocy, and Home Assistant

3. Check your setup: Verify your Grocy URL, API key, and port configuration

4. Get help:

   • Community Forum Discussion
   • Report Issues on GitHub

Contributing

Want to contribute to this project? Check out our CONTRIBUTING.md guide for:

• Setting up the development environment
• Debugging with VSCode
• Running development tasks
• Code structure overview
• Testing procedures
• Submission guidelines

We welcome contributions of all kinds! 🎉

Screenshots

Add-on Port Configuration

Integration configuration

URL

The Grocy url should be in the form below (start with http:// or https://) and point to your Grocy instance. If you use a SSL certificate you should have https and also check the "Verify SSL Certificate" box. Do not enter a port in the url field. Subdomains are also supported, fill out the full url in the field.

API key

Go to your Grocy instance. Navigate via the wrench icon in the top right corner to "Manage API keys" and add a new API key. Copy and paste the generated key.

Port

It should work with for example a Duck DNS address as well, but you still have to access it via a port, and the above instructions for the url still apply.

• If you have configured the Grocy add-on as described, use port 9192 (without https). Either be sure the port is open in your router or use your internal Home Assistant address.
• If you have configured an external Grocy instance and not sure, use port 80 for http or port 443 for https. Unless you have set a custom port for Grocy.

Add-on port configuration