Catail AI
Sign inSign up

Install on Shopify

Connect Catail to your Shopify storefront in four steps. The setup checklist in the Catail app (Shopify admin → Apps → Catail AI) shows live status for each step. Time: ~10 minutes.

What you are connecting

Add-to-cart on product pages can work from button markup () without the Web Pixel. Install the pixel and webhook for full cart → checkout → purchase reporting.

ComponentWhat it doesRequired for
Shopify Customer PrivacyStore-wide consent bannerBehavior analytics (pointer, heatmap, replay) after consent
Theme app embedApp embed in Theme Editor — no manual code edits; removed automatically on uninstallSessions, page views, scroll/pointer signals, cart session bridge
Shopify Web PixelCheckout sandbox eventsCommerce funnel after add-to-cart
orders/create webhookServer-side order notificationReliable purchase when Shop Pay skips the pixel
Product page blockOptional product template block for approved Catail PDP variantsShowing approved variants in controlled product page tests

1. Enable Shopify Customer Privacy

Catail reads consent through Shopify's Customer Privacy API. You do not install a separate Catail consent banner on production Shopify themes.

  1. Shopify admin → Settings → Customer privacy.
  2. Turn on the customer privacy banner for your regions.
  3. Ensure shoppers can accept or decline analytics with equally prominent choices.
  4. Save.

2. Enable the theme app embed

This is the recommended installation method. The tracker is managed by Shopify and removed automatically when the app is uninstalled — no code left in your theme files.

  1. Shopify admin → Online Store → Themes.
  2. Next to your live theme, click Customize.
  3. In the left panel, open App embeds (the puzzle-piece icon).
  4. Find Catail Analytics in the list and toggle it on.
  5. Click Save in the top-right corner.

Optional: add the Product page block

Add the Catail Product page block when you want Catail-approved product page variants to render on your live product template. The block keeps a manual fallback layout, so your product page remains usable even when no test is running.

  1. Shopify admin → Online Store → Themes → Customize.
  2. Open a product template.
  3. Add the Catail Product page / PDP Container app block to the template.
  4. Choose the fallback layout you want shoppers to see when no test is active.
  5. Save and preview a product page before publishing theme changes.

Verify the embed

Alternative (headless storefronts): open Catail merchant console → your project → Counter → Legacy: manual theme snippet, copy the production snippet (includes your counter_id), and paste it immediately before </body> in layout/theme.liquid.

  1. Open your storefront in a private/incognito window.
  2. Accept analytics in Shopify's privacy banner.
  3. Browse one or two pages.
  4. In the Catail admin app or Counter, confirm Tracker live or Receiving events = Yes.

3. Web Pixel and privacy settings

The Web Pixel runs in Shopify's sandbox. Configure Customer privacy on the Catail app before checkout events will flow.

Privacy settings (required)

  1. Shopify admin → Settings → Apps and sales channels.
  2. Open framework (Catail) → Customer privacy.
  3. Permission: select Required.
  4. Purposes: check Analytics only. Leave Marketing and Preferences unchecked.
  5. Data sale: select Data collected does not qualify as data sale.
  6. Save.

Install the pixel code

  1. In the app settings, open the Web Pixel / custom code area (or Settings → Customer events → Custom pixels).
  2. In Catail Counter, expand 3. Commerce funnel — Web Pixel + order webhook.
  3. Copy the Web Pixel snippet and paste it into Shopify.
  4. Save.

Verify pixel

  1. Add a product to cart and start checkout (payment not required).
  2. In Catail Counter, check Last pixel event — it should show a recent timestamp.

4. Register the order webhook

Shop Pay and some accelerated checkouts may not fire checkout_completed on the thank-you page. The webhook records purchases reliably.

The webhook reads catail_session_key from order note attributes — written automatically by the theme tracker when shoppers add to cart.

  1. In Catail Counter, complete theme + Web Pixel steps first.
  2. Click Connect Shopify app (OAuth) in the Commerce funnel section.
  3. Confirm status shows orders/create webhook active.
  4. Do not use Shopify admin Settings → Notifications → Webhooks (legacy; blocked for new custom apps in 2026).

Dev and test stores only

Do not use the Dev / test install (footer loader) on production shopper themes. Production stores must use the theme app embed (or manual snippet if headless) + Shopify Customer Privacy.

Troubleshooting

SymptomCheck
No tracker eventsTheme app embed toggled on in Theme Editor and saved; Customer Privacy enabled; shopper accepted analytics
Consent mode shows DevRemove footer dev loader; use production theme app embed only
No pixel eventsWeb Pixel privacy: Required + Analytics; theme tracker installed; complete a cart/checkout step
Purchases missing in funnelRegister orders/create webhook; confirm catail_session_key on order
Product page variants not changingConfirm the Product page block is added to the published product template and the variants are approved in Catail
Update required on snippetIf using legacy manual snippet: re-copy the latest from Counter after a platform update
Theme embed not activatingEnsure the theme is published and the App embed is toggled on — not just saved in a draft customization

Privacy summary

Analytics consent controls behavior measurement. Catail does not set tracking cookies for analytics; Tier 2 cookies are managed by Shopify Customer Privacy.

For legal and DPA details, see Terms of service and your merchant console legal pages.