# Pour Now Omnichannel Overlay — Agent Instructions You are an agent building a retailer purchase path on a brand's DTC product page, presented side by side with the brand's own Add to Cart. The goal is juxtaposition: the shopper sees two legitimate ways to buy (ship direct from the brand, or buy near you through a retailer) and picks the one that fits their moment. Neither path is framed as better. This document is self-contained. It encodes four proven presentation patterns (A through D), a button copy system, an anchoring guide, platform playbooks for Shopify, Commerce7, WooCommerce, and Offset Commerce, and acceptance criteria. Follow it exactly where it is specific; use judgment where it defers to the host site's design. Reference implementations live in this repo under `code/` (Shopify Liquid snippet, Commerce7 JS drop-in, WooCommerce plugin — each with an INSTALL.md). If you have the repo, start from those files and adapt to the host site instead of writing from scratch. Source design reference: `Omnichannel_Suggestions.pdf` (five slides: variants A-D on a tequila PDP, plus a copy exploration). If the operator provides the PDF, treat it as the visual ground truth for structure and hierarchy. --- ## 1. What you are building Every variant adds a **retailer lane** to the product page buy area: - **DTC lane** (already exists): quantity picker + Add to Cart, shipping promise (e.g. "Free ground shipping on 6+. Arrives in 2-3 days.") - **Retailer lane** (you add it): a short value line ("Curbside pickup, same-day delivery, local retailers, and more.") and a **Shop Now** action that routes to the product's Pour Now listing, where the shopper picks a retailer and purchase modality (nearest, fastest, best price, pickup, shipped). The Shop Now destination is one of two shapes, supplied by the operator: - **A Pour Now consumer listing URL** (a `pour.now` link), or - **A brand-hosted locator page** that embeds the listing (e.g. `/pages/store-locator`) — see section 5 for the embed and anchoring mechanics. Either way, you never build retailer selection UI yourself; the listing handles it. With a brand-level listing, anchor the specific product via `?productId=` (section 5). ### Non-negotiable framing rules 1. **Never disparage DTC.** The brand sells direct; the retailer lane is an addition, not a replacement. Copy is "prefer other options?" not "skip the wait." 2. **Never fabricate availability.** No "in stock at 12 stores near you" claims unless the operator wires a live data source. Static copy stays modality-generic: pickup, same-day, local retailers. 3. **Compliance stays with the retailer.** Do not add age gates, shipping-legality claims, or compliance language to the overlay. The retailer's checkout owns that. Do not state or imply that the brand or Pour Now handles compliance. 4. **Match the host site.** Inherit the brand theme's fonts, colors, button styles, radii, and spacing. Do not import Pour Now brand styling onto the brand's PDP. The overlay should look native, as if the brand's own designer built it. 5. **No dark patterns.** No fake urgency, no preselected lane, no hiding the DTC path. --- ## 2. Inputs to collect before building Ask the operator for these up front (one message, not five): | Input | Required | Notes | | ----------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Platform | yes | Shopify, Commerce7, WooCommerce, or Offset Commerce | | Variant | yes | A, B, C, or D (see section 3). Default to B if they have no opinion; it is the least invasive. | | Pour Now listing URL(s) | yes | Per product, a brand-level listing, or the brand's locator page that embeds the listing. Format is typically a `pour.now` consumer listing link or a `/pages/store-locator`-style page. | | Pour Now product IDs | for anchoring | From the Pour Now platform: Listings > open the listing > Products Config (e.g. "ID: 24943307"). Required to anchor a specific product on a brand-level listing. On Shopify, these often already live in a "Pour Now Product ID" product metafield. | | Product scope | yes | All products, a collection, or specific SKUs | | Copy lead | no | One of the six copy families in section 4. Default: modality-led primary line + location-led button. | | Access | yes | Shopify: theme or app access. Commerce7: frontend repo/CMS access. WooCommerce: wp-admin (plugin install) or theme child access. Offset: admin access or an Offset Partners contact. | | Attribution tags | no | UTM overrides. Defaults in section 6. | If the operator cannot supply a listing URL, stop and tell them that is the prerequisite; do not point Shop Now at a placeholder in production. --- ## 3. The four variants All variants live inside the existing buy box region of the product template, below price/tags and above the long description. Structure below is semantic, not pixel-prescriptive; realize it in the host theme's visual language. ### Variant A — Two lanes, side by side Two equal-weight cards in a row (stacked on mobile), separated by a small "OR" badge at the seam. - **Left card (DTC):** kicker "SHIP TO YOUR DOOR", heading "Buy direct", shipping promise line, quantity stepper + Add to Cart (solid/primary button). - **Right card (retailer):** lightly tinted background to differentiate, kicker "BUY IT NEAR YOU" (accent color), heading "Prefer other options?", value line "Curbside pickup, same-day delivery, local retailers, and more.", Shop Now button (outline/secondary style, location pin icon). Use when: the brand wants the strongest statement of channel equality. Costs the most horizontal space. ### Variant B — Primary + secondary DTC stays exactly as it is: quantity + full-width Add to Cart. Below it, a thin labeled divider "OR BUY FROM RETAILERS NEAR YOU", then a single tinted band: pin icon, "Prefer other options?" heading, value line, and a compact "SHOP NOW →" text button on the right. Use when: DTC is the brand's priority channel and the retailer path is a safety net. Least invasive; the default. ### Variant C — Choose your path A segmented control (two tabs: "Buy direct" | "Buy near you") above a single panel. - **Buy direct tab:** one-line summary ("$X a bottle · free ground shipping on 6+ · arrives in 2-3 business days."), quantity + Add to Cart. - **Buy near you tab:** value line + Shop Now button (and nothing else; keep the panel calm). Tabs must be keyboard-accessible (`role="tablist"`, arrow keys, `aria-selected`) and default to Buy direct. Persist the last-selected tab per session if trivial on the platform; do not build storage infrastructure for it. Use when: the buy box is cramped and the brand wants a clean single-column PDP. Hides one path at a time, so weakest for juxtaposition measurement. ### Variant D — Benefit stack One card containing two stacked rows: - **Row 1 (DTC):** truck icon, "Buy direct" heading with microcopy "Ships in 2-3 days · free on 6+", inline quantity + Add to Cart (solid). - **Row 2 (retailer, tinted):** pin icon, "Prefer other options?" heading with value line, Shop Now (outline). Use when: the brand wants both paths always visible but vertically compact. Good mobile behavior out of the box. ### Shared details - The value line for the retailer lane is always some variant of: "Curbside pickup, same-day delivery, local retailers, and more." - Icons: use the host theme's icon set if it has one; otherwise simple inline SVG line icons (truck for DTC, location pin for retailer). No emoji. - The tinted retailer surface should be a very light tint derived from the theme (a warm neutral or the brand accent at ~5-8% opacity), never a loud color block. - Shop Now opens the listing in a new tab (`target="_blank" rel="noopener"`), preserving the brand session. --- ## 4. Button copy system Six families, grouped by what the label leads with. Pick one family and stay consistent across the site. The framing device (section 3) carries the either/or; the button just names the action. | Family | Options | Note | | ------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | Location-led | Find nearby · Buy near you · In stock near you · Available near you · Where to buy · Find where to buy · Buy it here | Says where, but not that a store is involved | | Retailer-led | Find a retailer · Shop retail partners · Buy from our retail partners · See who carries it · Shop your favorite stores | Clearest about the store handoff; labels run long | | Speed-led | Get it today · Pick up today · Same-day near you | Sells immediacy, the strongest reason to skip shipping | | Community-led | Shop local · Support your local store | Warm and brand-friendly, but vague about what happens next | | Partner-led | Order via · Order through · Order from · Shop through | Frames the handoff into a retailer cart; shopper picks the store next, so no single logo | | Modality-led | Check availability · See what's in stock · In stock now | Leads with whether it's gettable; reassures before routing | Ground rule from the source exploration: **copy alone cannot carry the either/or.** Any of these only work paired with a framing device from section 3. Default pick: "Shop now" on the button with the modality value line above it, or "Buy near you" if the brand wants the button itself to explain. Casing: follow the host theme (many themes use uppercase button labels; the mockups do too). Match, don't fight. --- ## 5. Product anchoring (official Pour Now pattern) Source: Pour Now internal guide "How to: Anchor Products to Pour Now Listings" (Julianna Bologa, Scribe). This is how shipped integrations (19 Crimes, Zarpado) work; follow it rather than inventing a mapping scheme. ### 5a. The anchoring parameter A brand-level listing shows the whole portfolio. To land the shopper on the product they were just looking at, append the **Pour Now product ID** to the destination URL: ``` {listing_or_locator_url}?productId={pournow_product_id} ``` - The ID is Pour Now's, not the platform's. Find it in the Pour Now platform: **Listings > open the listing > Products Config** (e.g. "ID: 24943307"). - Live example: `https://19crimes.com/pages/store-locator?productId=24935146` - If the URL already has query params, append with `&` instead of `?`. ### 5b. Brand-hosted locator pages Many brands host the listing on their own page instead of linking to `pour.now` directly. The page needs exactly two pieces: ```html ``` `product-anchor.js` (Pour Now-hosted) does two things: auto-sizes the iframe via `postMessage` height events, and reads `?productId=` from the host page URL and forwards it into the listing to anchor that product. The iframe id must be exactly `pournow-shelf`. If the brand already has such a page (look for `script.pour.now/product-anchor.js` or a `store-locator` page), point Shop Now at that page with `?productId=` — do not build a second destination. ### 5c. Where the product ID lives per platform - **Shopify:** shipped integrations store it in a product metafield displayed as "Pour Now Product ID" (Shopify Admin > Products > product > Metafields). Check Settings > Custom data for the store's actual namespace/key before reading it in Liquid. Workflow: copy each ID from Products Config, paste into the metafield, build the Shop Now URL as `{locator_url}?productId={metafield value}`. - **Commerce7 / WordPress:** a custom field on the product page, or the JS config map keyed by product slug (section 7b). - **WooCommerce:** post meta on the product (the reference plugin uses `_pn_listing_url` for full URLs; add `_pn_product_id` + a base locator URL if the brand anchors onto one listing). ## 6. Attribution wiring Every Shop Now link carries query params so the juxtaposition is measurable in Pour Now analytics and the brand's own tooling: ``` {listing_url}?utm_source=brand-site&utm_medium=pdp&utm_campaign=omnichannel-{variant}&utm_content={product_handle} ``` - `{variant}` is `a`, `b`, `c`, or `d` (lowercase). - `{product_handle}` is the platform's product slug/SKU. - If the operator supplies their own UTM scheme, use theirs. Also fire the platform's native analytics event on Shop Now click if the site has one (e.g. a custom event `omnichannel_shop_now` with variant + product). Do not add a new analytics vendor for this. This is what makes the experiment real: DTC add-to-cart rate vs retailer-path clickthrough per variant, per product. If the brand wants a proper A/B test across variants, build all four gated behind a single config setting (section 7 playbooks say where the setting lives per platform) and let their testing tool or a simple percentage split flip it. --- ## 7. Platform playbooks ### 7a. Shopify **Preferred: theme app extension app block** (if working inside the Pour Now Shopify app repo, add it under `extensions/`). Otherwise a **theme section/snippet edit** in the merchant's Online Store 2.0 theme. App block route: 1. Create a theme app extension with one block, target `section` so merchants can drop it inside the product information section directly below the buy buttons. 2. Block schema settings: `variant` (select a/b/c/d), `listing_url` (text, fallback), `button_label` (text, default "Shop now"), `value_line` (text with the default value line), `show_or_divider` (checkbox, variant B). 3. Per-product listing URLs come from a product metafield `pournow.listing_url`; block falls back to the schema-level `listing_url` if the metafield is empty. Define the metafield via the app if you have app access, otherwise instruct the operator to create it in Settings > Custom data. 4. For variant B/D you are rendering alongside the theme's own buy buttons: do not duplicate Add to Cart. Render only the retailer lane and divider. For variants A and C, the block must include its own product form (`{% form 'product' %}` with variant id + quantity) and the operator hides the theme's default buy buttons on that template. 5. Styling: use CSS custom properties the theme exposes where possible; otherwise inherit `font-family` and set colors from block settings. Scope all CSS under a `.pn-omni` root class. Theme edit route (no app): add `snippets/pn-omnichannel.liquid` and render it from the product template below the buy buttons, with the same settings surfaced through the section schema. Verify: `shopify theme dev` or a duplicate theme preview, check desktop + 375px mobile, both a product with a metafield URL and one falling back, Add to Cart still functions, Shop Now lands on the listing with UTMs intact. ### 7b. Commerce7 Commerce7 storefronts are usually a brand-owned frontend (frequently WordPress, sometimes custom) with Commerce7's JavaScript widgets rendering the commerce pieces (`div` mount points like the buy/add-to-cart widget). You are wrapping their buy widget, not modifying it. 1. Locate the product page template in the site's CMS/theme and the element where the C7 buy widget mounts. 2. Build the variant structure around that mount point: the DTC lane wraps the existing C7 widget; the retailer lane is plain HTML you add beside/below it. 3. Because C7 widgets render asynchronously, do not reparent the widget's DOM after render. Place the wrapper in the template so the widget mounts inside the DTC lane from the start. If template access is limited to injected JS, run your layout script before C7 initializes or on `DOMContentLoaded` prior to the widget's mount, and test hard for race conditions. 4. Product-to-listing mapping: a JS object or CMS field keyed by C7 product slug. On WordPress, prefer a custom field on the product page over a hardcoded map. 5. Variant C caution: do not put the C7 widget in a `display:none` tab panel at page load; some widget versions mis-measure hidden containers. Render both panels and toggle with `visibility`/position or initialize on first tab reveal. 6. Styling: the site's own CSS, scoped under `.pn-omni`. Verify: real product page in a staging or draft page, add to cart through the C7 widget still works end to end (cart drawer opens, item added), Shop Now UTMs intact, mobile stack correct. ### 7c. WooCommerce **Preferred: the single-file plugin** at `code/woocommerce/pn-omnichannel.php` (settings under WooCommerce > Pour Now Omnichannel; per-product listing URL field on the product edit screen, General tab, falling back to the plugin's default URL). If you cannot install plugins, replicate its hooks in the child theme's `functions.php`. 1. All four variants are supported. B and D append the retailer lane via `woocommerce_single_product_summary` priority 31 (just after Add to Cart at 30). A and C wrap the theme's own add-to-cart form with `woocommerce_before_add_to_cart_form` / `woocommerce_after_add_to_cart_form`, so quantity pickers and variation selects keep working untouched. 2. **Block themes:** if the Single Product template is built with blocks, the classic hooks may not fire. Options: switch the product template to classic, or add a Custom HTML block below the buy box with static variant B markup. Flag which route was taken. 3. **Page builders (Elementor and friends):** if the builder replaces the product summary, use its equivalent "after add to cart" position; fall back to variant B. 4. Per-product mapping is post meta `_pn_listing_url`; never hardcode a slug-to-URL map in the theme when the meta field exists. 5. Styling: the plugin inherits the theme font and exposes `--pn-omni-accent`, `--pn-omni-tint`, `--pn-omni-radius`, `--pn-omni-line` custom properties — set them in Additional CSS to match the brand. Verify: staging site, Add to Cart on a simple AND a variable product unchanged, lane renders only on product pages that resolve a listing URL, UTMs intact, variant C tabs keyboard-accessible, 375px stack. ### 7d. Offset Commerce Offset Commerce (Offset Partners) is a closed, managed template system common among premium wineries. Template-level changes generally go through Offset or through the limited custom HTML/CSS/JS regions exposed in the admin. 1. First ask the operator what access exists: (a) Offset will apply template changes on request, (b) admin exposes a site-wide custom JS/CSS slot, or (c) content-block HTML only. 2. **Route (a), preferred:** produce a handoff spec instead of live code: the variant's HTML structure with the site's actual class names, the CSS, the listing URL mapping table (SKU to URL), and placement instruction ("directly below the add-to-cart control on product detail templates"). Write it so Offset's team can implement without a call. Deliver as a single markdown or HTML file. 3. **Route (b):** write a defensive injection script: on product pages only, locate the buy form via a stable selector, insert the retailer lane after it, read the product identifier from the page, look up the listing URL from an inline map. Fail silent (render nothing) if the selector misses; never break the buy box. Variants B and D only; A and C restructure the DTC form itself, which is too invasive for injected JS on a managed platform. 4. **Route (c):** last resort; a retailer band as a content block below the buy area, per product, maintained by hand. Flag the maintenance cost to the operator. Verify: on the live or preview site, the buy form still submits, the lane renders on product pages only, and nothing renders on pages where the selector fails. --- ## 8. Acceptance checklist Do not report done until every line passes: - [ ] Both lanes visible (or both tabs reachable, variant C) on desktop and 375px mobile - [ ] DTC add to cart works exactly as before the change - [ ] Shop Now opens the correct Pour Now listing in a new tab, UTMs present, variant and product tokens filled - [ ] Per-product listing mapping verified on at least two products, plus the fallback path - [ ] If anchoring onto a brand-level listing: `?productId=` carries the Pour Now product ID (from Products Config, not the platform's ID) and the listing lands anchored on the right product - [ ] Copy matches the chosen family; no availability claims, no compliance language, no DTC disparagement - [ ] Styling inherits the host theme; nothing looks pasted-in - [ ] Keyboard and screen reader pass on any interactive element you added (tabs, buttons) - [ ] Nothing renders (and nothing errors) on non-product pages - [ ] Screenshot evidence captured: each variant built, desktop + mobile, both lanes/states Report to the operator: what was built, where it lives (files/settings), the mapping table you configured, and the UTM scheme, so their analytics team can find the traffic.