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

# Shopify Automatic Event Tracking

> How Upstack Data automatically captures all customer journey events from your Shopify store — page views, add to cart, checkout, and purchases with no config.

Once the Upstack app is installed, its theme app extension is enabled, and the Upstack custom pixel is added under **Settings → Customer events**, Upstack captures customer journey events on your Shopify store automatically — no event code required. This document explains what events are tracked and when they fire.

> [!TIP]
>
> Both pieces are required: the theme app extension (**Online Store → Themes → Customize → App embeds → Upstack Data**) and the Upstack custom pixel. See [Install on Shopify](https://docs.upstackdata.com/quickstart/install-on-shopify.md).

## Tracking Methods

Upstack captures events through two complementary methods:

### Customer Events API (custom pixel)

Shopify's official [Customer Events API](https://shopify.dev/docs/api/customer-events) provides real-time cart and checkout events through the Upstack custom pixel. This is the most reliable method for conversion tracking and captures:

* Checkout started, progressed, and completed
* Payment information entered
* Shipping information entered
* Cart views, items added to and removed from the cart, and searches

### URL-Based Detection (theme app extension)

For storefront browsing, the theme app extension detects product and collection pages by URL pattern:

| URL Pattern | Event Fired |
| - | - |
| `/products/*` | `view_content` |
| `/collections/*` | `view_category` |

No configuration required — events fire automatically when visitors browse these pages.

***

## Event Mapping

The following table shows all automatically captured events:

| Customer Action | Upstack Event | Data Captured |
| - | - | - |
| Views any page | `page_view` | URL, title, referrer |
| Views a product page | `view_content` | Product ID, name, price, variant, URL |
| Views a collection | `view_category` | Collection ID and name |
| Searches the store | `search` | Search query |
| Views their cart | `view_cart` | All cart items, cart value, currency |
| Adds item to cart | `add_to_cart` | Product ID, name, price, quantity, variant |
| Removes item from cart | `product_removed_from_cart` | Product ID, quantity removed |
| Starts checkout | `initiate_checkout` | Cart items, value, currency |
| Enters contact info | `add_shipping_info` | Cart items, value, currency (+ triggers identity capture) |
| Enters shipping address | `add_shipping_info` | Cart items, value, addresses (+ triggers identity capture) |
| Selects shipping method | `add_shipping_info` | Cart items, value, currency |
| Enters payment info | `add_payment_info` | Payment method type (no card data) |
| Completes order | `purchase` | Full order: items, value, tax, shipping, customer |

### Which events reach Upstack even without the pixel?

Purchases are captured server-side, directly from Shopify, even without the pixel. Orders, cancellations, refunds, and new customers also reach Upstack directly from Shopify.

***

## Data Payloads

> [!NOTE]
>
> The JSON examples below show **destination wire format** — what Meta CAPI, TikTok, and other destinations receive after Upstack transforms the event. Event names are converted to PascalCase (e.g., `AddToCart`) for destination compatibility. When using the SDK directly, always use **snake\_case** (e.g., `add_to_cart`).

### Product View (`view_content`)

Automatically captured when a visitor views any `/products/*` page:

```json theme={null}
// Destination wire format (what Meta CAPI receives)
{
  "event_name": "ViewContent",
  "event_time": "2026-02-18T14:31:12.000Z",
  "event_source_url": "https://example-store.com/products/classic-tee",
  "user_data": {
    "client_ip_address": "203.0.113.42",
    "client_user_agent": "Mozilla/5.0...",
    "fbp": "fb.1.1708271400.XyZ789"
  },
  "custom_data": {
    "content_ids": ["8012345678"],
    "content_type": "product",
    "content_name": "Classic Cotton Tee",
    "value": 34.99,
    "currency": "USD"
  }
}
```

### Add to Cart (`add_to_cart`)

Captured when a visitor adds an item to their cart:

```json theme={null}
// Destination wire format (what Meta CAPI receives)
{
  "event_name": "AddToCart",
  "event_time": "2026-02-18T14:32:05.000Z",
  "event_source_url": "https://example-store.com/products/classic-tee",
  "user_data": {
    "client_ip_address": "203.0.113.42",
    "client_user_agent": "Mozilla/5.0...",
    "fbp": "fb.1.1708271400.XyZ789"
  },
  "custom_data": {
    "content_ids": ["8012345678"],
    "content_type": "product",
    "content_name": "Classic Cotton Tee",
    "value": 34.99,
    "currency": "USD",
    "num_items": 1
  }
}
```

### Checkout Started (`initiate_checkout`)

Captured when checkout begins:

```json theme={null}
// Destination wire format (what Meta CAPI receives)
{
  "event_name": "InitiateCheckout",
  "event_time": "2026-02-18T14:33:45.000Z",
  "event_source_url": "https://example-store.com/checkout",
  "user_data": {
    "client_ip_address": "203.0.113.42",
    "client_user_agent": "Mozilla/5.0...",
    "fbc": "fb.1.1708271400.AbC123",
    "fbp": "fb.1.1708271400.XyZ789"
  },
  "custom_data": {
    "content_ids": ["8012345678", "8012345679"],
    "content_type": "product",
    "value": 89.98,
    "currency": "USD",
    "num_items": 2
  }
}
```

### Purchase (`purchase`)

Captured when an order is completed:

```json theme={null}
// Destination wire format (what Meta CAPI receives)
{
  "event_name": "Purchase",
  "event_time": "2026-02-18T14:35:20.000Z",
  "event_source_url": "https://example-store.com/thank-you",
  "user_data": {
    "em": "a1b2c3d4e5f6...hashed",
    "ph": "f6e5d4c3b2a1...hashed",
    "client_ip_address": "203.0.113.42",
    "client_user_agent": "Mozilla/5.0...",
    "fbc": "fb.1.1708271400.AbC123",
    "fbp": "fb.1.1708271400.XyZ789",
    "external_id": "cust_12345"
  },
  "custom_data": {
    "content_ids": ["8012345678", "8012345679"],
    "content_type": "product",
    "value": 89.98,
    "currency": "USD",
    "order_id": "#1042",
    "num_items": 2
  }
}
```

***

## Identity Capture

When customers enter contact information during checkout, Upstack automatically:

1. **Captures email and phone** from the contact info step
2. **Associates the session** with the customer identity
3. **Persists identity** for cross-session attribution

This happens when customers enter contact or address information during checkout. No additional configuration is required.

> [!NOTE]
>
> Identity data enables cross-device attribution and improves match quality with ad platforms like Meta and TikTok.

***

## Consent Handling

See [How to Configure Consent Mode](https://docs.upstackdata.com/guides/privacy/how-to-configure-consent-mode.md).

***

## What's NOT Automatically Tracked

The following events require manual implementation:

| Event | Why Not Automatic | How to Track |
| - | - | - |
| Product list views | No standard Shopify event | Call `_upstack('track', 'view_item_list', {...})` |
| Newsletter signups | Form depends on theme | Use [Form Capture Integrations](https://docs.upstackdata.com/guides/integrations/form-capture-integrations.md) or manual tracking |
| Wishlist actions | Third-party apps vary | Call `_upstack('track', 'add_to_wishlist', {...})` |
| Custom conversions | Business-specific | Define and track [custom events](https://docs.upstackdata.com/guides/custom-events/how-to-create-custom-event-triggers.md) |

## Related Documentation

> [card] [Standard Events](https://docs.upstackdata.com/event-tracking/event-taxonomy/standard-events)
>
> Full reference with JavaScript snippets for manual event tracking.

> [card] [JavaScript SDK](https://docs.upstackdata.com/pixel/javascript-sdk.md)
>
> Complete API reference for the Upstack JavaScript SDK.

> [card] [Properties & Context](https://docs.upstackdata.com/event-tracking/event-taxonomy)
>
> Reference for item arrays, customer data, and auto-captured fields.

> [card] [Custom Events](https://docs.upstackdata.com/guides/custom-events/how-to-create-custom-event-triggers.md)
>
> Track custom interactions beyond the standard taxonomy.

> [card] [Form Capture Integrations](https://docs.upstackdata.com/guides/integrations/form-capture-integrations.md)
>
> Automatic lead capture from Klaviyo, Postscript, and more.

> [card] [Connect Shopify](https://docs.upstackdata.com/sources/catalog/shopify.md)
>
> Initial setup guide for connecting your Shopify store.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.