Installing on Shopify

Shopify checkout runs in a locked-down sandbox that the standard Prism snippet can't execute in, so Shopify uses two purpose-built pieces instead of the regular snippet install, plus an optional theme script for storefront pages:

1. A custom pixel — a small script pasted into Shopify's customer-events settings — for full-funnel browser tracking, including every checkout step and the completed order.
2. A custom app — a per-store API connection — for reliable order and abandoned-checkout data straight from Shopify's servers, which keeps working even when a visitor's browser blocks the pixel entirely.

All are self-serve: no Shopify app review, no waiting period. Budget 10–15 minutes. Everything below can be done with standard staff/collaborator access except enabling custom app development, which only the store owner can do the first time — flag that to them ahead of time if that's not you.

Step 1 — Add the custom pixel

Your Prism setup page in the Adsidian dashboard shows a pixel script generated for your store, with a copy button.

1. In Shopify admin, go to Settings → Customer events → Add custom pixel.
2. Name it "Adsidian Prism".
3. Paste the code from your Prism setup.
4. Set permission categories to Analytics and Marketing.
5. Click Connect.

The code you paste is a small loader. It fetches the pixel itself from your tracking host on every page load, so improvements Prism ships reach your store automatically with no re-paste. If you installed Prism's custom pixel before October 2026, you pasted the full pixel rather than the loader; re-paste once from your Prism setup to switch over.

"Pixel will not track any customer behavior" is expected

After you paste the loader, Shopify's pixel editor may show "Pixel will not track any customer behavior because it is not subscribed to any events." That message comes from a static scan of the pasted text for a literal analytics.subscribe( call. The loader subscribes through a stored reference (sb.analytics.subscribe), which the scan doesn't recognise. Events are subscribed and delivered normally — confirm in your Prism Live Events view rather than trusting the editor's warning.

Under the pixel's Data sale setting, choose Does not qualify as data sale if your policy treats Prism as a first-party service provider (see Privacy & consent on Shopify). With the default setting, Shopify blocks the pixel entirely for visitors who have opted out in a US opt-out region or who send Global Privacy Control, so Prism never sees the session and can't record the denial against it. With the setting changed, the pixel still loads, reads the opt-out from customerPrivacy, and sends the session with ad consent denied — so a later order can be linked back to that denial and withheld from ad platforms.

This alone lights up the full browser-side funnel: page views, product views, search, cart activity, every checkout step, and the completed order — including the customer's email, phone, name, and city/state/zip/country (hashed in the browser before they leave the page) on the checkout and completed-order events, which Shopify permits for merchant-pasted custom pixels without any review process. The pixel also carries Meta's _fbp browser identifier on every event, so Event Match Quality doesn't depend on a Meta pixel being installed.

Step 2 — Create a custom app for order sync

The pixel gives you the browser-side funnel; the custom app gives you the server-side truth — order and abandoned-checkout data straight from Shopify, unaffected by ad blockers or a closed tab. This is what makes purchase tracking and abandoned-cart data reliable rather than best-effort.

1. Settings → Apps and sales channels → Develop apps.
2. If this is the first custom app on the store, click Allow custom app development — this step requires the store owner.
3. Create an app, name it "Adsidian Prism".
4. Under Configure Admin API scopes, enable:
   • read_orders
   • read_checkouts
   • read_products
5. Install the app.
6. Shopify shows the Admin API access token once — copy it now. Also copy the API secret key from the app's API credentials.
7. Paste both into your Prism setup.

Once saved, Prism registers the order and checkout webhooks on your store automatically — there's nothing to configure in Shopify's webhook settings.

Step 3 — Add prism.js to the theme (optional)

The custom pixel covers checkout and purchase events. Loading prism.js from the theme as well is supported and common: it adds storefront browsing coverage and lead form capture on pages outside checkout (contact forms, newsletter and quote forms). Use both together; the pixel handles checkout and the theme script handles the rest of the storefront.

Recommended: the consent-aware loader. It loads prism.js only when Shopify's customer privacy API says marketing and sale of data are allowed and Global Privacy Control is off. Copy it from Installing the snippet → Optional stricter install, then:

1. Online Store → Themes, and duplicate your live theme or use its preview.
2. Edit code → theme.liquid, and paste the loader just before </head>.
3. Test in the theme preview before publishing: confirm prism.js does not load before you accept the cookie banner and does load after.

You can instead add the plain script tag from your Prism setup. prism.js honours the same privacy signals itself, but it will then load and set its identity cookie before consent.

Identity join snippet

Separately, this snippet links a visitor's browsing session to the order they eventually place, so a purchase that happens on a different device or after clearing cookies still attributes correctly. It's optional — orders still arrive from the order webhook without it — but it is the link between an order and the browsing session behind it, which is what carries that session's attribution and consent choice onto the order. A purchase that arrives by webhook inherits a browser opt-out when it is linked by cart or checkout token or by Prism's visitor ID (never by email); if any linked cart carries a denial, the order is withheld from ad platforms. It's worth the two minutes if you can edit the theme.

