Upstack Data Standard Events Reference

Standard events are predefined event types that Upstack recognizes across all destinations. Use these events to track customer behavior and attribute conversions.

This guide applies to all Upstack implementations — Shopify, headless, GTM, or custom websites. The JavaScript snippets below work everywhere the Upstack pixel is installed.

Shopify stores: Most events are tracked automatically by the Upstack Pixel. See Automatic Shopify Tracking to understand what’s already tracked. Use these snippets for custom implementations, headless checkouts, or events not covered by automatic tracking.

page_view

Fires when a visitor loads a page.

JavaScript

window._upstack('page');

With custom properties:

window._upstack('page', {
  pageCategory: 'product',
  collectionHandle: 'summer-2026'
});

Properties

Property	Type	Required	Description
pageCategory	string	No	Page type (e.g., `'product'`, `'collection'`, `'blog'`)
collectionHandle	string	No	Collection identifier for collection pages

Auto-Captured

The SDK automatically captures page_url, page_title, page_referrer, and page_path.

When to Fire

On initial page load
On SPA route changes
After dynamic content loads (infinite scroll)

view_content

Fires when a visitor views a product or content page.

Shopify: Automatically tracked when viewing product detail pages.

JavaScript

window._upstack('track', 'view_content', {
  items: [
    {
      id: 'SKU_12345',
      name: 'Classic Cotton Tee',
      price: 34.99,
      brand: 'Example Brand',
      category: 'Apparel/T-Shirts'
    }
  ],
  value: 34.99,
  currency: 'USD'
});

Minimal example:

window._upstack('track', 'view_content', {
  items: [{ id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99 }],
  value: 34.99,
  currency: 'USD'
});

Properties

Property	Type	Required	Description
items	array	Yes	Products viewed (see Item Object)
value	number	Yes	Product price
currency	string	Yes	ISO 4217 currency code (e.g., `'USD'`)

When to Fire

Product detail page load
Quick view modal open
Collection page load (with collection products)

view_category

Fires when a visitor views a collection or category page.

Shopify: Automatically tracked when viewing collection pages.

JavaScript

window._upstack('track', 'view_category', {
  items: [
    { id: 'SKU_001', name: 'Classic Cotton Tee', price: 34.99 },
    { id: 'SKU_002', name: 'Vintage Logo Hoodie', price: 59.99 },
    { id: 'SKU_003', name: 'Slim Fit Jeans', price: 79.99 }
  ],
  itemListId: 'summer_collection',
  itemListName: 'Summer 2026 Collection'
});

Minimal example:

window._upstack('track', 'view_category', {
  itemListId: 'mens_shirts',
  itemListName: 'Men\'s Shirts'
});

Properties

Property	Type	Required	Description
itemListId	string	No	Collection/category identifier
itemListName	string	No	Collection/category display name
items	array	No	Products shown in the category (see Item Object)

When to Fire

Collection page load
Category filter applied
Browse by category navigation

view_item_list

Fires when a visitor views a list of products (similar to view_category but more general).

JavaScript

window._upstack('track', 'view_item_list', {
  items: [
    { id: 'SKU_001', name: 'Classic Cotton Tee', price: 34.99, index: 0 },
    { id: 'SKU_002', name: 'Vintage Logo Hoodie', price: 59.99, index: 1 }
  ],
  itemListId: 'recommended_products',
  itemListName: 'Recommended For You'
});

Properties

Property	Type	Required	Description
itemListId	string	No	List identifier
itemListName	string	No	List display name
items	array	No	Products in the list (include `index` for position tracking)

When to Fire

Product recommendation carousel load
“Related Products” section view
“Recently Viewed” section view
Search results page load

add_to_cart

Fires when a visitor adds an item to their cart.

JavaScript

window._upstack('track', 'add_to_cart', {
  items: [
    {
      id: 'SKU_12345',
      name: 'Classic Cotton Tee',
      price: 34.99,
      quantity: 2,
      variant: 'Blue / Medium',
      brand: 'Example Brand',
      category: 'Apparel/T-Shirts'
    }
  ],
  value: 69.98,
  currency: 'USD'
});

Minimal example:

window._upstack('track', 'add_to_cart', {
  items: [{ id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 1 }],
  value: 34.99,
  currency: 'USD'
});

Properties

Property	Type	Required	Description
items	array	Yes	Products added (see Item Object)
value	number	Yes	Total value of items added
currency	string	Yes	ISO 4217 currency code

When to Fire

