> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Complete setup guide for Shopify brands

> Install Upstack Data on Shopify end to end: connect the app, enable the theme extension or custom pixel, set consent preferences, and configure multi-domain, multi-store, and custom-page (Replo) tracking.

This guide covers everything you need to set up Upstack Data tracking on your Shopify store — from connecting the app through advanced configurations for custom pages and multi-store brands.

## Prerequisites

* **Active Shopify store** with admin access
* **Facebook Business Manager account** with an active Ads account
* **Meta Pixel** already created (if not, you can create one during Upstack setup)

## Part 1: Connect Upstack Data and enable tracking

### Step 1: Connect the app

Connect Shopify from inside the Upstack dashboard — not from the Shopify App Store:

1. Sign in to your [Upstack Data dashboard](https://app.upstackdata.com/).
2. Open **Data Sources → Shopify**, then authorize the install in your Shopify Admin.

For a detailed walkthrough, see [How to download and install the Upstack Data app in Shopify](/guides/shopify/how-to-download-and-install-upstack-data-app-in-shopify).

**What permissions does Upstack Data need?** We need access to your Shopify customer events (purchases, add-to-cart, page views) to send accurate data to Meta. We don't store any customer data — we only forward events to your destinations.

### Step 2: Enable the Theme App Extension

After connecting, enable the Theme App Extension — this is required for tracking to work:

1. In the Upstack Data app, look for the **Theme App Extension** section.
2. Click **Enable Theme App Extension** (or **Activate on theme**).
3. Select your active Shopify theme and click **Confirm**.

**What does the Theme App Extension do?** It adds the Upstack tracking code to your store's theme without modifying the code directly, so theme updates won't break your tracking. If you have multiple themes, repeat this for each one you want to track. See [How to ensure the theme app extension is enabled](/guides/shopify/how-to-ensure-upstack-data-theme-app-extension-is-enabled).

### Step 3: Add a Custom Pixel (alternative method)

If the Theme App Extension doesn't work for your setup (rare), you can install a Custom Pixel instead:

1. Go to your **Shopify Admin → Settings → Customer events**.
2. Click **Add custom pixel** and select **Upstack Data**.
3. Click **Add pixel** and follow the setup prompts in the Upstack Data app.

Custom Pixels work the same way as Theme App Extensions but are managed separately. Use one or the other, not both.

### Step 4: Set consent and privacy settings

Before your pixel starts firing, configure your consent and privacy preferences:

1. In the Upstack Data app, go to **Settings** or **Configuration** and look for **Consent** or **Privacy** options.
2. Choose your consent preferences:
   * **Functional** — required for core tracking (recommended)
   * **Marketing** — for ad optimization and retargeting
   * **Analytics** — for audience insights
3. Save your settings.

Full walkthrough: [How to set up custom pixel privacy settings](/guides/shopify/how-to-setup-upstack-custom-pixel-privacy-settings).

**Does Upstack Data respect user consent?** Yes. We honor your Shopify consent banner and Meta Conversions API consent settings. We only send data that your customers have consented to share.

### Basic setup complete

At this point your Upstack Data pixel should be:

* ✓ Installed on your Shopify store
* ✓ Firing page views, add-to-cart, and purchase events
* ✓ Respecting user consent
* ✓ Sending data to your destinations

## Part 2: Multi-domain and multi-store configuration

### Single domain (most common)

If your store uses one domain (e.g., `mystore.shopify.com` or `www.mystore.com`), the setup above is complete — your pixel is automatically configured for your primary domain.

### Subdomains (www vs. non-www)

If you use multiple versions of your domain (`mystore.com` AND `www.mystore.com`):

1. In Shopify, go to **Settings → Domains** and verify all your primary and secondary domains are listed.
2. In the Upstack Data app, check if there's a **Domain Configuration** section.
3. If your subdomains aren't tracking, you may need to hard-code the pixel script (see [Part 3](#part-3-custom-page-and-replo-setup)).

**Best practice:** use a redirect to consolidate to one primary domain (e.g., `mystore.com` → `www.mystore.com`). This ensures all traffic hits the same domain and tracking is consistent.

### Alias domains or secondary domains

If you have a secondary or alias domain (e.g., `mystore.com` is primary, `mystorealias.com` is an alias):

1. **Option A (recommended):** hard-code the pixel on the alias domain manually (see [Part 3](#part-3-custom-page-and-replo-setup)).
2. **Option B:** ask Upstack support to configure server-side pixel tracking for your alias domain.
3. **Verify:** use Pixel Helper on both domains to confirm events are firing.

Server-side tracking ensures Click ID is preserved even when users are redirected between domains. See [Set up Upstack Data on a landing page or subdomain](/resources/how-to-set-up-upstack-data-on-a-landing-page-or-subdomain).

### Multi-store brands (multiple Shopify stores)

Each store needs its own Upstack setup:

1. **Store 1:** connect Upstack Data and complete setup (as above).
2. **Store 2:** repeat the process — see [Using Upstack Data on multiple stores](/troubleshooting/multiple-stores-and-pricing).
3. **Each store should have its own Meta Pixel ID** (or use one pixel for all stores if intentional).
4. **Verify in Meta Events Manager** that events from each domain arrive correctly.

## Part 3: Custom page and Replo setup

### Understanding custom pages

Shopify's native pages include product pages, cart, checkout, and collection pages. Many brands also use builders like **Replo** for landing pages, thank-you pages, or custom storefronts. Pages built outside Shopify (even if hosted on your domain) won't automatically include the Upstack Data pixel — you'll need to hard-code the tracking script.

### Hard-code the pixel on Replo pages (or other custom pages)

**Step 1: Get your Meta Pixel ID**

1. In the Upstack Data app, find your **Meta Pixel ID** (usually visible on the dashboard).
2. Copy this ID.

**Step 2: Add the pixel script to your custom page**

In Replo (or your custom page builder), find the **Head Code** or **Custom Code** section:

1. Go to your **Replo Editor → Settings → Head Code** (or **Custom Code**).
2. Paste the pixel script, replacing `YOUR_PIXEL_ID` with your actual Meta Pixel ID:

```html theme={null}
<!-- Upstack Data Pixel -->
<script async src="https://connect.facebook.net/en_US/fbevents.js"></script>
<script async>
  fbq('init', 'YOUR_PIXEL_ID');
  fbq('track', 'PageView');
</script>
<noscript>
  <img height="1" width="1" style="display:none"
    src="https://www.facebook.com/tr?id=YOUR_PIXEL_ID&ev=PageView&noscript=1" />
</noscript>
```

**Step 3: Use async instead of defer**

**Critical:** always use `async` loading, NOT `defer`. If you use `defer` and users bounce within 2–3 seconds, the pixel won't fire.

```html theme={null}
<!-- ✓ Correct -->
<script async src="..."></script>
<!-- ✗ Wrong -->
<script defer src="..."></script>
```

**Step 4: Verify Click ID preservation**

If you're using Replo for checkout pages:

1. In Replo settings, find **Redirect** or **Checkout Integration**.
2. Ensure the `fbclid` parameter is passed along in the redirect URL.
3. Test with Pixel Helper to confirm Click ID appears in the pixel event.

**What is Click ID?** It's Meta's way of tracking which ad led to a conversion. If Click ID is lost during a redirect, Meta can't attribute the purchase to your ad, and your ROAS will be inaccurate. See also [Implementing Upstack Data on landing pages](/resources/implementing-upstack-data-on-landing-pages).

### Verify custom page tracking

1. Open Pixel Helper and visit your custom page (Replo landing page, thank-you page, etc.).
2. Confirm that a **PageView** event fires.
3. Check that **Click ID** is present in the event details.
4. Add an item to cart or make a purchase (if applicable) and confirm **AddToCart** or **Purchase** events fire with correct values.

## Part 4: Handling common setup issues

### Issue: app onboarding not working (pre-authenticated store)

If you installed Upstack Data before and are setting it up again, the app may not show the login form.

**Fix:** in the Upstack Data app settings, enable **"Always Show Login Form"**, then log out and back in — the full setup flow should now appear.

### Issue: events not firing after installation

**Check these in order:**

1. **Theme App Extension enabled?** Go to **Settings → Customer events** and confirm Upstack Data is active.
2. **Custom Pixel installed?** If using a Custom Pixel instead of the Theme Extension, confirm it's added.
3. **Is your theme compatible?** Older custom themes may not support Theme App Extensions — contact Upstack support.
4. **Is JavaScript enabled in your browser?** Some privacy extensions block scripts.

For deeper diagnosis, see [How to troubleshoot your pixel](/troubleshooting/troubleshoot-pixel-issues).

### Issue: conversion value is wrong

**Most common cause:** your products are bundled or discounted, but your pixel fires with the pre-discount price.

**Example:** a $150 bundle is discounted to $80, but your pixel fires with value: \$150.

**Fix:** in your bundle/discount app settings (Kaching, Bold, Recharge, etc.), configure it to send **zero-dollar values** for bundled items — or ensure the pixel fires **after** the discount is applied. Test in Pixel Helper to confirm the correct (discounted) value fires.

### Issue: multiple pixels firing (duplicate tracking)

If Pixel Helper shows the same event twice, you have duplicate tracking:

1. **GTM installed?** Check if GTM is also firing the Meta pixel.
2. **Stape or Triple Whale?** These data layer tools may fire duplicate events.
3. **Two custom pixels installed?** Go to **Settings → Customer events** and verify only one Upstack pixel is active.

**Fix:** disable the duplicate source or coordinate with your analytics team about which tool is primary.

## Part 5: Verify your setup is complete

After installation, confirm these events are tracking:

* **Page View** — every time someone visits a page
* **Add to Cart** — when someone adds a product to their cart
* **Purchase** — when someone completes a purchase, with correct value

### Quick verification checklist

* [ ] Theme App Extension is enabled (or Custom Pixel is added)
* [ ] Pixel Helper shows events firing on your store
* [ ] Event values match your product prices (post-discount)
* [ ] Click ID is present in event details
* [ ] Meta Events Manager shows events arriving in real time
* [ ] Custom pages (Replo, etc.) have the pixel hard-coded with `async` loading
* [ ] No duplicate events in Pixel Helper

**All checks passing?** Great! Your Upstack Data setup is complete and tracking correctly. For a full verification walkthrough, see [Verify your Shopify pixel](/troubleshooting/verify-your-shopify-pixel).

## When to contact Upstack support

Reach out if you encounter:

* Theme App Extension won't enable
* Custom Pixel won't install
* Events fire in Pixel Helper but not in Meta Events Manager
* Setup flow doesn't appear after app installation
* Multi-domain or multi-store specific issues
* Custom page integrations (Replo, Kaching, etc.) aren't tracking
* Conversion values are consistently incorrect

**Include with your request:**

* Screenshot of your Shopify theme settings
* Screenshot of Pixel Helper (with events visible)
* Your store domain(s)
* Description of what you're trying to set up

***

**Still stuck?** Contact [support@upstackdata.com](mailto:support@upstackdata.com) with your Pixel ID and a description of the issue. We typically respond within a few hours.

## Summary: setup path for different scenarios

**For a standard Shopify store (most common):** connect the app → enable Theme App Extension → set consent/privacy settings → verify with Pixel Helper → done!

**For multiple domains (www vs. non-www):** follow standard setup, hard-code the pixel on any subdomains that aren't tracking, and verify on each domain with Pixel Helper.

**For custom pages (Replo, Kaching, etc.):** follow standard setup, hard-code the pixel script on custom pages with `async` loading, verify Click ID, and test each page with Pixel Helper.

**For multiple Shopify stores:** repeat standard setup on each store, give each store its own Meta Pixel ID, and verify in Meta Events Manager that events from each store arrive separately.

Most brands complete setup in under 15 minutes. Custom page configurations may take an additional 10–15 minutes depending on complexity.