Skip to main content
Custom events let you track interactions that don’t fit the standard event types. Wishlist adds, quiz completions, loyalty point redemptions, product configurator steps — any meaningful customer action can be captured as a custom event and forwarded through the Upstack pipeline.
Custom events flow through the same Capture → Resolve → Enrich → Activate pipeline as standard events. They receive identity resolution, enrichment, and destination forwarding automatically.
Two types of custom events exist:
  • User-defined custom events — Events you create and fire manually for business-specific interactions
  • Upstack-generated events — Events like nc_purchase and rc_purchase that Upstack fires automatically alongside standard events
See Upstack-native custom purchase events for the automatically generated events.

​
Naming Conventions

Custom event names follow these rules:
  • Use snake_case: wishlist_add, quiz_complete, loyalty_redeem
  • Keep names descriptive and specific: product_config_saved is better than custom_action_1
  • Avoid names that collide with standard events — page_view, purchase, etc. are reserved
  • Maximum length: 64 characters
  • Allowed characters: letters, numbers, underscores
Event names are case-sensitive. wishlist_add and WishlistAdd are treated as separate events. Use snake_case to match standard event conventions.

​
Tracking Custom Events

Pass the event name and properties directly to the track() method: 
window._upstack('track', 'wishlist_add', {
  content_ids: ['8012345678'],
  content_name: 'Classic Cotton Tee',
  value: 34.99,
  currency: 'USD',
  wishlist_id: 'wl_abc123'
});
Upstack automatically attaches identity data (user_data), timestamps, and context fields. You only provide the event name and properties. For best compatibility with destinations, reuse standard property names (content_ids, value, currency, content_name) wherever they apply.

​
How Custom Events Flow Through the Pipeline

Custom events follow the exact same path as standard events:
  1. Capture — The Upstack Pixel sends the event to the edge API. You can fire custom events using the JavaScript tracking API on your storefront.
  2. Resolve — Upstack ID attaches identity data to the event. Session stitching and cross-device linking work the same as for standard events.
  3. Enrich — UTM parameters, click IDs, and product catalog data are merged if applicable content_ids are present.
  4. Activate — The event is forwarded to destinations that accept custom events.

​
Destination Support

Not all destinations handle custom events the same way:
DestinationCustom Event Support
Meta CAPISupported as Custom event type. Meta receives the custom event name and all properties. Useful for building custom audiences and optimization.
TikTok Events APISupported. Custom events can be used for audience building but not standard optimization.
KlaviyoFully supported. Custom events appear as distinct metric types in Klaviyo for flow triggers and segmentation.
GA4Supported. Custom event names map directly to GA4 custom events. Properties become event parameters.
WebhookFully supported. The raw event payload is forwarded as-is.
Meta and TikTok ad optimization algorithms work best with standard events. Use custom events for audience building and measurement, but rely on standard events (Purchase, AddToCart, etc.) for campaign optimization signals.

​
Firing Custom Events

To fire a custom event from your storefront, use the Upstack JavaScript API: 
window._upstack('track', 'wishlist_add', {
  content_ids: ['8012345678'],
  content_name: 'Classic Cotton Tee',
  value: 34.99,
  currency: 'USD',
  wishlist_id: 'wl_abc123'
});
The Upstack Pixel handles serialization, batching, and delivery to the edge API. Identity fields (user_data) are attached automatically — you only need to provide the event name and custom_data properties.
For the full track() method signature with all 7 parameters including event deduplication, backdating, and useBeacon for page unload tracking, see the JavaScript SDK Reference.

​
Upstack-native custom purchase events

