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

# Event Properties and Context Fields

> Complete reference for all user data, custom data, and context fields available on Upstack events.

Every Upstack event consists of three field groups: **user data** for identity signals, **custom data** for event-specific properties, and **context** for automatic metadata. This page documents every available field.

<Note>
  Context fields are attached automatically by the Upstack Pixel and edge API. You never need to set them manually. User data fields are populated by identity resolution — the more identifiers available, the higher your destination match quality.
</Note>

## User Data

Identity signals attached to each event. These fields drive destination match quality (EMQ) and enable cross-device identity resolution.

| Field               | Type   | Description                                                                            | Example                             |
| ------------------- | ------ | -------------------------------------------------------------------------------------- | ----------------------------------- |
| `em`                | string | SHA-256 hashed email address. Lowercase and trimmed before hashing.                    | `a1b2c3d4e5f6...`                   |
| `ph`                | string | SHA-256 hashed phone number. E.164 format before hashing (e.g., `+15551234567`).       | `f6e5d4c3b2a1...`                   |
| `client_ip_address` | string | Visitor's IP address. Captured server-side by the edge API.                            | `203.0.113.42`                      |
| `client_user_agent` | string | Browser user agent string.                                                             | `Mozilla/5.0 (Macintosh; Intel...)` |
| `fbc`               | string | Meta click ID cookie (`_fbc`). Contains the `fbclid` from the ad click URL.            | `fb.1.1708271400.AbC123`            |
| `fbp`               | string | Meta browser ID cookie (`_fbp`). First-party cookie set by the Meta pixel.             | `fb.1.1708271400.XyZ789`            |
| `external_id`       | string | Your unique customer identifier (e.g., Shopify customer ID). Hashed before forwarding. | `cust_12345`                        |
| `ttclid`            | string | TikTok click ID. Captured from the ad click URL parameter.                             | `E.C.P.abc123def456`                |
| `gclid`             | string | Google click ID. Captured from the ad click URL parameter.                             | `CjwKCAjw...`                       |

<Tip>
  The more user data fields present on an event, the higher the match quality at destinations. A Purchase event with `em`, `ph`, `fbc`, and `fbp` typically scores EMQ 8–9 on Meta. The same event with only `client_ip_address` scores 2–3.
</Tip>

## Custom Data

Event-specific properties that describe what happened. Which fields are relevant depends on the event type.

| Field           | Type      | Description                                                    | Applicable Events                                                  |
| --------------- | --------- | -------------------------------------------------------------- | ------------------------------------------------------------------ |
| `value`         | number    | Monetary value of the event (e.g., cart total, order revenue). | AddToCart, InitiateCheckout, Purchase, Lead, Subscribe, StartTrial |
| `currency`      | string    | ISO 4217 currency code.                                        | Any event with `value`                                             |
| `content_ids`   | string\[] | Array of product or variant IDs involved in the event.         | ViewContent, AddToCart, InitiateCheckout, Purchase, Search         |
| `content_type`  | string    | Type of content: `"product"` or `"product_group"`.             | ViewContent, AddToCart, InitiateCheckout, Purchase                 |
| `content_name`  | string    | Human-readable name of the product, collection, or form.       | ViewContent, Lead, CompleteRegistration, StartTrial                |
| `num_items`     | number    | Total number of items in the cart or order.                    | AddToCart, InitiateCheckout, Purchase                              |
| `order_id`      | string    | Unique order identifier (Shopify order ID or name).            | Purchase                                                           |
| `search_string` | string    | The search query entered by the visitor.                       | Search                                                             |
| `page_title`    | string    | HTML `<title>` of the page where the event fired.              | PageView                                                           |
| `referrer`      | string    | The referring URL that led the visitor to the current page.    | PageView                                                           |

<Warning>
  The `value` field should represent the actual monetary amount relevant to the event. For Purchase events, this should match the order total you want reported to ad platforms. Mismatched values between Shopify and your destinations are the most common attribution debugging issue.
</Warning>

## Context

Automatic metadata captured by the Upstack Pixel and edge API. These fields are present on every event.

| Field              | Type     | Description                                                                 | Example                                          |
| ------------------ | -------- | --------------------------------------------------------------------------- | ------------------------------------------------ |
| `event_source_url` | string   | Full URL of the page where the event fired.                                 | `https://example-store.com/products/classic-tee` |
| `event_time`       | ISO 8601 | Timestamp when the event occurred, in UTC.                                  | `2026-02-18T14:30:00.000Z`                       |
| `page_url`         | string   | Canonical page URL (without query parameters).                              | `https://example-store.com/products/classic-tee` |
| `page_title`       | string   | HTML document title at the time of the event.                               | `Classic Cotton Tee \| Example Store`            |
| `referrer`         | string   | HTTP referrer header value.                                                 | `https://www.google.com/`                        |
| `user_agent`       | string   | Raw user agent string from the HTTP request.                                | `Mozilla/5.0 (Macintosh; Intel Mac OS X...)`     |
| `ip_address`       | string   | Client IP address as seen by the edge API.                                  | `203.0.113.42`                                   |
| `pixel_id`         | string   | Your Upstack Pixel ID. Identifies which store the event belongs to.         | `px_abc123def456`                                |
| `event_id`         | string   | Unique event identifier for deduplication.                                  | `evt_8f3a2b1c...`                                |
| `session_id`       | string   | Upstack session identifier. Groups events within a single browsing session. | `sess_9d4e5f6a...`                               |
| `utm_source`       | string   | UTM source parameter from the landing page URL.                             | `facebook`                                       |
| `utm_medium`       | string   | UTM medium parameter.                                                       | `cpc`                                            |
| `utm_campaign`     | string   | UTM campaign parameter.                                                     | `summer_sale_2026`                               |
| `utm_content`      | string   | UTM content parameter.                                                      | `hero_banner`                                    |
| `utm_term`         | string   | UTM term parameter.                                                         | `cotton+tee`                                     |
| `device_type`      | string   | Detected device category.                                                   | `mobile`, `desktop`, `tablet`                    |
| `country`          | string   | ISO 3166-1 alpha-2 country code, derived from IP geolocation.               | `US`                                             |
| `region`           | string   | State or region, derived from IP geolocation.                               | `California`                                     |

## Full Event Structure

Putting it all together, here's the complete structure of an Upstack event:

```json theme={null}
{
  "event_name": "Purchase",
  "event_time": "2026-02-18T14:35:20.000Z",
  "event_id": "evt_8f3a2b1c4d5e6f7a",
  "pixel_id": "px_abc123def456",
  "session_id": "sess_9d4e5f6a7b8c",
  "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", "8012345679"],
    "content_type": "product",
    "value": 89.98,
    "currency": "USD",
    "order_id": "#1042",
    "num_items": 2
  },
  "context": {
    "page_url": "https://example-store.com/thank-you",
    "referrer": "https://example-store.com/checkout",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "utm_campaign": "summer_sale_2026",
    "device_type": "mobile",
    "country": "US",
    "region": "California"
  }
}
```

<CardGroup cols={2}>
  <Card title="Standard Events" icon="list-check" href="/data-dictionary/standard-events">
    See which properties each standard event requires and accepts.
  </Card>

  <Card title="Identity & Stitching" icon="link" href="/data-dictionary/identity-stitching">
    How identity data gets attached to events through resolution and stitching.
  </Card>
</CardGroup>