Add-to-cart button click
Quantity increase in cart
“Buy Now” button click (before checkout)

product_removed_from_cart

Fires when a visitor removes an item from their cart.

JavaScript

window._upstack('track', 'product_removed_from_cart', {
  items: [
    {
      id: 'SKU_12345',
      name: 'Classic Cotton Tee',
      price: 34.99,
      quantity: 1
    }
  ],
  value: 34.99,
  currency: 'USD'
});

Properties

Property	Type	Required	Description
items	array	Yes	Products removed (see Item Object)
value	number	No	Value of removed items
currency	string	No	ISO 4217 currency code

When to Fire

Remove button click
Quantity decrease to zero
Clear cart action

view_cart

Fires when a visitor views their shopping cart.

JavaScript

window._upstack('track', 'view_cart', {
  items: [
    {
      id: 'SKU_12345',
      name: 'Classic Cotton Tee',
      price: 34.99,
      quantity: 2
    },
    {
      id: 'SKU_67890',
      name: 'Running Socks',
      price: 14.99,
      quantity: 1
    }
  ],
  value: 84.97,
  currency: 'USD'
});

Properties

Property	Type	Required	Description
items	array	Yes	Products in cart (see Item Object)
value	number	No	Total cart value
currency	string	No	ISO 4217 currency code

When to Fire

Cart page load
Cart drawer/sidebar open
Mini-cart expansion

initiate_checkout

Fires when a visitor starts the checkout process.

JavaScript

window._upstack('track', 'initiate_checkout', {
  items: [
    {
      id: 'SKU_12345',
      name: 'Classic Cotton Tee',
      price: 34.99,
      quantity: 2
    },
    {
      id: 'SKU_67890',
      name: 'Running Socks',
      price: 14.99,
      quantity: 1
    }
  ],
  value: 84.97,
  currency: 'USD'
});

Properties

Property	Type	Required	Description
items	array	Yes	Products in checkout
value	number	Yes	Cart subtotal
currency	string	Yes	ISO 4217 currency code

When to Fire

Checkout button click
Checkout page load
Express checkout initiation (Shop Pay, Apple Pay)

add_shipping_info

Fires when a customer enters shipping details during checkout.

JavaScript

window._upstack('track', 'add_shipping_info', {
  items: [
    { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 }
  ],
  value: 84.97,
  currency: 'USD',
  shippingTier: 'standard'
});

Properties

Property	Type	Required	Description
items	array	No	Products in checkout
value	number	No	Cart value at shipping step
currency	string	No	ISO 4217 currency code
shippingTier	string	No	Shipping method (e.g., `'standard'`, `'express'`, `'overnight'`)

When to Fire

Shipping form completion
Shipping method selection
Proceeding past shipping step

select_shipping_method

Fires when a customer selects a shipping method during checkout.

JavaScript

window._upstack('track', 'select_shipping_method', {
  shippingTier: 'express',
  shippingPrice: 12.99,
  currency: 'USD',
  value: 97.98
});

With items:

window._upstack('track', 'select_shipping_method', {
  shippingTier: 'overnight',
  shippingPrice: 24.99,
  currency: 'USD',
  value: 109.98,
  items: [
    { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 }
  ]
});

Properties

Property	Type	Required	Description
shippingTier	string	Yes	Shipping method selected (e.g., `'standard'`, `'express'`, `'overnight'`)
shippingPrice	number	No	Shipping cost
value	number	No	Cart value at shipping selection
currency	string	No	ISO 4217 currency code
items	array	No	Products in checkout

When to Fire

Shipping method radio button selection
Shipping tier dropdown change
Before proceeding to payment

add_payment_info

Fires when a customer enters payment details during checkout.

JavaScript

window._upstack('track', 'add_payment_info', {
  items: [
    { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 }
  ],
  value: 84.97,
  currency: 'USD',
  paymentType: 'credit_card'
});

Properties

Property	Type	Required	Description
items	array	No	Products in checkout
value	number	No	Cart value at payment step
currency	string	No	ISO 4217 currency code
paymentType	string	No	Payment method (e.g., `'credit_card'`, `'paypal'`, `'shop_pay'`)

When to Fire

Payment form completion
Payment method selection
Before final order submission

purchase

Fires when an order is completed.

JavaScript