Shopify-specific feature — The nc_purchase and rc_purchase events are only available for Shopify stores using the Upstack Shopify app. They rely on Shopify order history to determine customer status.
In addition to user-defined custom events, Upstack fires two built-in custom events that segment every order by customer status. They are sent alongside — not instead of — the standard purchase event.
Fires when an order is placed by a customer with no prior completed order history. Used to optimize Meta campaigns toward new-customer acquisition instead of repeat buyers.When it fires: Order confirmation, when the customer has zero prior completed orders in Shopify.Properties: Same payload as the standard Purchase event (value, currency, content_ids, order_id, etc.) plus Upstack’s identity enrichment (em, ph, fn, ln, fbc, fbp, client_ip_address, client_user_agent).See Set up custom events → NC Purchase for Meta setup steps.
Fires when an order is placed by a customer with one or more prior completed orders. Used for retargeting audiences, retention measurement, and keeping prospecting campaigns honest about who they’re actually converting.When it fires: Order confirmation, when the customer has at least one prior completed order in Shopify.Properties: Same payload as the standard Purchase event (value, currency, content_ids, order_id, etc.) plus Upstack’s identity enrichment (em, ph, fn, ln, fbc, fbp, client_ip_address, client_user_agent).What destinations receive (internal format):
// Internal format — Upstack fires this automatically, you don't write this code
{
  "event_name": "rc_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",
    "fbc": "fb.1.1708271400.AbC123",
    "fbp": "fb.1.1708271400.XyZ789",
    "external_id": "cust_12345"
  },
  "custom_data": {
    "content_ids": ["8012345678"],
    "content_type": "product",
    "value": 42.00,
    "currency": "USD",
    "order_id": "#1087",
    "num_items": 1
  }
}
See Set up custom events → RC Purchase for Meta setup steps.
The standard purchase event still fires for every order regardless of customer status. nc_purchase and rc_purchase fire in addition to purchase, not instead of it.

​
AOV-Segmented Purchase Events

Upstack automatically generates AOV (Average Order Value) segmented purchase events based on your store’s order history. These events help you optimize campaigns toward high-value orders.
Automatically generated. You do not fire these events manually. Upstack analyzes each order against your store’s historical AOV distribution and fires the appropriate event automatically.
Fires when an order’s value exceeds your store’s historical average order value threshold.When it fires: Order confirmation, when order_value > store_aov_threshold.Properties: Same payload as the standard Purchase event.Use case: Optimize Meta campaigns toward customers who place high-value orders, not just any orders.
Fires when an order’s value falls below your store’s historical average.When it fires: Order confirmation, when order_value < store_aov_threshold.Properties: Same payload as the standard Purchase event.Use case: Exclude from high-value optimization campaigns; analyze patterns in low-value conversions.
Fires when an order’s value exceeds the 70th percentile of your store’s order values.When it fires: Order confirmation, when order_value >= p70_threshold.Properties: Same payload as the standard Purchase event.Use case: Target campaigns toward top 30% of orders by value.
Fires when an order’s value exceeds the 80th percentile of your store’s order values.When it fires: Order confirmation, when order_value >= p80_threshold.Properties: Same payload as the standard Purchase event.Use case: Target campaigns toward top 20% of orders by value.
Fires when an order’s value exceeds the 90th percentile of your store’s order values.When it fires: Order confirmation, when order_value >= p90_threshold.Properties: Same payload as the standard Purchase event.Use case: Target campaigns toward your highest-value orders (top 10%).
Use percentile-based events (p70_aov_purchase, p80_aov_purchase, p90_aov_purchase) in Meta custom conversions to optimize toward different value tiers. This is more precise than the binary high_aov_purchase/low_aov_purchase split.

​
Customer Behavior Purchase Events

Upstack automatically segments purchases by customer behavior patterns.
Fires when an order contains upsell or cross-sell items that were added after the initial product selection.When it fires: Order confirmation, when upsell/cross-sell items are detected in the cart.Properties: Same payload as the standard Purchase event, plus identification of which items were upsells.Use case: Measure upsell effectiveness; optimize campaigns toward customers likely to accept upsells.
Fires when a previously inactive customer returns and makes a purchase.When it fires: Order confirmation, when the customer has been inactive for a defined period (typically 90+ days since last order).Properties: Same payload as the standard Purchase event.Use case: Measure win-back campaign effectiveness; build audiences of re-engaged customers.

Standard Events

Review the full list of built-in events before creating a custom event.

JavaScript SDK

Full track() method reference with all 7 parameters.

Properties & Context

See all available property fields you can include in custom_data.

Shopify Automatic Tracking

Events automatically tracked on Shopify stores.