Blackcap can merge supported household/external shopping sources into the shopping workflow and can hand off lists through configured Shop With providers. The browser bridge supports explicitly configured browser-open actions without pretending to provide an API integration where none exists.

External items retain provider/source identity and are merged without collapsing unrelated entries. Connections and provider availability are organization-scoped.

Household and external lists

Blackcap has a built-in Household List for persistent, non-recipe shopping needs such as milk, paper towels, dish soap, snacks, or other items added by voice assistant. The Household List is organization-scoped and is separate from normal event-based shopping lists created from recipes, meal plans, or one-off shopping sessions.

The first External Shopping List implementation is a local desktop Chrome extension bridge for:

Google Keep, commonly used by Google Home shopping-list voice capture
Amazon/Alexa, using the Alexa Shopping List web page
Custom URL, for future or local experiments against another shopping-list page

This is not an official Google/Amazon OAuth API integration. The bridge uses the user's already signed-in Chrome browser session and does not store Google, Amazon, or custom-provider passwords.

Household List behavior

The Household List is created automatically per organization when the feature is enabled.

It is different from a normal Blackcap shopping list:

it is persistent and ongoing;
it cannot be completed, archived, deleted, or made the active event list;
it can be edited from Shopping Lists;
unchecked, non-ignored items can be included with normal Shop a List and Shop With sessions;
checked provider-backed items can be pushed back to the external provider from an attended desktop Chrome flow.

Organization configuration

Open Configuration → Organization → Household List to manage organization-scoped behavior.

Settings:

Enable Household List: controls whether the built-in Household List appears and can be included with other lists. Default: enabled.
External Sync Freshness: controls when Blackcap suggests syncing External Shopping Lists before desktop shopping. Default: 30 minutes.
Default Include Household List for Admin Shop a List: controls whether Admin Shop a List includes Household List items by default. Default: yes.
Default Include Household List for Mobile Shop a List: controls whether Mobile Shop a List includes Household List items by default. Default: yes.

Freshness behavior:

Always ask: Admin desktop flows treat every shopping session as sync-recommended. Mobile shows a yellow informational freshness pill because mobile cannot run the provider bridge.
Minutes-based values: Admin desktop flows recommend sync when any enabled external connection is older than the configured window, has never synced, or has a failed sync. Admin and Mobile show a green/yellow synced-ago pill when Household List inclusion is available.
Never: Blackcap does not prompt for pre-shopping provider sync, but manual sync remains available from the Household List editor.

The synced-ago pill is informational. It does not block shopping, and it does not prevent Household List items from being included when the checkbox is selected.

External Shopping List connections

Open Connections and create an External Shopping List organization connection.

Each connection stores:

provider type;
provider display name;
selected list name;
selected list URL;
enabled/disabled state;
last sync metadata and errors;
favicon/source badge metadata when available.

Provider pages are opened by the Chrome extension in popup-sized windows. The connection page includes a known-limitation warning because provider sync and provider check-off require the desktop Chrome extension and a signed-in browser session. Mobile can shop with the last-synced Household List snapshot but cannot sync provider pages or check off provider items.

Google Keep setup

Google Home shopping-list voice capture often lands in a Google Keep list note.

In Blackcap, open Connections.
Add an External Shopping List connection.
Choose Google Keep.
Press Open to launch Keep in a popup-sized window.
Select the Keep list note that should back the household shopping list.
Close the Keep window to return to Blackcap. The extension tries to capture the selected list URL, including the #LIST/... fragment.
If automatic capture misses the URL, press Use Selected URL or paste the Keep list URL manually.
Save the connection.

Typical Keep list URLs look like:

https://keep.google.com/u/0/#LIST/<list-id>

Amazon/Alexa setup

Amazon/Alexa uses the Alexa Shopping List web page.

In Blackcap, open Connections.
Add an External Shopping List connection.
Choose Amazon/Alexa.
Blackcap prepopulates the standard Alexa Shopping List URL:
```
https://www.amazon.com/gp/alexa-shopping-list?
```
Press Open to confirm Chrome is signed into the desired Amazon account.
Save the connection.

Amazon extraction is intentionally scoped to the Alexa Shopping List application area and rejects cart/header/flyout text such as prices or checkout content.