window._upstack('track', 'purchase', {
  orderId: 'ORD_12345',
  value: 149.99,
  currency: 'USD',
  tax: 12.50,
  shipping: 5.99,
  items: [
    {
      id: 'SKU_001',
      name: 'Blue Running Shoes',
      price: 89.99,
      quantity: 1,
      brand: 'Nike',
      category: 'Shoes/Running'
    },
    {
      id: 'SKU_002',
      name: 'Running Socks',
      price: 14.99,
      quantity: 2,
      brand: 'Nike',
      category: 'Accessories/Socks'
    }
  ],
  email: 'customer@example.com'
}, 'ORD_12345');

The third parameter ('ORD_12345') is a deduplication ID. It prevents duplicate purchase events from being sent to destinations if the event fires multiple times.

Minimal example:

window._upstack('track', 'purchase', {
  orderId: 'ORD_12345',
  value: 149.99,
  currency: 'USD',
  items: [{ id: 'SKU_001', name: 'Blue Running Shoes', price: 89.99, quantity: 1 }]
}, 'ORD_12345');

Properties

Property	Type	Required	Description
orderId	string	Yes	Unique order identifier
value	number	Yes	Total order value
currency	string	Yes	ISO 4217 currency code
items	array	Yes	Products purchased (see Item Object)
tax	number	No	Tax amount
shipping	number	No	Shipping cost
email	string	No	Customer email (improves identity matching)

Important: The value property should match what you want reported to ad platforms. Discrepancies between Shopify order totals and reported CAPI revenue are the most common attribution debugging issue.

When to Fire

Order confirmation page load
After successful payment confirmation
Shopify orders/create webhook (server-side)

search

Fires when a visitor performs a search.

JavaScript

window._upstack('track', 'search', {
  searchTerm: 'blue running shoes',
  resultsCount: 24
});

With search results:

window._upstack('track', 'search', {
  searchTerm: 'blue running shoes',
  resultsCount: 24,
  items: [
    { id: 'SKU_001', name: 'Blue Running Shoes', price: 89.99 },
    { id: 'SKU_002', name: 'Navy Training Shoes', price: 79.99 }
  ]
});

Properties

Property	Type	Required	Description
searchTerm	string	Yes	The search query entered
resultsCount	number	No	Number of results returned
items	array	No	Top products in search results

When to Fire

Search results page load
Predictive search dropdown display
“No results” page (with resultsCount: 0)

lead

Fires when a visitor submits a lead form.

JavaScript

window._upstack('track', 'lead', {
  source: 'contact_form',
  email: 'prospect@example.com',
  value: 150.00,
  currency: 'USD'
});

Newsletter signup:

window._upstack('track', 'lead', {
  source: 'newsletter_popup',
  email: 'subscriber@example.com'
});

Properties

Property	Type	Required	Description
source	string	No	Form or campaign identifier
email	string	No	Lead’s email address
value	number	No	Estimated lead value
currency	string	No	ISO 4217 currency code

When to Fire

Contact form submission
Newsletter signup
Quote request submission
Product inquiry

complete_registration

Fires when a customer creates an account.

JavaScript

window._upstack('track', 'complete_registration', {
  method: 'email',
  source: 'checkout_page'
});

Properties

Property	Type	Required	Description
method	string	No	Registration method (e.g., `'email'`, `'google'`, `'facebook'`)
source	string	No	Where registration occurred

When to Fire

Account registration form submission
OAuth signup completion (Google, Facebook)
Post-purchase account creation

Fires when a visitor subscribes to email or SMS marketing.

JavaScript

window._upstack('track', 'subscribe', {
  channel: 'email',
  source: 'footer_form',
  value: 5.00,
  currency: 'USD'
});

SMS subscription:

window._upstack('track', 'subscribe', {
  channel: 'sms',
  source: 'popup',
  phone: '+15551234567'
});

Properties

Property	Type	Required	Description
channel	string	No	Subscription channel (`'email'`, `'sms'`, `'push'`)
source	string	No	Subscription source (e.g., `'popup'`, `'footer'`, `'checkout'`)
value	number	No	Estimated subscriber value
currency	string	No	ISO 4217 currency code

When to Fire

Newsletter signup
SMS opt-in
Push notification subscription

add_to_wishlist

Fires when a visitor adds a product to their wishlist.

JavaScript

window._upstack('track', 'add_to_wishlist', {
  items: [
    {
      id: 'SKU_12345',
      name: 'Classic Cotton Tee',
      price: 34.99,
      brand: 'Example Brand'
    }
  ],
  value: 34.99,
  currency: 'USD'
});

Properties

Property	Type	Required	Description
items	array	Yes	Products added to wishlist
value	number	No	Product price
currency	string	No	ISO 4217 currency code