1. Online Store → Themes → Edit code.
2. Open theme.liquid.
3. Paste the snippet from your Prism setup just before </body>.
4. Save.

It writes your visitor's Prism identity into the cart's attributes, which Shopify carries through to the order — so the order webhook arrives already linked to the browsing session that led to it.

Step 4 — Catalog ID format

Skip this step if you're not running Meta catalog or dynamic retargeting ads.

The pixel and your Shopify catalog can format product IDs differently, and a mismatch breaks dynamic retargeting silently — ads simply have no products to show, with no error anywhere. In your Prism setup, choose the ID format that matches the catalog feed your ads actually use:

• shopify_composite — shopify_{country}_{productId}_{variantId}, the format Shopify's own Meta sales channel uses. Correct for most stores that connected Meta via Shopify's app.
• variant_id — a bare Shopify variant ID, used by some manually built catalog feeds.
• product_id — a bare Shopify product ID.

If you're not sure which one applies, check the id field on a product in your Meta catalog (Meta Commerce Manager → Catalog) and match its shape.

Step 5 — Verify

1. Browse a product page on your store and confirm PageView and ViewItem show up in your Prism activity.
2. Add an item to your cart and confirm AddToCart.
3. Place a test order. If your store has a test payment gateway enabled (Settings → Payments → Bogus Gateway, dev/partner stores only), use it to complete a real checkout end to end without charging a card; otherwise use a real low-value order. Confirm Purchase arrives, and that the order shows up from the custom app's webhook shortly after.

Ongoing health — webhook freshness and catalog ID consistency — is checked automatically and surfaced in your Prism setup, so a broken connection doesn't go silent.

Privacy & consent on Shopify

The custom pixel reads Shopify's Customer Privacy API correctly and sends the visitor's choices with every event. Shopify exposes marketingAllowed, analyticsProcessingAllowed, preferencesProcessingAllowed and saleOfDataAllowed to the pixel, and Prism applies them as follows:

• If marketingAllowed or saleOfDataAllowed is false, ad consent is denied. The event is stored first-party and not forwarded to Meta, Google, LinkedIn, Reddit or ChatGPT Ads.
• If the browser sends Global Privacy Control, ad consent is denied the same way. The server also checks the Sec-GPC header on every browser request.
• Denial only: nothing here can grant consent, and when the visitor changes their choice (visitorConsentCollected) a re-grant restores delivery.
• With no signal, the per-client consent_default applies (US default: granted).

When prism.js is also loaded from the theme (Step 3), it reads window.Shopify.customerPrivacy itself and only creates the _fbp cookie when ad consent is not denied. The consent-aware loader in Step 3 additionally keeps it from loading at all before consent.

For the full list of cookies, what form auto-capture reads, data-prism-ignore, retention and deletion, see Privacy & consent. Draft your policy text with Suggested privacy-policy wording.

Re-paste the custom pixel after Prism updates

Shopify stores its own copy of the custom pixel code. When Prism ships an update to the pixel (including privacy changes), your store keeps running the old version until you replace it. After a Prism update, open your Prism setup page, copy the current pixel code, then in Shopify go to Settings → Customer events, open the "Adsidian Prism" pixel, paste over the old code, and save.

Troubleshooting

Symptom	Likely cause / fix
Allow custom app development isn't visible	You're not the store owner. Only the store owner can enable it, once, per store — ask them to click through Step 2.2, then continue from Step 2.3 yourself.
Events aren't arriving for EU/UK visitors	The pixel's permission category is set to something your consent banner doesn't grant by default. Confirm the pixel is set to Analytics and Marketing in Step 1, and that your consent platform is actually granting those categories — see Consent integration.
Pixel editor says "will not track any customer behavior"	Expected with the loader — see the note under Step 1. The editor's static scan doesn't see sb.analytics.subscribe; events still flow.
Checkout-step or purchase events are missing, but product/cart events work fine	The pixel itself is working; check that it's still Connected under Customer events (a theme change or app conflict can occasionally disconnect a pixel) and that permissions weren't changed after the initial setup.
Orders aren't showing up, but browser events (AddToCart, BeginCheckout) are	The custom app step wasn't completed, or the Admin API token/secret pasted into Prism setup doesn't match a currently-installed app. Redo Step 2 — reinstalling the app issues a fresh token.
Dynamic retargeting ads show no products	Catalog ID format mismatch — revisit Step 4 and check the format against an actual product ID in Meta Commerce Manager.

Next

• E-commerce events — what each captured event means
• Cart abandonment — how abandoned checkouts and carts are detected
• Verifying your install