🧩 Chrome Extension Shop With

Audience: User, Org Admin, System Admin, Developer, Support Related: Shopping Lists · Household and External Sync · Shop With Providers · Kitchen Inventory

Shop With turns a Blackcap shopping list into an attended browser workflow on supported retailer websites. The Chrome Extension presents one consolidated shopping need at a time, helps the user search the selected provider/store, and writes the user's decisions back to the Blackcap list.

Shop With is not an unattended ordering bot. It does not place an order, select substitutions, submit payment, or store retailer credentials. The user remains responsible for the retailer page, product choice, quantity, cart, delivery/pickup, and checkout.

Requirements

• The Blackcap Chrome Extension is installed and connected with an active user-owned API Token.
• The token belongs to the organization containing the list.
• The user has permission to read/update that list.
• At least one Shop With provider is enabled in Configuration → Platform → Providers.
• The browser has granted the extension access to the selected Blackcap and retailer/provider hosts.
• The user is signed in to the retailer in Chrome when the provider requires an account.

Blackcap never receives or stores the retailer password, payment method, or authenticated browser cookies.

List selection

Shop With can use:

• a normal active Shopping List;
• a selected open Shopping List where the extension/API permits it;
• the persistent Household List;
• Household List items included with a normal shopping session.

The organization is determined from the API Token and extension selection. The server returns only lists and items the authenticated user may access in that organization.

Provider and store selection

System Admins maintain the platform provider catalog. Built-in definitions include providers such as Instacart, Shipt, Walmart, and Target, and custom providers can be configured.

A provider definition can specify:

• enabled state;
• display name/logo;
• recognized host patterns;
• home and search URL templates;
• integrated extension behavior or external-tab fallback;
• optional provider/store modes;
• browser viewport and attended runtime behavior;
• provider-specific extension rules/selectors.

Shipt supports a free-form store mode. A value such as target, costco, or another Shipt store slug can be entered; an empty value falls back to the configured default, normally stores.

The selected provider and store remain attached to the active Shop With session until the user changes them, resets the session, or completes it.

Item consolidation

Before the queue reaches the extension, Blackcap consolidates duplicate rows when it can do so safely. Consolidation uses normalized shopping/search text while preserving every backing shopping-list item reference.

• Matching quantities with the same unit can be summed.
• Mixed or uncertain units remain grouped with a count/source label instead of inventing a combined quantity.
• Recipe, manual, Household List, and externally sourced references remain traceable.
• Got It, Already Have It, review uncheck, and reshop actions update all backing rows represented by the consolidated item.

Consolidation changes presentation, not the underlying source-of-truth identity.

Shopping workflow

1. Open Shop With from Blackcap or the extension.
2. Select the organization, list, provider, and store when prompted.
3. The side panel shows the current item, quantity/unit, search text, department/source context, and progress.
4. Search for or add the desired product on the retailer page.
5. Choose one of the Blackcap actions:
   • Got It marks every backing item represented by the current consolidated row as shopped.
   • Already Have It resolves the shopping need and uses the normal Have It/Kitchen Inventory flow, including storage-location selection where required.
   • Skip moves the item later in the current queue without completing or deleting it.
6. Continue through the queue.
7. Review completed/skipped items when needed.
8. Complete the session or use Return to go back to Blackcap.

The current-item line uses a compact animated overflow treatment for long item names. External-list sync/update status uses normal wrapping because provider diagnostics are more important than a single-line presentation.

Complete, Return, and reset

These actions have intentionally different meanings:

• Complete finishes the Shop With session, finalizes the Blackcap list state, runs any explicit external-list closeout that is due, clears extension session state, and closes the shopping side panel. It does not navigate back to Blackcap.
• Return leaves the attended provider workflow and returns the user to Blackcap's Shop a List page.
• Reset abandons the extension's current provider/session selections without silently deleting the underlying Shopping List.
• Closing the browser/side panel does not imply successful completion; the session can be resumed from retained Blackcap/extension state where supported.

