Instacart Web Substitution Preference Overlay

WHAT IT DOES

This tool helps you manage substitution preferences for your Instacart shopping cart or order. It extracts product names, brands, sizes, quantities, and current substitution settings from the page, displaying each item in a clear panel. Each item shows its substitution preference (Refund, Substitute, or Shopper's Choice) as a clickable button — clicking cycles through the available options. Items that are out of stock or have pending substitution decisions are highlighted with a red border and status badge. The panel provides a summary showing total items, issues, and counts by preference type. You can save preferences per product for future orders, apply a default preference to all items at once, and auto-save changes as you make them.

WHERE IT RUNS

The script activates on Instacart pages (instacart.com), including shopping carts, order review pages, and checkout screens. It automatically detects cart items using multiple extraction strategies that work across different Instacart layouts. The panel appears as a draggable overlay that stays accessible as you review your order.

HOW TO USE

Navigate to your Instacart cart or order page. The panel will appear showing all items with their current substitution preferences. Click any preference button to cycle through options: Unknown → Refund → Substitute → Shopper's Choice → Unknown. The item's preference updates immediately. Use the "Save" button (💾) next to any item to save its preference for future orders — the script remembers it using the product name, brand, and size. Set a default preference using the dropdown, then click "Apply Default to All" to set all items to that preference. Toggle "Auto-save on" to automatically save preferences when you change them. The "Refresh" button manually updates the item list, and "Clear Saved" removes all saved preferences. The summary shows how many items have each preference type and highlights any items with issues (out of stock or pending decisions).

THE TECHNICAL MECHANISM

The script employs a multi-strategy DOM extraction approach for Instacart's dynamic cart interface. It first attempts structured selectors targeting known class names like .cart-item, .order-item, and .product-item, then falls back to heuristic detection of item containers based on content patterns including currency symbols, product-related keywords, and reasonable text length. Product name extraction prioritizes dedicated name elements and falls back to parsing the first non-numeric line of text. Brand, size, and quantity are extracted from dedicated elements or regex patterns. Substitution preference detection uses pattern matching for common Instacart phrasing: "refund" or "don't replace" for refund preference, "substitute" or "replace" for substitute preference, and "shopper's choice" or "best match" for shopper's choice preference. The preference cycling logic uses an ordered array with wrap-around to provide a smooth UI experience. Saved preferences are stored using GM_setValue with a product key derived from the item's name, brand, and size. The script also tracks out-of-stock and pending status indicators from the page to highlight items needing attention. All settings are persisted using GM_setValue.

THE PANEL

The panel is fully draggable by its header and remembers its position on the page across sessions. It can be collapsed to a small bubble using the minimize button, then restored by clicking the bubble. The panel resizes automatically to fit its content and can be closed with the Escape key or by clicking the close button. The panel's position and state persist globally, so it returns to the same location on subsequent visits.

PLEASE NOTE

Requires the free BotGentz extension to run. Instacart may update its site structure, which could affect the script's ability to detect items and preferences — updates will be released as needed. All preference data is stored locally in your browser and is never transmitted externally. This tool is for convenience only and does not guarantee that your substitution preferences will be honored by Instacart shoppers. Always verify your order and preferences directly on the Instacart platform. The script does not modify your Instacart account or place orders.