> For the complete documentation index, see [llms.txt](https://the-wishlist-documentation.gitbook.io/the-wishlist-documentation-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://the-wishlist-documentation.gitbook.io/the-wishlist-documentation-docs/developer-reference/customer-events-pixel.md).

# Shopify Customer Events Pixel

This guide explains how to install The Wishlist Company custom pixel in Shopify.

The pixel captures selected Shopify customer events and sends them to The Wishlist Company so browsing, collection, and add-to-cart activity can be used inside the platform.

***

## Events captured

| Shopify event           | Purpose                            |
| ----------------------- | ---------------------------------- |
| `product_viewed`        | Captures product detail page views |
| `collection_viewed`     | Captures collection page views     |
| `product_added_to_cart` | Captures add-to-cart activity      |

***

## Before you begin

You will need:

| Requirement                           | Notes                                                                                                                     |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Shopify Admin access                  | You must be able to access **Settings → Customer events** in Shopify Admin.                                               |
| The Wishlist Company tenant connected | The Shopify store domain must be mapped to the correct tenant in The Wishlist Company platform.                           |
| Approved customer privacy settings    | Confirm the merchant’s required consent, analytics, preferences, and data-sale configuration before connecting the pixel. |
| Event collection endpoint             | The Wishlist Company will provide the correct production event collection endpoint.                                       |

> The merchant is responsible for confirming that the customer privacy settings match their legal jurisdictions, consent model, and privacy policy.

***

## Installation steps

### 1. Open Customer Events in Shopify

In Shopify Admin, go to:

```
Settings → Customer events
```

***

### 2. Add a custom pixel

1. Open the **Custom pixels** tab.
2. Select **Add custom pixel**.
3. Name the pixel:

```
The Wishlist Company Customer Events
```

4. Click **Add pixel**.

***

### 3. Configure customer privacy settings

In the pixel’s **Customer privacy** section, configure the permission and data-sale settings according to the merchant’s privacy and consent requirements.

| Setting    | Recommended handling                                        |
| ---------- | ----------------------------------------------------------- |
| Permission | Set according to the merchant’s consent and privacy policy. |
| Data sale  | Set according to the merchant’s legal and privacy position. |

> These are not purely technical settings. The merchant should confirm the correct configuration with their privacy, compliance, or legal owner before connecting the pixel.

***

### 4. Paste the pixel code

Paste the approved production pixel code into the Shopify code editor.

Replace the value of `ENDPOINT` with the event collection endpoint supplied by The Wishlist Company.

```javascript
const ENDPOINT = '{{EVENT_COLLECTION_ENDPOINT}}';

const getShopifyDomain = () => {
  return init?.data?.shop?.myshopifyDomain || null;
};

const getCustomerId = () => {
  return init?.data?.customer?.id || null;
};

const buildBaseEventData = (event) => ({
  clientId: event.clientId,
  eventId: event.id,
  eventSeq: event.seq,
  customerId: getCustomerId(),
  eventTime: event.timestamp,
  shopifyDomain: getShopifyDomain()
});

const sendEvent = (eventType, eventData) => {
  const payload = {
    event_name: eventType,
    event_data: eventData
  };

  return fetch(ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload),
    keepalive: true
  }).catch((error) => {
    console.error(`${eventType} fetch error:`, error);
  });
};

const handleShopifyEvent = (event, eventType) => {
  let eventData = buildBaseEventData(event);

  try {
    if (eventType === 'product_viewed') {
      const variant = event.data.productVariant;
      const product = variant.product;

      eventData = {
        ...eventData,
        Product: product.title,
        Variant: variant.title,
        variantRef: variant.id,
        productRef: product.id,
        image: variant.image,
        sku: variant.sku,
        type: product.type,
        url: product.url,
        brand: product.vendor
      };
    }

    if (eventType === 'product_added_to_cart') {
      const merchandise = event.data.cartLine.merchandise;
      const product = merchandise.product;

      eventData = {
        ...eventData,
        Product: product.title,
        Variant: merchandise.title,
        variantRef: merchandise.id,
        productRef: product.id,
        image: merchandise.image,
        sku: merchandise.sku,
        type: product.type,
        url: product.url,
        brand: product.vendor,
        quantity: event.data.cartLine.quantity
      };
    }

    if (eventType === 'collection_viewed') {
      eventData = {
        ...eventData,
        collectionTitle: event.data.collection.title,
        collectionId: event.data.collection.id
      };
    }

    sendEvent(eventType, eventData);
  } catch (error) {
    console.error(`Error processing ${eventType}:`, error);
  }
};

analytics.subscribe('product_viewed', (event) => {
  handleShopifyEvent(event, 'product_viewed');
});

analytics.subscribe('collection_viewed', (event) => {
  handleShopifyEvent(event, 'collection_viewed');
});

analytics.subscribe('product_added_to_cart', (event) => {
  handleShopifyEvent(event, 'product_added_to_cart');
});
```

***

### 5. Save and connect the pixel

1. Click **Save**.
2. Click **Connect pixel**.
3. Confirm the Shopify connection prompt.

The pixel will not start sending events until it has been connected.

***

## Testing

After connecting the pixel:

1. Open the pixel in Shopify Admin.
2. Click **Test**.
3. Visit a product page and confirm that `product_viewed` is triggered.
4. Add a product to cart and confirm that `product_added_to_cart` is triggered.
5. Visit a collection page and confirm that `collection_viewed` is triggered.
6. Confirm that The Wishlist Company receives the events for the correct tenant.

***

## Troubleshooting

| Issue                                                    | Likely cause                                                        | Action                                                                                |
| -------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Pixel does not fire                                      | Pixel is not connected                                              | Confirm the pixel status is **Connected** in Customer events.                         |
| Events do not appear during testing                      | Consent or privacy settings may be blocking execution               | Accept tracking in the cookie banner or review the Shopify customer privacy settings. |
| Events appear in Shopify but not in The Wishlist Company | Endpoint or tenant mapping issue                                    | Confirm the production endpoint and Shopify domain mapping.                           |
| Duplicate events                                         | An older pixel or theme script may still be installed               | Remove any previous Wishlist pixel implementation before enabling the custom pixel.   |
| Add-to-cart event fails                                  | Shopify event payload structure differs from the expected structure | Check the Shopify pixel test output and browser console errors.                       |

***

## Security and data handling notes

The event collection endpoint is designed to receive browser-based pixel events.

Any endpoint included in client-side JavaScript should be treated as public. Do not include private credentials, API keys, secrets, or tokens in the pixel code.

For this reason:

* Do not include API keys, secrets, or private tokens in the pixel code.
* Do not modify the endpoint unless instructed by The Wishlist Company.
* Do not reuse the endpoint for unrelated integrations.
* The Wishlist Company validates incoming events server-side. Events are only accepted for Shopify domains connected to a tenant, and the tenant is always determined by The Wishlist Company from the store domain, never from the event payload. Unknown event types, malformed fields and events from unconnected stores are discarded.
* The Shopify store domain in the event payload must match a connected tenant.

***

## Implementation notes

The pixel sends event data using a `POST` request to the supplied event collection endpoint.

Each request contains:

```json
{
  "event_name": "product_viewed",
  "event_data": {
    "clientId": "example-client-id",
    "eventId": "example-event-id",
    "eventSeq": 1,
    "customerId": "gid://shopify/Customer/123456789",
    "eventTime": "2026-03-24T00:00:00.000Z",
    "shopifyDomain": "example-store.myshopify.com",
    "Product": "Example Product",
    "Variant": "Default Title",
    "variantRef": "gid://shopify/ProductVariant/123456789",
    "productRef": "gid://shopify/Product/123456789",
    "image": {
      "src": "https://cdn.shopify.com/example-image.jpg"
    },
    "sku": "EXAMPLE-SKU",
    "type": "Example Type",
    "url": "/products/example-product",
    "brand": "Example Brand"
  }
}
```

The exact payload fields vary by event type.

***

## Support

For assistance, contact The Wishlist Company implementation team.

Please include:

* Shopify store domain
* Pixel name
* Event being tested
* Screenshot of any Shopify pixel test errors
* Approximate time the test was performed