> ## 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

> Define and send custom events to capture site-specific interactions beyond Upstack's standard event taxonomy — for use in attribution, audience segmentation, and destination forwarding.

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.

<Tip>
  Custom events flow through the same Capture → Resolve → Enrich → Activate pipeline as standard events. They receive identity resolution, enrichment, and destination forwarding automatically.
</Tip>

## 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

<Warning>
  Event names are case-sensitive. `WishlistAdd` and `wishlistadd` are treated as separate events. Pick a convention and stick with it.
</Warning>

## 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.

```json theme={null}
{
  "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:

| 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.                                                                                       |

<Note>
  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.
</Note>

## Firing Custom Events

To fire a custom event from your storefront, use the Upstack JavaScript API:

```javascript theme={null}
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.

<AccordionGroup>
  <Accordion title="nc_purchase" icon="user-plus">
    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](/get-started/custom-events#new-customer-purchase-nc-purchase) for Meta setup steps.
  </Accordion>

  <Accordion title="rc_purchase" icon="rotate-right">
    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:**

    ```json theme={null}
    {
      "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](/get-started/custom-events#returning-customer-purchase-rc-purchase) for Meta setup steps.
  </Accordion>
</AccordionGroup>

<Note>
  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.
</Note>

<CardGroup cols={2}>
  <Card title="Standard Events" icon="list-check" href="/data-dictionary/standard-events">
    Review the full list of built-in events before creating a custom event.
  </Card>

  <Card title="Properties & Context" icon="table" href="/data-dictionary/properties-and-context">
    See all available property fields you can include in custom\_data.
  </Card>
</CardGroup>