Storefront integration

Updated September 30, 2026

Choose the supported integration path for product pages, cart pages, cart drawers, and custom theme storefronts.

Start with the lightest integration that gives you the presentation control you need. The Upsell paths below use the same published recommendation decisions. Bundles use their own bundle setup and SDK contract.

Storefront need	Recommended path	What you own
Standard product page	Product page app block	Placement and Theme Editor settings
Standard cart page	Cart page app block	Placement and Theme Editor settings
Compatible cart drawer	Cart drawer app embed	Enablement and optional placement overrides
Custom theme markup	JavaScript SDK through Shopify App Proxy	Mount point, lifecycle, and optional custom rendering
Fully custom cards	Facts API plus SDK event helpers	Rendering, product hydration, cart writes, and event wiring

The browser-facing SDK and endpoints use Shopify App Proxy authentication. A private API credential is not required for this path and must never be placed in theme JavaScript. See Storefront API and authentication.

Product page app block

Add the block to the product template in the Theme Editor. The block sends the current product as its source, requests Market-aware rendered HTML, and wires impressions and add-to-cart behavior. A recommendation failure leaves the slot empty; it never blocks the product form.

Cart page app block

The cart block resolves from the live cart lines and current Shopify Market. Every matching published rule can contribute candidates; duplicate products are removed and each returned card keeps one Campaign and Rule owner for attribution.

Cart drawer

Shopify themes implement drawers differently. Use these paths in order:

Cart drawer app embed. Enable the embed. It uses the explicit settings you provide or a maintained compatible-theme selector.
Explicit mount point. Add <div data-tab-cross-sell="cart_drawer"></div> inside the live drawer. An explicit mount point wins over theme detection.
SDK-owned lifecycle. For a custom drawer, create and start the SDK drawer controller so a drawer replacement or cart-line change triggers a fresh mount.

If the theme is not compatible and no explicit mount point is found, the integration waits silently. It does not patch arbitrary drawer markup or write errors to the storefront console.

Check the shop’s access

Confirm the required placement and API entitlements in the app before choosing an integration. API/SDK delivery is for Shopify Online Store pages on the shop origin; it does not provide an externally hosted headless storefront. See Plan access and analytics.

Custom theme storefront

Custom theme integrations call the shop-relative App Proxy base:

/apps/tab-cross-sell

Choose one rendering mode:

Rendered HTML: POST /recommendations/rendered returns the authoritative card fragment. client.mount() inserts it and observes valid impressions. This is the closest custom-theme path to the official blocks.
Facts only: POST /recommendations/resolve returns decisions and candidate identities without a UI. Your code hydrates products, renders cards, writes to Shopify cart, and tracks every event.

Continue with JavaScript SDK or Storefront API and authentication.

Support boundary

Merchants are not expected to debug App Proxy requests, SDK lifecycle behavior, or attribution wiring themselves. For a custom theme or agency build, contact Tab Commerce before launch. We will review the integration path with the implementing team and help isolate routing, Market context, campaign matching, rendering, and event-identity issues.

The storefront should still fail safely while an issue is being investigated: a recommendation failure leaves the placement empty and never blocks product discovery, cart updates, or checkout.

Failure behavior

Empty candidates, invalid Market context, a timeout, a network error, or a failed display-data lookup all degrade to an empty slot. Do not replace that behavior with stale recommendation HTML. Storefront availability and checkout remain independent of Tab Upsell & Bundles.