When to Fire

Wishlist/favorite button click
Save for later action
Heart icon click on product

refund

Fires when an order is refunded.

JavaScript

Full refund:

window._upstack('track', 'refund', {
  orderId: 'ORD_12345',
  value: 149.99,
  currency: 'USD'
});

Partial refund:

window._upstack('track', 'refund', {
  orderId: 'ORD_12345',
  value: 89.99,
  currency: 'USD',
  items: [
    { id: 'SKU_001', name: 'Blue Running Shoes', price: 89.99, quantity: 1 }
  ]
});

Properties

Property	Type	Required	Description
orderId	string	Yes	Original order identifier
value	number	Yes	Refund amount
currency	string	No	ISO 4217 currency code
items	array	No	Products refunded (for partial refunds)

When to Fire

Refund processed via Shopify admin
refunds/create webhook (server-side)
Customer service refund action

Fires when a user logs into their account.

JavaScript

window._upstack('track', 'login', {
  method: 'email'
});

Properties

Property	Type	Required	Description
method	string	No	Login method (`'email'`, `'google'`, `'facebook'`, `'shop_pay'`)

When to Fire

Successful login form submission
OAuth login completion
Automatic re-authentication

sign_up

Fires when a user creates a new account.

JavaScript

window._upstack('track', 'sign_up', {
  method: 'email'
});

Properties

Property	Type	Required	Description
method	string	No	Signup method (`'email'`, `'google'`, `'facebook'`)

sign_up vs complete_registration: Use sign_up for initial account creation. Use complete_registration for multi-step registration flows or when capturing additional profile data.

When to Fire

Account creation form submission
OAuth signup completion

contact

Fires when a user submits a contact form.

JavaScript

window._upstack('track', 'contact', {
  formName: 'product_inquiry',
  email: 'customer@example.com'
});

Properties

Property	Type	Required	Description
formName	string	No	Form or inquiry type
email	string	No	Contact’s email

When to Fire

Contact us form submission
Support request submission
Product inquiry

book_call

Fires when a user books a call or consultation.

JavaScript

window._upstack('track', 'book_call', {
  callType: 'sales_consultation',
  value: 200.00,
  currency: 'USD'
});

Properties

Property	Type	Required	Description
callType	string	No	Type of call (e.g., `'sales_consultation'`, `'support'`)
value	number	No	Estimated value of the booking
currency	string	No	ISO 4217 currency code

When to Fire

Calendly booking confirmation
Meeting scheduler submission
Demo request completion

schedule

Fires when a user schedules an appointment.

JavaScript

window._upstack('track', 'schedule', {
  appointmentType: 'fitting',
  value: 75.00,
  currency: 'USD'
});

Properties

Property	Type	Required	Description
appointmentType	string	No	Type of appointment
value	number	No	Service value
currency	string	No	ISO 4217 currency code

When to Fire

Appointment booking confirmation
Service scheduling completion

submit_application

Fires when a user submits an application.

JavaScript

window._upstack('track', 'submit_application', {
  applicationType: 'wholesale_partner',
  value: 5000.00,
  currency: 'USD'
});

Properties

Property	Type	Required	Description
applicationType	string	No	Application type
value	number	No	Estimated application value
currency	string	No	ISO 4217 currency code

When to Fire

Wholesale application submission
Affiliate program application
Partnership request

trial_started

Fires when a visitor begins a free trial.

JavaScript

window._upstack('track', 'trial_started', {
  planName: 'Premium Plan',
  trialDays: 14,
  value: 49.99,
  currency: 'USD'
});

Properties

Property	Type	Required	Description
planName	string	No	Trial plan or product name
trialDays	number	No	Trial duration in days
value	number	No	Plan value after trial
currency	string	No	ISO 4217 currency code

When to Fire

Trial signup confirmation
Trial activation

Item Object

The items array in e-commerce events uses this structure:

{
  id: 'SKU_12345',           // Required: Product or variant ID
  name: 'Classic Cotton Tee', // Required: Product name
  price: 34.99,              // Required: Unit price
  quantity: 1,               // Required for cart/purchase events
  brand: 'Example Brand',    // Optional: Brand name
  category: 'Apparel/Tees',  // Optional: Product category (use / for hierarchy)
  variant: 'Blue / Medium',  // Optional: Variant info
  position: 1                // Optional: Position in list (for impressions)
}

