> ## 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.
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](https://shopify.dev/docs/api/customer-events) 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 Pattern | Event Fired |
| ---------------- | --------------- |
| `/products/*` | `view_content` |
| `/collections/*` | `view_category` |
| `/cart` | `view_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 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:
```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.
Identity data enables cross-device attribution and improves match quality with ad platforms like Meta and TikTok.
***
## Consent Handling
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
```json theme={null}
{
"consent": {
"analytics": true,
"marketing": false,
"preferences": true
}
}
```
***
## 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](/guides/integrations/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](/pixel/custom-events) |
## Related Documentation
Full reference with JavaScript snippets for manual event tracking.
Complete API reference for the Upstack JavaScript SDK.
Reference for item arrays, customer data, and auto-captured fields.
Track custom interactions beyond the standard taxonomy.
Automatic lead capture from Klaviyo, Postscript, and more.
Initial setup guide for connecting your Shopify store.