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:

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.

Both 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.

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 and phone on the completed-order event, which Shopify permits for merchant-pasted custom pixels without any review process.

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 — Theme snippet for identity join (optional)

This step 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 — attribution still works without it, matching by email — but it's the highest-quality signal available on Shopify, so 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.

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.
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