Property	Type	Required	Description
id	string	Yes	Product or variant SKU/ID
name	string	Yes	Product display name
price	number	Yes	Unit price (not total)
quantity	number	Varies	Required for add_to_cart, purchase; optional for view events
brand	string	No	Brand or manufacturer
category	string	No	Category path (e.g., `'Shoes/Running'`)
variant	string	No	Size, color, or other variant
position	number	No	Position in list for impression tracking

Event Tracking Matrix

This matrix shows which events are tracked automatically by the Upstack Pixel on Shopify stores versus which require manual implementation.

Event	Shopify Auto	Headless/Manual
`page_view`	✅	Required
`view_content`	✅	Required
`view_category`	✅	Required
`view_item_list`	—	Required
`add_to_cart`	✅	Required
`product_removed_from_cart`	✅	Required
`view_cart`	✅	Required
`initiate_checkout`	✅	Required
`add_shipping_info`	✅	Required
`select_shipping_method`	—	Required
`add_payment_info`	✅	Required
`purchase`	✅	Required
`search`	✅	Required
`lead`	Via form hooks	Required
`subscribe`	Via popup/form hooks	Required
`complete_registration`	—	Required
`login`	—	Required
`sign_up`	—	Required
`refund`	Via webhook	—

Legend:

✅ = Automatically tracked by Upstack Pixel
Via form hooks = Tracked when using compatible form/popup apps
Via webhook = Tracked server-side through Shopify webhooks
Required = You must implement manually
— = Not applicable or rarely needed

Events Not Covered Here

Event Type	Documentation
`identify`	See JavaScript SDK Reference
`nc_purchase` / `rc_purchase`	Upstack-generated new vs. returning customer purchase events. See Custom Events
Shopify automatic events	See Shopify Automatic Tracking
SaaS events	See SaaS Events Reference
Custom events	See Custom Events

Shopify Automatic Tracking

Events that fire automatically on Shopify stores — check what’s already tracked.

JavaScript SDK

Full SDK API reference including identify() and direct client methods.

Properties & Context

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

Custom Events

Create events beyond the standard taxonomy, including Upstack-generated events like nc_purchase.

​page_view

​JavaScript

​Properties

​Auto-Captured

​When to Fire

​view_content

​JavaScript

​Properties

​When to Fire

​view_category

​JavaScript

​Properties

​When to Fire

​view_item_list

​JavaScript

​Properties

​When to Fire

​add_to_cart

​JavaScript

​Properties

​When to Fire

​product_removed_from_cart

​JavaScript

​Properties

​When to Fire

​view_cart

​JavaScript

​Properties

​When to Fire

​initiate_checkout

​JavaScript

​Properties

​When to Fire

​add_shipping_info

​JavaScript

​Properties

​When to Fire

​select_shipping_method

​JavaScript

​Properties

​When to Fire

​add_payment_info

​JavaScript

​Properties

​When to Fire

​purchase

​JavaScript

​Properties

​When to Fire

​search

​JavaScript

​Properties

​When to Fire

​lead

​JavaScript

​Properties

​When to Fire

​complete_registration

​JavaScript

​Properties

​When to Fire

​subscribe

​JavaScript

​Properties

​When to Fire

​add_to_wishlist

​JavaScript

​Properties

​When to Fire

​refund

​JavaScript

​Properties

​When to Fire

​login

​JavaScript

​Properties

​When to Fire

​sign_up

​JavaScript

​Properties

page_view

JavaScript

Properties

Auto-Captured

When to Fire

view_content

JavaScript

Properties

When to Fire

view_category

JavaScript

Properties

When to Fire

view_item_list

JavaScript

Properties

When to Fire

add_to_cart

JavaScript

Properties

When to Fire

product_removed_from_cart

JavaScript

Properties

When to Fire

view_cart

JavaScript

Properties

When to Fire

initiate_checkout

JavaScript

Properties

When to Fire

add_shipping_info

JavaScript

Properties

When to Fire

select_shipping_method

JavaScript

Properties

When to Fire

add_payment_info

JavaScript

Properties

When to Fire

purchase

JavaScript

Properties

When to Fire

search

JavaScript

Properties

When to Fire

lead

JavaScript

Properties

When to Fire

complete_registration

JavaScript

Properties

When to Fire

subscribe

JavaScript

Properties

When to Fire

add_to_wishlist

JavaScript

Properties

When to Fire

refund

JavaScript

Properties

When to Fire

login

JavaScript

Properties

When to Fire

sign_up

JavaScript

Properties