Shopify Automatic Event Tracking

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.

Both pieces are required: the theme app extension (Online Store → Themes → Customize → App embeds → Upstackified) and the Upstack custom pixel. See Install on Shopify.

Tracking Methods

Upstack captures events through two complementary methods:

Customer Events API (custom pixel)

Shopify’s official Customer Events API 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 handle, URL
Searches the store	`search`	Search query, results count
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`	Email, phone (+ triggers identity capture)
Enters shipping address	`add_shipping_info`	Address fields (+ triggers identity capture)
Selects shipping method	`add_shipping_info`	Shipping tier selection
Enters payment info	`add_payment_info`	Payment method type (no card data)
Completes order	`purchase`	Full order: items, value, tax, shipping, customer

Data Payloads

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:

// 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:

// 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:

// 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:

// 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:

Captures email and phone from the contact info step
Associates the session with the customer identity
Persists identity for cross-session attribution

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

Identity data enables cross-device attribution and improves match quality with ad platforms like Meta and TikTok.

Upstack respects Shopify’s customer consent settings:

If analytics consent is not granted, tracking is limited to essential events
Marketing consent affects which destinations receive forwarded events
Consent state is captured and included with each event

{
  "consent": {
    "analytics": true,
    "marketing": false,
    "preferences": true
  }
}

The Permission option on the Upstack Custom Pixel decides whether the pixel waits for this consent before it loads. See How to set up custom pixel privacy settings for the recommended Permission and Data sale settings.

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 or manual tracking
Wishlist actions	Third-party apps vary	Call `_upstack('track', 'add_to_wishlist', {...})`
Custom conversions	Business-specific	Define and track custom events

Standard Events

Full reference with JavaScript snippets for manual event tracking.

JavaScript SDK

Complete API reference for the Upstack JavaScript SDK.

Properties & Context

Reference for item arrays, customer data, and auto-captured fields.

Custom Events

Track custom interactions beyond the standard taxonomy.

Form Capture Integrations

Automatic lead capture from Klaviyo, Postscript, and more.

Connect Shopify

Initial setup guide for connecting your Shopify store.

SDK

IDENTITY

AUTOMATIC TRACKING

Shopify Automatic Event Tracking

Tracking Methods

Customer Events API (custom pixel)

URL-Based Detection (theme app extension)

Event Mapping

Data Payloads

Product View (`view_content`)

Add to Cart (`add_to_cart`)

Checkout Started (`initiate_checkout`)

Purchase (`purchase`)

Identity Capture

What’s NOT Automatically Tracked

Standard Events

JavaScript SDK

Properties & Context

Custom Events

Form Capture Integrations

Connect Shopify

​Tracking Methods

​Customer Events API (custom pixel)

​URL-Based Detection (theme app extension)

​Event Mapping

​Data Payloads

​Product View (view_content)

​Add to Cart (add_to_cart)

​Checkout Started (initiate_checkout)

​Purchase (purchase)

​Identity Capture

​Consent Handling

​What’s NOT Automatically Tracked

​Related Documentation

Standard Events

JavaScript SDK

Properties & Context

Custom Events

Form Capture Integrations

Connect Shopify

Tracking Methods

Customer Events API (custom pixel)

URL-Based Detection (theme app extension)

Event Mapping

Data Payloads

Product View (`view_content`)

Add to Cart (`add_to_cart`)

Checkout Started (`initiate_checkout`)

Purchase (`purchase`)

Identity Capture

Consent Handling

What’s NOT Automatically Tracked

Related Documentation