This project provides a reliable and lightweight synchronization between the default Alexa shopping list (the same list used natively on an Echo Show 15 widget) and Home Assistant.
Before building this integration, two popular alternatives were evaluated. They were not adopted for the reasons explained below.
Repository: https://github.com/mmstano/ha-echo-command-center
This project relies on custom Alexa skills. However, custom skills cannot access Alexa's default built-in shopping list. Because of this limitation, the list displayed in the native Echo Show 15 shopping widget cannot be used.
Since the goal of this project was to keep using Alexa's default list — ensuring full compatibility with the Echo Show interface — this approach was not viable.
Repository: https://github.com/madmachinations/home-assistant-alexa-shopping-list
Previous versions of this project used:
- Browser-based authentication with cookies
- Interaction with Amazon's list interface through Selenium
- A multi-container architecture (one server container + one client container)
Although functional at first, this approach proved unreliable in long-term use:
- ❌ Cookies frequently expired or became invalid
- ❌ After some time, synchronization silently stopped
- ❌ Selenium interactions were heavy and resource-intensive
- ❌ The two-container setup added unnecessary complexity to the system
For these reasons, it was not suitable for a stable, always-on home automation environment.
This integration was created to provide a simpler, stable, and lightweight solution that:
✅ Works directly with the default Alexa shopping list ✅ Maintains compatibility with the Echo Show 15 native widget ✅ Requires minimal dependencies ✅ Ensures long-term reliability without Selenium or fragile cookies
This integration uses the Chrome DevTools Protocol (CDP) to interact directly with Amazon's web interface:
┌─────────────┐ ┌──────────────┐ ┌──────────────┐
│ Alexa │ ◄─────► │ Amazon │ ◄─────► │ Chromium │
│ (Voice) │ │ (Cloud) │ │ (Browser) │
└─────────────┘ └──────────────┘ └──────┬───────┘
│ CDP
│ (WebSocket)
┌──────▼───────┐
│ Home │
│ Assistant │
└──────────────┘
- Chromium Browser: Runs with remote debugging mode and your Amazon session logged in
- CDP Connection: Home Assistant connects via WebSocket to control the browser
- JavaScript Execution: Reads and manipulates the shopping list directly on the page
- Bidirectional Sync: Keeps Home Assistant and Alexa lists synchronized
Key Advantages:
- 🔒 Secure: Uses your existing Amazon session (manual login, no stored credentials)
- 🚀 Lightweight: No Selenium, no cookies management, no complex architecture (~1MB vs ~100MB)
- 🔄 Reliable: Direct DOM manipulation via CDP - if the page loads, it works
- 🎯 Simple: One integration, one browser, one connection
- ⚡ Fast: WebSocket communication with minimal overhead
- Home Assistant 2021.3.0 or newer
- Chromium/Chrome browser running with remote debugging enabled
- Amazon account with access to Alexa shopping lists
- Network access between Home Assistant and Chromium (localhost if on same machine)
- ✅ Raspberry Pi 4/5 (ARM64)
- ✅ Linux (x86_64, ARM64)
- ✅ Windows (with Chrome/Chromium)
- ✅ macOS
- ✅ Home Assistant Container (host network mode)
- ✅ Home Assistant Core
- ✅ Home Assistant OS (with separate Chromium instance)
- Open HACS in Home Assistant
- Go to Integrations
- Click the ⋮ menu → Custom repositories
- Add this repository URL:
https://github.com/thiagobucca/ha-alexa-shopping-list-sync - Category: Integration
- Click Download
- Restart Home Assistant
- Download or clone this repository
- Copy the
custom_components/alexa_shopping_listfolder to your Home Assistantcustom_componentsdirectory - Restart Home Assistant
sudo apt-get update
sudo apt-get install chromium-browsersudo pacman -S chromiumbrew install --cask chromiumDownload Chromium from: https://www.chromium.org/getting-involved/download-chromium
Run Chromium with the --remote-debugging-port flag:
chromium-browser \
--remote-debugging-port=9222 \
--user-data-dir=$HOME/.config/chromium-ha \
--no-first-run \
--no-default-browser-check \
"https://www.amazon.com/alexaquantum/sp/alexaShoppingList"Adjust the Amazon domain for your region:
- 🇺🇸 US:
amazon.com - 🇬🇧 UK:
amazon.co.uk - 🇧🇷 Brazil:
amazon.com.br - 🇩🇪 Germany:
amazon.de - 🇫🇷 France:
amazon.fr - 🇮🇹 Italy:
amazon.it - 🇪🇸 Spain:
amazon.es - 🇨🇦 Canada:
amazon.ca - 🇯🇵 Japan:
amazon.co.jp
💡 Important: The
--user-data-dirflag creates a separate Chrome profile, keeping your session isolated and persistent.
When Chromium opens:
- Manually log in to your Amazon account
- Complete two-factor authentication if prompted
- Solve any CAPTCHAs if requested
- ✅ Keep this browser window open and logged in
💡 Tip: On headless systems (like Raspberry Pi), use VNC or X11 forwarding to access the desktop and log in via the browser.
Test if the CDP endpoint is accessible:
curl http://localhost:9222/jsonYou should see JSON output with page information including "title": "Alexa Shopping List".
If Home Assistant is in Docker (host network mode):
docker exec -it homeassistant curl http://localhost:9222/jsonAdd to your configuration.yaml:
shopping_list:Save and restart Home Assistant (or reload configuration).
- Go to Settings → Devices & Services
- Click + Add Integration
- Search for "Alexa Shopping List"
- Configure the integration:
| Parameter | Description | Default | Example |
|---|---|---|---|
| CDP Endpoint | Chromium remote debugging URL | http://localhost:9222 |
http://192.168.1.100:9222 |
| Sync Interval | Minutes between automatic syncs | 60 |
30, 120 |
- Click Submit
The integration will:
- ✅ Connect to Chromium via CDP
- ✅ Navigate to your Alexa shopping list (if not already there)
- ✅ Perform the first synchronization
- ✅ Create a sensor:
sensor.alexa_shopping_list
The integration automatically syncs every X minutes (configured during setup).
What happens during auto sync:
- 📥 Items added via Alexa → appear in Home Assistant
- 📤 Items marked as complete in HA → removed from Alexa
- 🔄 Lists stay synchronized bidirectionally
Force an immediate sync:
service: alexa_shopping_list.sync_alexa_shopping_listAutomation example:
script:
sync_alexa_list:
alias: "Sync Alexa Shopping List"
sequence:
- service: alexa_shopping_list.sync_alexa_shopping_list"Alexa, add milk to my shopping list"
"Alexa, add bread and eggs to my list"
→ Next sync (auto or manual) → Items appear in Home Assistant
- Open the Shopping List panel in Home Assistant
- Add an item (e.g., "coffee")
- Call manual sync service (force sync)
- Item appears in Alexa
| Method | Behavior |
|---|---|
| Mark as complete in HA | ✅ Removed from Alexa + HA |
| Voice command via Alexa | ✅ Removed from Alexa + HA |
| Delete in HA |
💡 Best Practice: Always mark items as complete instead of deleting them in HA.
Why? Deleting an item in HA doesn't communicate the intent to remove it from Alexa. Marking as complete signals "I bought this item" and removes it from both lists.
- Go to Settings → Devices & Services
- Find Alexa Shopping List
- Click Configure
- Adjust Sync Interval (minutes)
Recommended values:
- 60 minutes: Normal use (default)
- 30 minutes: Frequent updates
- 120 minutes: Low traffic / battery saving
- 5-10 minutes: Testing only (not recommended for production)
⚠️ Warning: Very short intervals (< 5 minutes) may trigger rate limiting or cause excessive browser activity.
The integration fires events you can use in automations:
Fired when the shopping list changes during sync.
Event Data:
event_type: alexa_shopping_list_changed
data:
success: true
changed: true
added: ["milk", "eggs"]
removed: ["bread"]
alexa_count: 5
ha_count: 5Example Automation:
automation:
- alias: "Notify when items added to shopping list"
trigger:
- platform: event
event_type: alexa_shopping_list_changed
condition:
- "{{ trigger.event.data.added | length > 0 }}"
action:
- service: notify.mobile_app
data:
title: "Shopping List Updated"
message: "Added: {{ trigger.event.data.added | join(', ') }}"The integration creates a sensor: sensor.alexa_shopping_list
State: Number of items in Alexa list
Attributes:
last_sync: Timestamp of last successful syncconnected: CDP connection status (true/false)alexa_count: Number of items in Alexa listha_count: Number of items in HA list
Example Lovelace Card:
type: entities
title: Alexa Shopping List
entities:
- entity: sensor.alexa_shopping_list
name: Total Items
- type: attribute
entity: sensor.alexa_shopping_list
attribute: alexa_count
name: Items in Alexa
- type: attribute
entity: sensor.alexa_shopping_list
attribute: ha_count
name: Items in Home Assistant
- type: attribute
entity: sensor.alexa_shopping_list
attribute: last_sync
name: Last SyncError: CDP connection failed
Solutions:
- Verify Chromium is running:
ps aux | grep chromium - Test CDP endpoint:
curl http://localhost:9222/json - Check the port is correct (default: 9222)
- Ensure firewall allows connections to port 9222
- Try restarting Chromium with the correct flags
Symptoms: Items added via Alexa don't appear in HA (or vice versa)
Solutions:
- Check the browser is on the shopping list page
- Verify you're still logged in to Amazon
- Force a manual sync:
alexa_shopping_list.sync_alexa_shopping_list - Check Home Assistant logs: Settings → System → Logs (filter:
alexa_shopping_list) - Reload the integration
Symptoms: Sync stops working after days/weeks
Solutions:
- Access Chromium via VNC or direct display
- Check if Amazon is asking you to log in again
- Re-authenticate if needed
- Reload the integration in Home Assistant
Cause: Amazon changed their page structure for your region
Solutions:
- Open a GitHub issue with:
- Your Amazon domain (e.g.,
amazon.com) - Browser console errors (F12 → Console)
- Screenshot of the shopping list page
- Your Amazon domain (e.g.,
- The selectors may need updating for your specific Amazon region
Cause: Sync interval is too short
Solutions:
- Check your configured sync interval
- Increase to at least 30-60 minutes
- The Tab/refresh behavior should only occur during item addition, not constantly
Create /etc/systemd/system/chromium-alexa.service:
[Unit]
Description=Chromium for Alexa Shopping List Integration
After=network.target graphical.target
[Service]
Type=simple
User=homeassistant
Environment="DISPLAY=:0"
Environment="XAUTHORITY=/home/homeassistant/.Xauthority"
ExecStart=/usr/bin/chromium-browser \
--remote-debugging-port=9222 \
--user-data-dir=/home/homeassistant/.config/chromium-ha \
--no-first-run \
--no-default-browser-check \
"https://www.amazon.com/alexaquantum/sp/alexaShoppingList"
Restart=always
RestartSec=10
[Install]
WantedBy=graphical.targetEnable and start:
sudo systemctl daemon-reload
sudo systemctl enable chromium-alexa
sudo systemctl start chromium-alexa
sudo systemctl status chromium-alexaversion: '3.8'
services:
homeassistant:
image: homeassistant/home-assistant:stable
volumes:
- ./config:/config
network_mode: host
restart: unless-stopped
chromium:
image: browserless/chrome:latest
ports:
- "9222:3000"
environment:
- CONNECTION_TIMEOUT=600000
- MAX_CONCURRENT_SESSIONS=1
- KEEP_ALIVE=true
restart: unless-stoppedNote: With browserless/chrome, you'll need to handle authentication differently. Manual login may not persist across container restarts.
A: Yes! It supports all Amazon domains worldwide.
A: It's safe. You log in normally via the browser. Home Assistant uses the official Chrome DevTools Protocol (same as Chrome Developer Tools). However, use reasonable sync intervals (≥60 minutes) to avoid rate limiting.
A: Much less than Selenium! The browser is already open; Home Assistant only connects via WebSocket when syncing. CPU usage is minimal.
A: Yes! The browser must stay open and logged in. Configure auto-start on boot (see systemd service example above).
A: Not currently. One Amazon account per Home Assistant instance.
A: No, only shopping lists are supported at this time.
A: The integration will show as disconnected. Once internet returns, it will reconnect automatically on the next sync.
Contributions are welcome! Here's how you can help:
- 🐛 Report Bugs: Open an issue with detailed information
- 💡 Suggest Features: Describe your use case and proposed solution
- 🔧 Submit Pull Requests: Fork, code, test, and submit
- 📖 Improve Documentation: Fix typos, add examples, or translate
# Clone the repository
git clone https://github.com/thiagobucca/ha-alexa-shopping-list-sync
cd ha-alexa-shopping-list-sync
# Install in development mode (symlink)
ln -s $(pwd)/custom_components/alexa_shopping_list \
/path/to/homeassistant/config/custom_components/alexa_shopping_list
# Restart Home Assistant to load changescustom_components/alexa_shopping_list/
├── __init__.py # Integration entry point
├── config_flow.py # Configuration UI flow
├── coordinator.py # Data update coordinator
├── cdp_manager.py # Chrome DevTools Protocol manager
├── shopping_list_sync.py # Synchronization logic
├── sensor.py # Home Assistant sensor platform
├── manifest.json # Integration metadata
├── strings.json # UI strings
└── translations/
└── en.json # English translations
- ✨ Built with Chrome DevTools Protocol (CDP)
- ✅ Direct WebSocket communication with Chromium
- ✅ Lightweight architecture (~1MB dependencies)
- ✅ Long-term reliability without Selenium or cookies
- ✅ Simple 3-step configuration
- ✅ Bidirectional synchronization
- ✅ Works with default Alexa shopping list
- ✅ Compatible with Echo Show 15 widget
This project is licensed under the MIT License - see the LICENSE file for details.
This project is not affiliated with Amazon, Alexa, or any of their subsidiaries.
"Amazon" and "Alexa" are registered trademarks of Amazon.com, Inc.
Use at your own risk. The author is not responsible for any issues arising from the use of this integration.
Made with ❤️ for the Home Assistant community
⭐ If this project helped you, please give it a star!
