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 events let you track interactions that don’t fit the 13 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.

​
Naming Conventions

Custom event names follow these rules:
  • Use PascalCase: WishlistAdd, QuizComplete, LoyaltyRedeem
  • Keep names descriptive and specific: ProductConfigSaved is better than CustomAction1
  • Avoid names that collide with standard events — PageView, Purchase, etc. are reserved
  • Maximum length: 64 characters
  • Allowed characters: letters, numbers, underscores
Event names are case-sensitive. WishlistAdd and wishlistadd are treated as separate events. Pick a convention and stick with it.

​
Property Structure

Custom events use the same envelope as standard events. You control the custom_data payload — Upstack attaches user_data and context fields automatically. 
{
  "event_name": "WishlistAdd",
  "event_time": "2026-02-18T14:42:00.000Z",
  "event_source_url": "https://example-store.com/products/classic-tee",
  "user_data": {
    "client_ip_address": "203.0.113.42",
    "client_user_agent": "Mozilla/5.0...",
    "fbp": "fb.1.1708271400.XyZ789"
  },
  "custom_data": {
    "content_ids": ["8012345678"],
    "content_name": "Classic Cotton Tee",
    "value": 34.99,
    "currency": "USD",
    "wishlist_id": "wl_abc123"
  }
}
You can include any key-value pairs in custom_data. For best compatibility with destinations, reuse the 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', 'WishlistAdd', {
  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.

​
Upstack-native custom purchase events

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 Shopify 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 Shopify 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).Example payload:
{
  "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",
    "client_ip_address": "203.0.113.42",
    "client_user_agent": "Mozilla/5.0...",
    "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.

Standard Events

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

Properties & Context

See all available property fields you can include in custom_data.