> ## Documentation Index
> Fetch the complete documentation index at: https://docs.northbeam.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Identify Events

> Link a visitor to their email so orders can be attributed when the order ID isn't available in the browser.

`identify` links a visitor's browser session to their **email address**. When the order reaches Northbeam from your backend, Northbeam matches it to that session by email, instead of by order ID.

Use it when your checkout can't give the order ID to the browser. The most common case is a **third-party checkout provider**, such as CheckoutChamp, CartHook, or Purple Dot.

## Which setup you need

Most stores track purchases with a [purchase event](/docs/purchase-pixel), which sends the order ID from the confirmation page. If your checkout can't do that, those orders show as **unattributed**. `identify` fixes this.

| Your checkout | What to use |
| :- | :- |
| Passes the order ID to the confirmation page | [Purchase Events](/docs/purchase-pixel). You don't need this page. |
| Can't pass the order ID (most third-party checkouts) | `identify`. **Follow this page.** |

`identify` works the same way on Shopify and custom stores.

<span id="prerequisites" style={{ display: "block", scrollMarginTop: "7rem" }} />

## Requirements

Before you start, confirm that:

* The [Northbeam Pixel](/docs/add-pixel) is on every page, **including your checkout pages**.
* Your checkout is on the **same root domain** as your store. For example, `checkout.yourstore.com` works. A completely different domain does not.
* Every order sent to Northbeam includes `customer_email`.
* You can add scripts to the checkout pages, either in code or through Google Tag Manager.

***

## Set up identify

### Step 1: Add the pixel to your checkout pages

The Northbeam Pixel must run on **every page**, including pages served by your checkout provider. Without it, there's no session for `identify` to attach to.

If your checkout runs on a subdomain (for example, `checkout.yourstore.com`), install the pixel there too. Use the same script and steps from your [platform guide](/docs/add-pixel#which-setup-you-need), and confirm your Content Security Policy allows traffic to your `i.` subdomain.

### Step 2: Call identify when the email is known

Call `identify` on the checkout step where the customer first enters their email, usually the contact or information step. The earlier it fires, the more orders Northbeam can match.

```javascript theme={null}
window.Northbeam.identify("email", "customer@example.com");
```

Replace `customer@example.com` with the customer's email. It usually comes from a template variable or the data layer.

**In your site's code**, use your platform's template variable:

```html theme={null}
<script type="application/javascript">
  // Replace {{ customer.email }} with your platform's template syntax
  window.Northbeam.identify("email", "{{ customer.email }}");
</script>
```

**In Google Tag Manager:**

1. Create a **Data Layer Variable** for the customer's email (for example, `dlv - customer_email`).
2. Create a **Custom HTML** tag with this script:

```javascript theme={null}
window.Northbeam.identify("email", "{{dlv - customer_email}}");
```

3. Set the trigger to fire on the checkout page where the email is entered.
4. **Publish** the container.

### Step 3: Send customer\_email with every order

Northbeam matches by email, so `customer_email` is **required** on every order.

* **Custom (Orders API):** include `customer_email` in the payload.

```json theme={null}
{
  "id": "12345",
  "customer_email": "customer@example.com",
  "total_price": 99.00,
  "currency": "USD"
}
```

* **Shopify:** Northbeam pulls the email from the Shopify order. Check that orders in your Shopify admin have an email.

***

<span id="identify-argument-reference" style={{ display: "block", scrollMarginTop: "7rem" }} />

## `identify` reference

You can send the email as plain text or as a SHA-256 hash.

```javascript theme={null}
// Plain-text email
window.Northbeam.identify("email", "john.smith@gmail.com")

// Hashed email
window.Northbeam.identify(
  "hashed_email",
  "1bb931a0c4488a629e0eb571988b87811c27338ad90888376567c7bce0419e5a"
);
```

| Argument | | Type | Description |
| :- | :- | :- | :- |
| 1 | *required* | String | `"email"` or `"hashed_email"` |
| 2 | *required* | String | The email address, or the SHA-256 hash of the normalized email (64 lowercase hex characters) |

**Use plain-text `"email"` when you can.** We normalize and hash it for you. Use `"hashed_email"` only if your privacy policy doesn't allow sending plain-text emails to third parties.

If you hash the email yourself, trim spaces and lowercase it first. Following the full [normalization guidelines](/docs/hashing-customer-data) improves match rates.

<span id="advanced-identifycustomerid" style={{ display: "block", scrollMarginTop: "7rem" }} />

## `identifyCustomerId`

If you'd rather not send email addresses, use `identifyCustomerId`. It links the session to the customer's ID from your order management system, with no personal information shared.

```javascript theme={null}
window.Northbeam.identifyCustomerId("custom", "1234567890");
```

| Argument | | Type | Description |
| :- | :- | :- | :- |
| 1 | *required* | String | Where the ID comes from. Use `"custom"` for the Orders API, or `"shopify"` for Shopify. |
| 2 | *required* | String | The customer ID. Must exactly match the `customer_id` on your Northbeam orders. |

<Warning>
  The ID must **exactly match** the `customer_id` on the order. If it doesn't, the match fails.
</Warning>

***

## Troubleshooting

| Problem | Likely cause | Fix |
| :- | :- | :- |
| Third-party checkout orders still unattributed | `identify` isn't firing, or `customer_email` is missing from the order | Confirm `identify` fires before checkout completes, and that orders include `customer_email` |
| `identify` fires but orders don't match | The email in the browser doesn't match the email on the order | Make sure both use the same email |
| Pixel not found on checkout pages | The pixel isn't installed on the checkout domain or subdomain | Install the pixel on the checkout pages |

## Related

* [Purchase Events](/docs/purchase-pixel): tracking purchases when the order ID is available
* [Order Definition (Orders API)](/docs/order-definition): every order field, including `customer_email`
* [Troubleshooting Pixel Tracking](/docs/guide-to-troubleshooting-pixel-tracking)
* [Data Appears as Organic, Other, or Unattributed](/docs/differences-in-unattributed-data)