Skip to main content

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 event triggers let you go beyond standard ecommerce events — page views, add-to-carts, purchases — to track the specific actions that matter most to your business. This guide explains what custom event triggers are, when to use them, and how they flow through Upstack’s server-side pipeline to your ad platforms.

​
Prerequisites

  • An Upstack Data account with the Upstack pixel installed and standard events flowing
  • At least one destination connected (see Connect a destination) — Meta, Google Ads, TikTok, Klaviyo, etc.
  • A clear definition of the trigger condition you want to track (e.g., new customer purchase, quiz completion, high-value order)
  • Admin access to the destination platform’s event manager (e.g., Meta Events Manager) so you can approve custom events and create matching Custom Conversions

​
What are custom event triggers?

Standard ecommerce tracking covers the basics: someone views a product, adds it to their cart, begins checkout, and completes a purchase. But your business likely has actions that fall outside that flow — quiz completions, email sign-ups, subscription enrollments, or purchases from a specific product category. Custom event triggers let you define those actions as trackable events in Upstack. Once configured, they flow through the same server-side pipeline as your standard events: enriched with identity data, matched to user profiles, and forwarded to your connected destinations (Meta, Google Ads, TikTok, and others). This means you can tell Meta “this person completed a quiz” or “this was a first-time customer purchase” with the same data quality and identity enrichment your standard purchase events receive.
Custom events complement standard tracking — they don’t replace it. Keep sending the standard Purchase event alongside any custom variant like nc_purchase. Ad platforms rely on the standard event for baseline optimization and reporting.

​
Why custom event triggers matter

Custom events unlock capabilities that standard tracking cannot:
  • New customer acquisition optimization. Send a dedicated event when a first-time customer purchases, so Meta or Google can optimize for acquiring net-new buyers — not just driving repeat orders.
  • Category-level optimization. If you sell across multiple product categories (e.g., skincare and supplements), purchase events scoped per category let ad platforms optimize for the right products.
  • Funnel-stage tracking. Track mid-funnel actions like quiz completions or email captures as conversion events, giving ad platforms more signal about user intent earlier in the journey.
  • High-value action identification. Define events for actions that predict high lifetime value — subscribing, purchasing a bundle, or hitting a spend threshold.

​
Common use cases

Fires only when an order comes from a customer with no prior Shopify order history. The most popular custom event — it lets Meta and Google optimize for net-new customer acquisition rather than total purchases. See Setting up new customer purchase metrics in Meta Ads Manager.
The complement to nc_purchase — fires when a customer with existing order history makes a purchase. Useful for building retargeting audiences or measuring retention campaign performance.
Fires when a purchase includes products from a specific collection or product type. A brand selling apparel and accessories might create apparel_purchase and accessories_purchase events to let Meta optimize separately for each category.
Fires when a customer completes an on-site quiz, survey, or lead capture form. Gives ad platforms a mid-funnel signal that helps them find users more likely to engage deeply with your brand.
Fires when a customer signs up for a subscription product. Especially valuable for brands where subscription customers have significantly higher lifetime value.
Fires when an order exceeds a specified dollar threshold (e.g., orders over $150). Lets ad platforms optimize for higher-AOV customers.

​
How custom events flow through Upstack

Custom events follow the same path as standard events:
1

Trigger condition is met

The action you defined occurs — a new customer makes a purchase, a quiz is completed, a high-value order is placed.
2

Upstack captures and enriches the event

The event runs through Upstack’s server-side pipeline, where identity resolution attaches available user data — email, phone, IP, browser fingerprint, click IDs.
3

Event is sent to destinations

The enriched event is delivered to your connected destinations via their server-side APIs — Meta CAPI, Google Ads offline conversions, TikTok Events API, and others.
4

Ad platforms match the event

The destination uses the identity parameters to match the event to a user profile. The richer the identity data, the higher the match quality.
Because custom events go through the same enrichment pipeline, they benefit from the same identity resolution and data quality as your standard events.

​
General workflow

Setting up a custom event trigger follows this flow:
1

Define the trigger condition

Decide what action should fire the event and what criteria must be met (customer has zero prior orders, order contains products from a specific collection, order value exceeds a threshold).
2

Configure event parameters

Set the event name, the data that should accompany it (value, currency, content IDs), and any filtering rules.
3

Map to destinations

Choose which connected destinations should receive this event. The same event can be sent to Meta, Google Ads, TikTok, Pinterest, Snapchat, and others simultaneously.
4

Create corresponding custom conversions (if needed)

In platforms like Meta, create a Custom Conversion in Events Manager that maps to your custom event name, so you can use it as an optimization goal in your ad campaigns. See How to approve Meta custom events.
Configuration steps will vary by event type. Contact the Upstack team during onboarding for specific setup — they’ll help you scope the trigger condition, parameter mapping, and destination routing for your use case.

​
Best practices

​
Naming conventions

  • Use lowercase with underscores: nc_purchase, quiz_complete, high_value_order.
  • Keep names short but descriptive — ad platform UIs have limited space for event names.
  • Be consistent. If you use nc_purchase for new customer purchase, use rc_purchase for returning — not returning_customer_buy.

​
Start with high-impact events

Don’t create a dozen custom events on day one. Start with the one or two that will most directly improve your ad optimization:
  • If your primary goal is new customer acquisition, start with nc_purchase.
  • If you sell across distinct categories, start with category-specific purchase events.
  • If you have a quiz-driven funnel, add quiz completion early.

​
Validate before scaling

After creating a custom event, verify it’s firing correctly and being received by your destination platforms before building ad campaigns around it:
  • In the Upstack dashboard under Event Health, confirm the custom event appears with the expected name and parameters.
  • In your destination’s event manager (Meta Events Manager, Google Ads conversions, TikTok Events Manager, etc.), confirm the event is arriving with the expected parameters.
  • Trigger the event in a controlled test (e.g., place a test order matching your condition) and confirm it shows up end-to-end before scaling spend.

​
Avoid duplicating standard events

Custom events should complement standard tracking. Keep sending the standard Purchase event alongside any custom purchase events like nc_purchase. Ad platforms rely on the standard event for baseline optimization and reporting.

​
Include value parameters

Whenever a custom event is tied to revenue (like a purchase event), include the value and currency parameters. This lets ad platforms calculate ROAS for campaigns optimized toward that event.
Pair every revenue-bearing custom event with a Custom Conversion in Meta. The custom event populates Meta’s pipeline; the Custom Conversion is what you actually select as a campaign optimization goal. See How to approve Meta custom events.

​
Frequently asked questions

Yes. Custom events flow through the same Upstack pipeline as standard events, receiving the same identity resolution, data enrichment, and server-side delivery.
There is no hard limit in Upstack, but ad platforms have their own. Meta, for example, allows up to 100 custom conversions per ad account. Focus on the events that meaningfully improve your optimization.
Custom events are scored separately from standard events in Meta’s system. They benefit from the same identity parameters Upstack attaches, so they should have similar match quality to your standard events.
Yes. When you configure a custom event, you can map it to any of your connected destinations. The same event can be sent to Meta, Google Ads, TikTok, and others simultaneously.

Custom events overview

Why custom events matter and how they fit into your tracking setup.

Custom events data dictionary

Reference for custom event names, parameters, and payloads.

New customer purchase metrics in Meta

End-to-end setup for nc_purchase and the matching Meta Custom Conversion.

Approve Meta custom events

Approve and verify custom events in Meta Events Manager.

Meta CAPI destination

Configure server-side event delivery to Meta.