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 event Upstack captures starts with whatever identity signals the visitor provides — often just an IP address and browser cookie. Upstack ID enriches these events with resolved identity data, connecting anonymous sessions to known customers and dramatically improving the quality of data sent to your destinations.
Events that pass through identity resolution carry 3–5x more match keys on average. This directly translates to higher EMQ scores on Meta, better audience match rates on TikTok, and more accurate attribution.

​
Identity Fields on Events

After identity resolution, events carry these identity-related fields:
FieldLocationDescription
session_idEvent rootGroups all events within a single browsing session. Set by the first-party cookie.
identity_idEvent rootThe resolved Upstack identity ID. Present once the visitor has been identified.
emuser_dataSHA-256 hashed email address.
phuser_dataSHA-256 hashed phone number.
external_iduser_dataShopify customer ID or other external identifier.
fbcuser_dataMeta click ID cookie linking the session to an ad click.
fbpuser_dataMeta browser ID cookie for cross-session continuity.
ttcliduser_dataTikTok click ID for ad attribution.
gcliduser_dataGoogle click ID for ad attribution.
client_ip_addressuser_dataVisitor IP address.
client_user_agentuser_dataBrowser user agent string.

​
How Identity Attaches to Events

Identity resolution happens at the Resolve stage of the pipeline, between event capture and destination forwarding. When a visitor lands on your store, the Upstack Pixel sets a first-party cookie. Every event in that browsing session shares the same session_id. If the visitor has been seen before (returning visitor), the cookie links to their existing identity profile.

​
2. Deterministic Identification

When a visitor provides a hard identifier — logging in, entering an email at checkout, clicking a Klaviyo email link — Upstack ID creates a deterministic match:
  • The session_id is linked to the customer’s identity_id
  • em (hashed email) and ph (hashed phone) are attached to the event
  • external_id is set from the Shopify customer ID

​
3. Session Stitching

This is where the real value emerges. When identification happens mid-session (e.g., at checkout), Upstack ID retroactively enriches all prior anonymous events in that session with the resolved identity data. A typical session flow:
EventBefore StitchingAfter Stitching
PageView (homepage)IP + user agent onlyIP + user agent + em + ph + identity_id
ViewContent (product page)IP + user agent onlyIP + user agent + em + ph + identity_id
AddToCartIP + user agent onlyIP + user agent + em + ph + identity_id
InitiateCheckoutIP + user agent + em + phIP + user agent + em + ph + identity_id
PurchaseIP + user agent + em + phIP + user agent + em + ph + identity_id
Without stitching, the PageView, ViewContent, and AddToCart events would be forwarded to destinations with weak identity signals. With stitching, every event in the session carries the full set of match keys.
Session stitching is retroactive within the session. Events are held briefly in the pipeline to allow late-arriving identity data to propagate. The hold window is short enough to maintain near-real-time forwarding.

​
4. Cross-Device Linking

When the same email or phone appears across sessions on different devices, Upstack ID merges those sessions under a single identity_id. A shopper who browses on mobile and purchases on desktop is recognized as one customer. Cross-device linking enables:
  • Accurate attribution across devices
  • Larger retargeting audiences (one profile instead of two)
  • Complete customer journey visibility in analytics

​
Impact on Destination Match Quality

Identity resolution directly drives the match keys available for each destination:
DestinationKey Match FieldsTypical EMQ Without StitchingTypical EMQ With Stitching
Meta CAPIem, ph, fbc, fbp, IP, user agent3–57–9
TikTok Events APIem, ph, ttclid, IP, user agent2–46–8
Klaviyoem, phPartial profilesComplete profiles
GA4client_id, user_idAnonymous onlyIdentified users
The difference is especially pronounced for upper-funnel events (PageView, ViewContent) that typically fire before the visitor has identified themselves. Session stitching ensures these events reach destinations with full identity data.
Identity resolution depends on the visitor eventually identifying themselves within the session. Fully anonymous sessions (no login, no checkout, no email link click) cannot be resolved. The identification rate varies by store — typically 30–60% of sessions are resolved.

​
How This Connects to the Broader Pipeline

Identity resolution sits between event capture and destination forwarding:
  1. Capture — Upstack Pixel fires raw events with whatever signals are available.
  2. Resolve — Upstack ID attaches identity, stitches sessions, and links devices. (You are here.)
  3. Enrich — Product catalog data and UTM parameters are merged.
  4. Activate — Identity-enriched events are forwarded to destinations with maximum match keys.
For a deeper dive into how identity resolution works at the infrastructure level, see the Identity Resolution concept page.

Identity Resolution Concepts

How the identity graph, deterministic matching, and probabilistic signals work under the hood.

Properties & Context

Full reference for all identity fields, custom data, and context on events.