> ## 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. # Custom Events > Track custom events beyond standard taxonomy — wishlist adds, quiz completions, loyalty redemptions. Full pipeline support with identity resolution. 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](#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: ```javascript theme={null} 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: | 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. | | **Webhook** | Fully 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: ```javascript theme={null} 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](/pixel/javascript-sdk#trackeventname-eventdata). ## 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](/guides/facebook-ads/set-up-nc-and-rc-purchase-events-in-meta#new-customer-purchase-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):** ```json theme={null} // 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](/guides/facebook-ads/set-up-nc-and-rc-purchase-events-in-meta#returning-customer-purchase-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. ## Related Documentation Review the full list of built-in events before creating a custom event. Full track() method reference with all 7 parameters. See all available property fields you can include in custom\_data. Events automatically tracked on Shopify stores.