Custom setup

Choose Custom to connect another shopping-list page by URL. Blackcap validates that the URL is a normal http(s) page and attempts to cache the site's favicon for the connection row and imported item source badge. Custom providers use generic DOM extraction until a provider-specific extractor is added.

Syncing external lists into Blackcap

Manual sync is available from the Household List editor. Pre-shopping sync is suggested from Admin desktop shopping flows when Household List items are included and the sync freshness setting says one or more enabled connections may be stale.

During sync:

the extension opens each enabled provider page in a popup-sized window;
the side panel shows External Shopping List sync status;
the extension reads visible unchecked/open provider items;
Blackcap reconciles those items into the Household List.

The sync summary uses these terms:

added: new provider item added to Blackcap;
updated: existing item/source metadata refreshed;
reopened: an item Blackcap thought was resolved is still open on the provider, so Blackcap put it back on the Household List;
checked off: a provider association disappeared or became completed externally and Blackcap reconciled it locally;
read: number of provider rows read from the page.

Reconciliation rules:

items are matched by normalized item name;
duplicate provider items consolidate into one Household List row;
if multiple providers contain the same item, one row is shown with provider/source metadata underneath;
provider associations that are no longer visible are marked inactive rather than deleting the Blackcap row immediately;
manual-only Household List rows are not checked off just because an external provider reference disappears;
ignored items remain linked but are hidden from shopping surfaces.

Ignoring external items

External items can be ignored from the Household List editor when they should remain on the external provider list but should not be treated as a Blackcap shopping need.

Ignored items:

stay linked to the provider/source;
are hidden from Admin Shop a List, Mobile Shop a List, and Shop With sessions;
appear in the Household preview with an ignored badge;
are not checked off or deleted on the external provider just because they were ignored;
are marked checked locally if a future provider sync no longer reports them as open.

Pinned Household items

Household List rows can be pinned when they are standing reminders for staples such as milk, bread, eggs, or other items the shopper should always consider. Pinning is intentionally the opposite of ignoring an external item:

ignored items stay linked but are hidden from shopping;
pinned items remain visible in shopping even after being bought;
checking off a pinned item marks it complete only for the current shopping session;
the backing Household List item is kept unchecked so it appears again in the next shopping session;
pinned provider-backed items can still participate in the normal attended external-provider check-off flow for the session that resolved them.

Admin and Mobile Shop a List attach a browser-session id to the shopping view so pinned items can move into the checked section for that trip without becoming completed on the persistent Household List. Shop With uses its existing session id for the same purpose.

The Household List editor exposes pinning as a compact 📌 toggle. A fully opaque pin means the item is pinned; a faded pin means it is not pinned. The Household preview shows a 📌 to the right of the item name only for pinned items. The same operation is available through POST /shopping-list/{list_id}/manual-item/anchor for API Tester and regression coverage.

Shopping with Household List items

Admin Shop a List

For normal Blackcap shopping lists, Admin Shop a List shows an Include Household List checkbox when the organization has Household List enabled. When selected, unchecked, non-ignored Household List items are included in the shopping view while the backing Household List rows remain separate from recipe/event rows.

The Admin view shows the synced-ago freshness pill next to the Include Household List checkbox. The pre-shopping Sync External Lists panel only appears when Household List items are included and the sync freshness setting recommends a sync.

Completing a normal Admin shopping list prepares provider check-off tasks for any included Household List items that were resolved.

Mobile Shop a List

Mobile Shop a List can include the last-synced Household List items and shows the synced-ago freshness pill when the Include Household List checkbox is available.

Mobile does not run external provider browser automation. It cannot sync Google Keep/Amazon pages and cannot check off provider items. Mobile shopping remains local/informational with respect to external providers.

Chrome extension Shop With

Shop With can include Household List items alongside recipe/event items. The side panel may show one consolidated shopping/search row for duplicate needs, but Blackcap keeps the underlying records separate so recipe rows and Household List provider references are not destructively merged.

Got It and Already Have It mark the Blackcap shopping rows resolved. External provider check-off does not happen item-by-item. For a normal shopping list, provider check-off runs only when the Shop With session is finished.

Shopping the Household List directly

