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

# Identity Resolution and Session Stitching

> How Upstack ID attaches resolved identity to events, stitches anonymous sessions, and improves destination match quality.

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.

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

## Identity Fields on Events

After identity resolution, events carry these identity-related fields:

| Field               | Location    | Description                                                                        |
| ------------------- | ----------- | ---------------------------------------------------------------------------------- |
| `session_id`        | Event root  | Groups all events within a single browsing session. Set by the first-party cookie. |
| `identity_id`       | Event root  | The resolved Upstack identity ID. Present once the visitor has been identified.    |
| `em`                | `user_data` | SHA-256 hashed email address.                                                      |
| `ph`                | `user_data` | SHA-256 hashed phone number.                                                       |
| `external_id`       | `user_data` | Shopify customer ID or other external identifier.                                  |
| `fbc`               | `user_data` | Meta click ID cookie linking the session to an ad click.                           |
| `fbp`               | `user_data` | Meta browser ID cookie for cross-session continuity.                               |
| `ttclid`            | `user_data` | TikTok click ID for ad attribution.                                                |
| `gclid`             | `user_data` | Google click ID for ad attribution.                                                |
| `client_ip_address` | `user_data` | Visitor IP address.                                                                |
| `client_user_agent` | `user_data` | Browser user agent string.                                                         |

## How Identity Attaches to Events

Identity resolution happens at the **Resolve** stage of the pipeline, between event capture and destination forwarding.

### 1. First-Party Cookie Matching

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:

| Event                      | Before Stitching              | After Stitching                               |
| -------------------------- | ----------------------------- | --------------------------------------------- |
| PageView (homepage)        | IP + user agent only          | IP + user agent + `em` + `ph` + `identity_id` |
| ViewContent (product page) | IP + user agent only          | IP + user agent + `em` + `ph` + `identity_id` |
| AddToCart                  | IP + user agent only          | IP + user agent + `em` + `ph` + `identity_id` |
| InitiateCheckout           | IP + user agent + `em` + `ph` | IP + user agent + `em` + `ph` + `identity_id` |
| Purchase                   | IP + user agent + `em` + `ph` | IP + 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.

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

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

| Destination           | Key Match Fields                         | Typical EMQ Without Stitching | Typical EMQ With Stitching |
| --------------------- | ---------------------------------------- | ----------------------------- | -------------------------- |
| **Meta CAPI**         | `em`, `ph`, `fbc`, `fbp`, IP, user agent | 3–5                           | 7–9                        |
| **TikTok Events API** | `em`, `ph`, `ttclid`, IP, user agent     | 2–4                           | 6–8                        |
| **Klaviyo**           | `em`, `ph`                               | Partial profiles              | Complete profiles          |
| **GA4**               | `client_id`, `user_id`                   | Anonymous only                | Identified 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.

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

## 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](/data-dictionary/identity-resolution) concept page.

<CardGroup cols={2}>
  <Card title="Identity Resolution Concepts" icon="fingerprint" href="/data-dictionary/identity-resolution">
    How the identity graph, deterministic matching, and probabilistic signals work under the hood.
  </Card>

  <Card title="Properties & Context" icon="table" href="/data-dictionary/properties-and-context">
    Full reference for all identity fields, custom data, and context on events.
  </Card>
</CardGroup>