Identify Events

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

Requirements

Before you start, confirm that:

The Northbeam 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, 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.

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:

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

In Google Tag Manager:

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

window.Northbeam.identify("email", "{{dlv - customer_email}}");

Set the trigger to fire on the checkout page where the email is entered.
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.

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

`identify` reference

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

// 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 improves match rates.

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

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.

The ID must exactly match the customer_id on the order. If it doesn’t, the match fails.

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

Purchase Events: tracking purchases when the order ID is available
Order Definition (Orders API): every order field, including customer_email
Troubleshooting Pixel Tracking
Data Appears as Organic, Other, or Unattributed

Overview

Set up your account

Install tracking

Pixel and events

Add orders

Add spend

Which setup you need

Requirements

Set up identify

Step 1: Add the pixel to your checkout pages

Step 2: Call identify when the email is known

Step 3: Send customer_email with every order

`identify` reference

`identifyCustomerId`

Troubleshooting

​Which setup you need

​Requirements

​Set up identify

​Step 1: Add the pixel to your checkout pages

​Step 2: Call identify when the email is known

​Step 3: Send customer_email with every order

​identify reference

​identifyCustomerId

​Troubleshooting

​Related

Which setup you need

Requirements

Set up identify

Step 1: Add the pixel to your checkout pages

Step 2: Call identify when the email is known

Step 3: Send customer_email with every order

`identify` reference

`identifyCustomerId`

Troubleshooting

Related