AisleAsk — Digital Deals & Coupons

Status: planned (spec). Driver: a real prospective user ("Grandma Pat") — "I'd use AisleAsk if it peppered in the digital coupon deals along the way, and/or let me just shop the deals."

Two modes she asked for, both of which merge cleanly onto AisleAsk's existing spine (a route by section + a normalized product→section map):

• Mode A — deals along the way. As you walk into each section, surface the single best relevant deal ("In Dairy: your yogurt is BOGO"). Attaches to the route by section and to list items by product match. On glasses, JQ speaks it on the existing GET /:store/next beat.
• Mode B — shop the deals. A new list source: "What's on sale at my Safeway?" → pull current deals → tap to add → route them like any items. Slots into the existing import-sources architecture (recipes/lists → one route) — deals are just another source.

Non-negotiable honesty guardrail

Deals are store- and time-specific; a stale or wrong price burns trust fast, especially for a price-sensitive shopper. Rules:

• Only show a deal we can scope to this store.
• Always show the deal's source + validity window; never fabricate.
• If we can't verify a deal at this store, don't show it.
• Loyalty-linked coupons require explicit card-linking consent.

Data sources — ranked by leverage

1. Flipp / Wishabi weekly-ad API — one partnership, structured store-scoped circular deals across most major chains. Powers both modes. Highest-leverage single move; needs a partner agreement. (QuickSites owns the commerce/partnership side of the mesh — a Flipp deal could serve their storefronts too. Sounding them out — see crosstalk.)
2. Kroger Developer API (owns QFC) — public API with per-store product + promotion data, OAuth into the loyalty card for clipped digital coupons. Most-open retailer-direct option. Safeway/Albertsons is far more closed.
3. Ibotta / Coupons.com (Quotient) / Checkout51 — item- and brand-level rebates + manufacturer coupons, grocery-focused, with affiliate revenue share (same model as the Amazon hivejournal-20 tag). Merges at the item level. Buildable without a data partnership.
4. Crowd + glasses capture — reuses what shipped for the store-walk: extend "scan this aisle" → "scan this sale tag" — OCR the yellow shelf tag (gpt-4o-mini vision, already proven for aisle signs) into a crowd deal tied to a product + store. No partnership, self-serviceable, dovetails with the walker gig ("while you catalog, capture sale tags"). Sparse at first, but free and honest.
5. Scraping retailer apps — ToS/legal landmine, fragile. Not a foundation.

How it merges (mechanics that already exist)

• Deals key to the normalized product name → a join against the global aisleask_product_sections map. Item match is essentially free.
• Section-tagged deals ride the existing section walk order for the "along the way" peppering.
• "Shop the deals" is a new source feeding import-sources → route.
• Glasses: the deal rides the existing GET /:store/next hook — JQ speaks the next item + its deal.

Shared offer contract (QuickSites-owned capability)

The offer shape and the shared GET /api/deals feed are owned by QuickSites and specified in the single source of truth: crosstalk/contracts/deals-feed.md — do NOT fork the shape here. Summary (as of 2026-07-24): QS owns the feed; three consumers — AisleAsk (in-store, store-scoped), QS storefront promo blocks, and PorchHearth (cook sourcing, the store-agnostic "best offer per item across nearby stores" query mode). Two query modes, one normalized Offer record, every source emits it. Same reusable-capability discipline as route-optimize / capture-grant.

Phase 0 (below) is HJ-internal crowd + affiliate. Its aisleask_deals rows map onto the contract's Offer record (store_id→store_scope, normalized_product→product_match, offer_text+source→offer, valid_until→valid_thru) so that when the shared feed exists, our output is a drop-in source — no rebuild. The contract, not this file, is authoritative for the exact field shapes.

Decision (2026-07-24): the paid-aggregator partnership (Flipp/Wishabi = real spend) is DEFERRED until Phase 0 proves out — build the free crowd + affiliate path first, then revisit a paid feed with real usage data, not a guess. QS owns the shared /api/deals capability and will co-define the contract if the paid feed is later greenlit; no dependency until then.

Staged plan

Phase 0 — build now (no partnership, dogfoodable today)

The wedge: crowd + affiliate, both self-serviceable.

1. "Scan this sale tag" — a new glasses/phone capture, sibling to scanSectionSign:
   • Glasses intent deal/scan ("scan this deal / scan this sale tag"), or a phone "📷 Scan a deal" button on the store's Deals tab.
   • Photo → gpt-4o-mini vision extracts { product, price, deal_text (e.g. "BOGO", "2 for $5"), valid_until? } → writes a crowd deal.
   • Rides the capture rail (new purpose aisleask_deal, self-subject, no consent gate) for the durable photo record + provenance.
   • Store-scoped (the store you're in / the glasses-active store) + product normalized so it joins the product→section map.
   • Honesty: source = crowd, captured_at stamped, shown with "spotted <date>" so it's clearly a shopper sighting, not a guaranteed price.
2. New table aisleask_deals — stores the crowd/affiliate offers; its read output maps to the shared Offer record above (store_id→store_scope, normalized_product→product_match, deal_text→offer, source, valid_until→valid_thru), so a future QS-owned /api/deals feed is a drop-in additional source, not a rebuild. Columns: { id, store_id, normalized_product, offer_text, valid_until, source ('crowd'|'affiliate'|'flipp'|'kroger'), confidence, captured_by, created_at }. Service-role only (matches the rest of AisleAsk).
3. Affiliate item-match — for list items, look up Ibotta/Coupons offers by normalized product/brand and attach them (revenue share). Behind a provider wrapper so Phase 1/2 sources plug into the same merge.
4. Surface:
   • List view: a small "💸 deal" chip on matching items (source + validity on tap).
   • New "Deals" tab / "Shop the deals" — the store's current deals as a tappable add-to-list set (Mode B).
   • Glasses: GET /next includes the item's deal so JQ can speak it (Mode A).

Phase 1 — the real deal engine

Flipp weekly-ad partnership → store-scoped structured deals across chains. Backfills both modes with verified, dated circular data. This is the quality leap. (QS coordination in flight.)

Phase 2 — personalized

Kroger/QFC loyalty linking (their API is the most open) → the user's clipped digital coupons, the richest + most accurate, behind explicit card-linking consent.

Why this is also monetization

Coupon/rebate affiliate (Ibotta, Coupons.com, Flipp) is a revenue stream aligned with AisleAsk's operated-service business model — not just a feature. The "shop the deals" mode is exactly where intent-to-buy is highest.

Mesh reuse

• Glasses scanSectionSign → scanDealTag (same vision + capture pattern).
• Capture rail: new aisleask_deal purpose (one-line CHECK widen).
• import-sources merge: deals as a new source.
• GET /:store/next glasses hook: carries the deal.
• Global product→section normalization: the join key for every source.