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.

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

​
User Data

Identity signals attached to each event. These fields drive destination match quality (EMQ) and enable cross-device identity resolution.
FieldTypeDescriptionExample
emstringSHA-256 hashed email address. Lowercase and trimmed before hashing.a1b2c3d4e5f6...
phstringSHA-256 hashed phone number. E.164 format before hashing (e.g., +15551234567).f6e5d4c3b2a1...
client_ip_addressstringVisitor’s IP address. Captured server-side by the edge API.203.0.113.42
client_user_agentstringBrowser user agent string.Mozilla/5.0 (Macintosh; Intel...)
fbcstringMeta click ID cookie (_fbc). Contains the fbclid from the ad click URL.fb.1.1708271400.AbC123
fbpstringMeta browser ID cookie (_fbp). First-party cookie set by the Meta pixel.fb.1.1708271400.XyZ789
external_idstringYour unique customer identifier (e.g., Shopify customer ID). Hashed before forwarding.cust_12345
ttclidstringTikTok click ID. Captured from the ad click URL parameter.E.C.P.abc123def456
gclidstringGoogle click ID. Captured from the ad click URL parameter.CjwKCAjw...
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.

​
Custom Data

Event-specific properties that describe what happened. Which fields are relevant depends on the event type.
FieldTypeDescriptionApplicable Events
valuenumberMonetary value of the event (e.g., cart total, order revenue).AddToCart, InitiateCheckout, Purchase, Lead, Subscribe, StartTrial
currencystringISO 4217 currency code.Any event with value
content_idsstring[]Array of product or variant IDs involved in the event.ViewContent, AddToCart, InitiateCheckout, Purchase, Search
content_typestringType of content: "product" or "product_group".ViewContent, AddToCart, InitiateCheckout, Purchase
content_namestringHuman-readable name of the product, collection, or form.ViewContent, Lead, CompleteRegistration, StartTrial
num_itemsnumberTotal number of items in the cart or order.AddToCart, InitiateCheckout, Purchase
order_idstringUnique order identifier (Shopify order ID or name).Purchase
search_stringstringThe search query entered by the visitor.Search
page_titlestringHTML <title> of the page where the event fired.PageView
referrerstringThe referring URL that led the visitor to the current page.PageView
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.

​
Context

Automatic metadata captured by the Upstack Pixel and edge API. These fields are present on every event.
FieldTypeDescriptionExample
event_source_urlstringFull URL of the page where the event fired.https://example-store.com/products/classic-tee
event_timeISO 8601Timestamp when the event occurred, in UTC.2026-02-18T14:30:00.000Z
page_urlstringCanonical page URL (without query parameters).https://example-store.com/products/classic-tee
page_titlestringHTML document title at the time of the event.Classic Cotton Tee | Example Store
referrerstringHTTP referrer header value.https://www.google.com/
user_agentstringRaw user agent string from the HTTP request.Mozilla/5.0 (Macintosh; Intel Mac OS X...)
ip_addressstringClient IP address as seen by the edge API.203.0.113.42
pixel_idstringYour Upstack Pixel ID. Identifies which store the event belongs to.px_abc123def456
event_idstringUnique event identifier for deduplication.evt_8f3a2b1c...
session_idstringUpstack session identifier. Groups events within a single browsing session.sess_9d4e5f6a...
utm_sourcestringUTM source parameter from the landing page URL.facebook
utm_mediumstringUTM medium parameter.cpc
utm_campaignstringUTM campaign parameter.summer_sale_2026
utm_contentstringUTM content parameter.hero_banner
utm_termstringUTM term parameter.cotton+tee
device_typestringDetected device category.mobile, desktop, tablet
countrystringISO 3166-1 alpha-2 country code, derived from IP geolocation.US
regionstringState or region, derived from IP geolocation.California

​
Full Event Structure

Putting it all together, here’s the complete structure of an Upstack event: 
{
  "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"
  }
}

Standard Events

See which properties each standard event requires and accepts.

Identity & Stitching

How identity data gets attached to events through resolution and stitching.