Household and external-provider items

Household List items participate in the same queue. Externally sourced items retain provider/list/source identity.

Checking an item during normal shopping does not immediately manipulate the external provider page. Provider check-off is attempted only through an intentional attended closeout action, such as:

• completing a normal list that included Household List items;
• completing Shop With;
• choosing Update External List while shopping the Household List directly.

Successful provider items are checked off remotely. If a provider check-off fails, Blackcap puts the affected item back on the open Household List so the need is not lost. The extension shows the successful/failed counts and the result remains visible in Job Status → External Lists.

Mobile can shop the last-synced Household List snapshot but cannot run provider browser automation or remote check-off; that requires desktop Chrome and the extension.

Relationship to Kitchen Inventory

Already Have It and supported completion flows must use the canonical Kitchen Inventory service rather than creating a separate extension inventory. Normalized identity, organization uniqueness, grocery department, Have It state, and storage location follow the same rules as Admin and Mobile.

Permissions and security

• API Tokens are user-owned, organization-bound, named, revocable, and shown once at creation.
• The extension never gains more permission than the token/user already has.
• Retailer and external-list pages are untrusted input.
• Host permissions should be limited to Blackcap and configured providers required by current features.
• Provider credentials, cookies, payment data, and order history must not be submitted to Blackcap.
• The extension must not automate checkout, payment, purchase confirmation, or other irreversible retailer actions.
• Server responses and extension submissions must preserve organization IDs and backing item IDs rather than relying on visible row positions.
• API Token access activity may record endpoint, IP, country, and user agent for authorized troubleshooting.

Operations visibility

• Job Status → External Lists shows attended import/check-off runs, provider, organization, status, item counts, failures, and sanitized result details.
• Performance → External List Performance shows duration and success/failure trends by provider and operation.
• Audit activity records relevant extension/list actions without storing retailer credentials or full page content.

System Admins can inspect another organization's history when authorized, but they cannot launch that organization's attended browser action from Job Status because provider automation depends on the user's signed-in Chrome session.

Troubleshooting

Shop With is not offered

Confirm the extension is connected, the API Token is active for the intended organization, the list contains open shop-ready items, and a provider is enabled.

The extension requests site permission

Grant permission only for the intended configured provider host. If the requested host is unexpected, cancel and review the provider definition.

The retailer page is not recognized

Open the provider from the extension again, verify the hostname matches the provider definition, and check whether the retailer changed its page. Use the configured external-tab search fallback when available.

The wrong Shipt store opens

Review the session's free-form Shipt store value. Clear it to use the default stores path or enter the intended Shipt store slug.

An item keeps returning

A skipped item rotates instead of completing. For externally sourced items, a failed remote check-off intentionally reopens the Household List item. Review the External Lists job detail before marking it complete again.

Duplicate items were combined incorrectly

Review normalized names, quantities, units, and source refs. Unsafe mixed quantities should remain grouped rather than summed. Fix consolidation in the shared shopping service, not by discarding backing IDs in extension code.

External completion did not synchronize

Open Job Status → External Lists. Confirm the provider page was open, the browser was signed in, host permission was granted, and the provider DOM still exposes the item. Failed items are reopened on the Household List.

Developer rules

• Keep shopping-list state and consolidation in shared Blackcap services/repositories.
• Keep retailer DOM selectors and attended browser behavior in the Chrome Extension/provider adapter boundary.
• Use stable item_id/source references, not row indexes, for mutations.
• Preserve organization scoping, explicit-column queries, safe retries, audit context, and external source identity.
• Never add provider passwords/cookies to payloads or logs.
• Keep Complete, Return, Skip, Got It, Already Have It, and provider closeout semantics distinct.
• Test normal lists, Household List inclusion, duplicate consolidation, storage location, provider/store persistence, completion, remote check-off success/failure, and resume/reset behavior.