The Household List can be shopped directly, but it is persistent and cannot be completed. When shopping the Household List directly from Admin, use Update External List to check off resolved provider-backed items externally.

Checking off external provider items

Provider check-off is attended and desktop-extension-based.

Trigger points:

Normal shopping list: completing the Admin list or finishing the Shop With session checks off resolved included Household List provider items.
Household List directly: press Update External List from the Admin Household List shopping view.
Mobile: no provider check-off is attempted.

During provider update:

the extension side panel opens in External Shopping List Update mode;
provider pages open in popup-sized windows;
the side panel shows total items, item names, success count, and failure count;
successful rows are recorded as completed externally;
failed rows are put back on the Household List so they are not lost.

Unresolved or unchecked Household List items remain open on the external provider. Blackcap does not check off provider items just because a recipe ingredient with the same name was completed.

Chrome extension permissions and popups

The extension needs host permission for the Blackcap server URL and for provider pages it reads or updates. If permission is missing, the side panel shows Grant Site Access with the provider context. Approve Chrome's host-permission prompt and continue the flow.

If the provider page is not signed in or MFA is required, Blackcap leaves the provider popup open and shows guidance in the side panel. Sign in normally in the provider popup, then continue the sync/update flow.

External sync and update status areas wrap across multiple lines in the extension side panel. The single-line animated current-item display is reserved for normal Shop With sessions.

Database model and Database Admin reconciliation

The Household List uses normal Blackcap shopping-list tables plus provider-source bridge tables. This keeps Household items compatible with existing Shop a List and Shop With behavior while preserving external provider identity.

Important tables/resources:

shopping_lists: the built-in Household List row has list_kind='household' and is_builtin=1.
shopping_list_items: visible Household List items live here. These rows are the items shown in Admin, Mobile, and Shop With.
shopping_list_items.external_source_*: compact rollup of the primary active external source. Do not treat this as the full source list.
household_list_item_external_sources: authoritative source-association rows. One Household item can have multiple active external sources, such as Amazon/Alexa and Google Keep both contributing milk.
household_list_browser_bridge_imports: attended Chrome-extension import history.
connections: organization External Shopping List connection configuration and metadata.
external_shopping_lists, external_shopping_list_items, shopping_list_external_item_links, and external_shopping_sync_runs: provider-neutral foundation tables for API-style/future external providers and any flows that use durable external snapshots.

To troubleshoot an item:

find the organization Household List in shopping_lists;
find the visible item in shopping_list_items;
inspect household_list_item_external_sources for every active/inactive provider association;
inspect household_list_browser_bridge_imports or extension side-panel status for the last browser sync/update run.

A duplicate item across providers should normally become one Household shopping_list_items row with multiple household_list_item_external_sources rows. The primary source rollup controls the visible badge/favicon, while the source table preserves the complete provider association set.

Ignored items are local Blackcap state. They can still have provider source associations, but they should not appear in Admin Shop a List, Mobile Shop a List, or Shop With.

Security and privacy notes

Provider passwords are not stored in Blackcap.
The extension uses the signed-in desktop Chrome session.
Extension API calls use the user's Blackcap API token.
Provider URLs and source metadata are stored as organization connection/list metadata.
Provider errors should not include secrets.
This feature is experimental/local browser automation and may need selector updates when Google Keep or Amazon changes page markup.

Troubleshooting

Sync button opens a provider page but no items import

Confirm the browser is signed into the correct Google/Amazon account, the selected Keep note or Alexa Shopping List is visible, and the extension has site access for that provider URL.

Google Keep connection keeps using the wrong list

Open the Keep list note from the connection dialog, verify the URL includes #LIST/..., close the provider popup, and save the captured URL. Use Use Selected URL or paste the URL manually if automatic capture misses the SPA fragment.

Amazon imports prices or cart data

Amazon extraction should be scoped to the Alexa Shopping List area. If cart/header/flyout content appears again, update the Amazon selector/filter logic in the extension and verify the page is the Alexa Shopping List URL rather than an Amazon cart or shopping page.

Provider check-off fails

The side panel shows failed item names and provider details. Failed items are put back on the Household List. Open the provider popup, confirm the items are visible/open, grant site access if requested, and run the update again.

Mobile shows stale sync information

