Custom Events - Upstack Data

Custom events let you track interactions that don’t fit the standard event types. 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. For wishlist adds, use the standard add_to_wishlist event instead.

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: quiz_complete, loyalty_redeem, product_config_saved
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. quiz_complete and QuizComplete 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', 'product_config_saved', {
  items: [{ id: '8012345678', name: 'Classic Cotton Tee', price: 34.99 }],
  value: 34.99,
  currency: 'USD',
  config_id: 'cfg_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 (items, value, currency) wherever they apply — destination content IDs are built from items[], not from a top-level content_ids property.

How Custom Events Flow Through the Pipeline

Custom events follow the exact same path as standard events:

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

Destination Support

Not all destinations handle custom events the same way:

Destination	Custom Event Support
Meta CAPI	Supported as `Custom` event type. Meta receives the custom event name and all properties. Useful for building custom audiences and optimization.
TikTok Events API	Supported. Custom events can be used for audience building but not standard optimization.
Klaviyo	Fully supported. Custom events appear as distinct metric types in Klaviyo for flow triggers and segmentation.
GA4	Supported. Custom event names map directly to GA4 custom events. Properties become event parameters.

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', 'product_config_saved', {
  items: [{ id: '8012345678', name: 'Classic Cotton Tee', price: 34.99 }],
  value: 34.99,
  currency: 'USD',
  config_id: 'cfg_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. Customer status comes from Upstack’s own customer records, built from tracked purchases plus imported Shopify orders — Upstack doesn’t look up the customer’s order history in Shopify at purchase time.

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.

nc_purchase

Fires when an order is placed by a customer Upstack has no customer record for. Used to optimize Meta campaigns toward new-customer acquisition instead of repeat buyers.When it fires: On each purchase, when Upstack finds no record of the customer in its own customer records (built from tracked purchases plus imported Shopify orders).Properties: Same payload as the standard Purchase event (value, currency, items, orderId, 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.

rc_purchase

Fires when an order is placed by a customer Upstack already has a customer record for. Used for retargeting audiences, retention measurement, and keeping prospecting campaigns honest about who they’re actually converting.When it fires: On each purchase, when Upstack finds the customer in its own customer records (built from tracked purchases plus imported Shopify orders).Properties: Same payload as the standard Purchase event (value, currency, items, orderId, 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 has built-in measures for five order-value event names — high_aov_purchase, low_aov_purchase, p70_aov_purchase, p80_aov_purchase, and p90_aov_purchase — but it doesn’t generate these events automatically or calculate AOV thresholds from your order history. To use one, create it with a global event mapping on purchase with an order-value condition. See AOV purchase events for the event names, their built-in measures, and setup steps.

Customer Behavior Purchase Events

Upstack automatically segments purchases by customer behavior patterns.

upsell_purchase

Fires when a customer accepts a post-purchase offer that adds items to an order Upstack has already sent as a Purchase.When it fires: On a Shopify order update for the same order, when the order has the AfterSell Upsell tag and its new total is higher than the Purchase value already sent.Properties: Same payload as the original Purchase event, except value is only the added amount and items lists only the added line items.Use case: Measure upsell effectiveness; optimize campaigns toward customers likely to accept upsells.See How post-purchase upsells are tracked for how Upstack detects an upsell.

lapsed_purchase

Fires when a previously inactive customer returns and makes a purchase.When it fires: On a purchase, when the customer’s previous order was created 12 or more calendar months earlier.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.

​Naming Conventions

​Tracking Custom Events

​How Custom Events Flow Through the Pipeline

​Destination Support

​Firing Custom Events

​Upstack-native custom purchase events

​AOV-Segmented Purchase Events

​Customer Behavior Purchase Events

​Related Documentation

Standard Events

JavaScript SDK

Properties & Context

Shopify Automatic Tracking

Naming Conventions

Tracking Custom Events

How Custom Events Flow Through the Pipeline

Destination Support

Firing Custom Events

Upstack-native custom purchase events

AOV-Segmented Purchase Events

Customer Behavior Purchase Events

Related Documentation