Skip to main content
When you install Upstack on your Shopify store, we automatically capture customer journey events without any additional configuration. This document explains what events are tracked and when they fire.
No manual setup required — all standard e-commerce events are captured automatically once the Upstack app is installed.

​
Tracking Methods

Upstack captures events through two complementary methods:

​
Customer Events API (Checkout)

Shopify’s official Customer Events API provides real-time checkout events. This is the most reliable method for conversion tracking and captures:
  • Checkout started, progressed, and completed
  • Payment information entered
  • Shipping information entered
  • Cart interactions during checkout

​
URL-Based Detection (Storefront)

For storefront browsing, Upstack automatically detects page types based on URL patterns:
URL PatternEvent Fired
/products/*view_content
/collections/*view_category
/cartview_cart
/search?*search
No configuration required — events fire automatically when visitors browse these pages.

​
Event Mapping

The following table shows all automatically captured events:
Customer ActionUpstack EventData Captured
Views any pagepage_viewURL, title, referrer
Views a product pageview_contentProduct ID, name, price, variant, URL
Views a collectionview_categoryCollection handle, URL
Searches the storesearchSearch query, results count
Views their cartview_cartAll cart items, cart value, currency
Adds item to cartadd_to_cartProduct ID, name, price, quantity, variant
Removes item from cartproduct_removed_from_cartProduct ID, quantity removed
Starts checkoutinitiate_checkoutCart items, value, currency
Enters contact infoadd_shipping_infoEmail, phone (+ triggers identity capture)
Enters shipping addressadd_shipping_infoAddress fields (+ triggers identity capture)
Selects shipping methodadd_shipping_infoShipping tier selection
Enters payment infoadd_payment_infoPayment method type (no card data)
Completes orderpurchaseFull 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:
  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.
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
  }
}

​
What’s NOT Automatically Tracked

The following events require manual implementation:
EventWhy Not AutomaticHow to Track
Product list viewsNo standard Shopify eventCall _upstack('track', 'view_item_list', {...})
Newsletter signupsForm depends on themeUse Form Capture Integrations or manual tracking
Wishlist actionsThird-party apps varyCall _upstack('track', 'add_to_wishlist', {...})
Custom conversionsBusiness-specificDefine 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.