Mobile uses the last-synced Household List snapshot. Use desktop Chrome to sync external providers, then return to mobile shopping.

Suggested regression checks

Sync Google Keep into the Household List.
Sync Amazon/Alexa into the Household List.
Verify duplicate provider items consolidate by name.
Ignore a provider-backed item and confirm it is hidden from Admin/Mobile/Shop With.
Include Household List items in a normal Admin list and complete the list.
Include Household List items in a Shop With session and finish the session.
Shop the Household List directly and press Update External List.
Confirm failed provider updates put items back on the Household List.
Confirm Mobile Shop a List includes Household List items but never attempts provider update.

Operations visibility

External Shopping List browser-bridge runs are visible in operations tooling:

Job Status → External Lists shows individual Household List imports and external provider check-off/update results. It includes provider, organization, status, item counts, and sanitized result details. Runs are grouped into queued, running, failed, completed, and ignored sections where applicable; completed history is collapsed by default. Failed provider updates are visible there so support can confirm when Blackcap put an item back on the Household List.
Performance → External List Performance shows aggregate duration and success/failure trends by provider/operation.
Database exposes the underlying state tables, including household_list_browser_bridge_imports, external_shopping_sync_runs, and household_list_item_external_sources.

Job Status does not expose cross-organization Sync Again or Update External List actions. Those actions require the desktop Chrome extension and a browser session signed in to the provider account for the active organization. System Admins can inspect another organization’s history, but provider automation should be launched from that organization’s normal signed-in browser context.

Browser bridge boundaries

The Household List browser bridge is the desktop Chrome extension path used by Blackcap's External Shopping List feature.

For the full user/admin guide, see:

This page is the canonical Household and External Shopping List guide.

Current implementation summary

The bridge supports organization-scoped External Shopping List connections for:

Google Keep
Amazon/Alexa
Custom URL

The extension opens provider pages in popup-sized windows, reads visible unchecked/open items from the signed-in Chrome session, imports them into the organization Household List, and later checks off resolved provider-backed items when an attended desktop flow explicitly triggers provider update.

Important boundaries

Blackcap does not store Google, Amazon, or custom-provider passwords.
This is browser automation through the user's signed-in Chrome session, not an official Google/Amazon OAuth API integration.
Mobile Shop a List can include the last-synced Household List items, but mobile cannot sync provider pages or check off provider items.
Provider check-off is not triggered when each individual item is checked. It runs only when a normal list is completed, a Shop With session is finished, or the Household List direct shopping view uses Update External List.
Failed provider updates put the item back on the Household List so the need is not lost.

Developer maintenance notes

Provider DOM selectors are intentionally conservative:

Google Keep reads selected list note rows and preserves the #LIST/... URL fragment during setup.
Amazon/Alexa reads from the Alexa Shopping List page/app area and filters cart/header/flyout text such as prices, checkout rows, and unrelated navigation content.
Custom providers use generic DOM extraction and may require a provider-specific extractor later.

The extension side panel has separate modes for Shop With, external import sync, and external provider check-off. Keep the single-line animated current-item behavior for Shop With only; external sync/update status should wrap naturally so provider status details remain readable.

Current implementation boundary

The implemented integration is the attended Chrome Extension browser bridge described above. It intentionally does not claim official Google Keep or Amazon/Alexa list API synchronization. Future official-provider work must be documented as a separate reviewed design only after provider eligibility, permissions, read/write semantics, and terms are verified.

For the item-by-item retailer workflow, see Chrome Extension Shop With.

Developer rules

Keep Household List persistence and reconciliation in the shared shopping-list/household-list service and repository boundaries.
Keep provider DOM extraction and attended provider-page interaction in the Chrome Extension.
Preserve organization scoping, source identity, provider/list identifiers, ignored/pinned state, and last-sync metadata.
Do not store Google, Amazon, retailer, or custom-provider passwords or browser cookies.
Treat provider page content as untrusted input and sanitize all submitted evidence.
Do not mark remote items complete until an explicit closeout action requests provider update.
On provider check-off failure, reopen the affected Household List item so the shopping need is not lost.
Keep external-list runs visible in Job Status and Performance without exposing provider credentials or cross-organization actions.

On this page