What are Purchase Events?

Purchase conversion events are purchases that occur on your website. It's extremely important that these are captured on all your checkout flows.

How Do You Track Purchase Events?

We use a single event: firePurchaseEvent.

This event fires when a transaction is completed, typically on the Order Confirmation or Thank You page.

This payload includes order details that we match against the backend source of truth (Raw Shopify orders; Orders API data)

Tracking Purchases on Shopify Stores

This script tracks completed purchases from your Shopify Checkout. This is required for tracking Purchases in Northbeam.

Step 1: Find the Customer Events script

1. In the Onboarding Flow:
   1. Navigate to Step 7: Add Pixel
   2. Find the script called Shopify: Customer Events
2. In the Dashboard:
   1. Click on Settings
   2. Click on Northbeam Pixel and Event Tracking
   3. Find the script called Shopify: Customer Events

Step 2: Add the script in your Customer Events

1. Log into your Shopify account, click Settings
2. In the side navigation, click Customer Events
3. In the top right, click Add Custom Pixel
4. Name the pixel anything you'd like (e.g. "Northbeam Event Tracking”), then click Add Pixel
5. Paste the script into the code editor
6. In the top right corner, click Save
7. Below the editor, click Connect
8. In the modal, click Connect to give the pixel secure access to your online store, checkout, and order confirmation.

Step 3: Change data access settings

1. From your Shopify admin, go to Settings > Customer events.
2. Click the App pixels tab.
3. For the Northbeam pixel, click the pixel's current data access setting in the Data column.
4. In the dialog, select Always on, and then click Apply.

Step 4: Customer Privacy

Under Customer Privacy, ensure a consent banner is configured.

If data restrictions are enabled without a banner:

• Users cannot opt in
• Tracking may be blocked
• The Customer Events script may not fire
• Conversion tracking may break

Always confirm privacy settings and consent are aligned before going live.

Step 5: Notify Northbeam

Once the script is installed, submit a support ticket to let our team know. We'll finalize setup to ensure accurate page view tracking.

🚧

Important:

Failing to notify our team may result in incorrect page view tracking.

Page view tracking is a foundational event in Northbeam's conversion tracking system — without it, purchase attribution may be incomplete or inaccurate.

Tracking Purchases on Non-Shopify Stores

Use the window.Northbeam.fireSlimPurchaseEvent OR window.Northbeam.firePurchaseEvent Northbeam Pixel JavaScript function for any non-Shopify native checkout. These functions equally signal that a conversion has taken place within the visitor's session, but the target function to use depends on your usage intent, available fields, and actionability requirements.

Either event must fire when a transaction is completed — once the final order details are available — typically on the Order Confirmation or Thank You page. A timely and proper trigger is required for purchase matching in Northbeam, and they can be deployed natively into your site's code or injected externally via Google Tag Manager.

Global Requirements (both fireSlimPurchaseEvent and firePurchaseEvent)

Your chosen function must:

• Fire after the core Northbeam base pixel.
• Fire only after the order is finalized and all charges have been processed to prevent ingestion of cancelled transactions.
• Fire once per completed order; do not repeat id values.
• Contain all corresponding keys with defined values. NULL values are invalid.

Critical: id = order_id

We use the value from the id key (Please see function requirements below) to match the frontend purchase event (fireSlimPurchaseEvent AND/OR firePurchaseEvent) to your backend source of truth (orders sent via the Northbeam Orders API).

If the value does not exactly match the corresponding server-side order (Case-sensitive): that purchase will not attribute correctly. It is strongly recommended that someone with basic JavaScript knowledge implements these scripts.

Important: Historical purchase data cannot be recovered. An improper implementation will result in missing attribution. Thus: It is critical that fireSlimPurchaseEvent / firePurchaseEvent is configured correctly from day one.

window.Northbeam.fireSlimPurchaseEvent

Definitions

This lightweight function signals that the order/transaction number passed in the id field is a valid conversion that should be attributed. It only requires a single value for activation. This is ourprimary recommended function for most* implementations.

fireSlimPurchaseEvent example

<script type="application/javascript">
  window.Northbeam.fireSlimPurchaseEvent("A123" || "Missing - unmatched order")
</script>

• Note: The id key/field is an implicit parameter in fireSlimPurchaseEvent and does not need to be externally defined for the function to operate. It only needs a value, which is automatically mapped to the implicit id key.

Considerations

• fireSlimPurchaseEvent does not process monetary values and is therefore not recommended when operational actionability is a crucial consideration -AND- your corresponding backend Northbeam API upsert implementation is not synchronized to your Dashboard processing cycles. On such cases: firePurchaseEvent is best used instead of fireSlimPurchaseEvent.

window.Northbeam.firePurchaseEvent

Definitions

This full-fledged function not only signals that the order/transaction number passed in the id field is a valid conversion that should be attributed, but it also contains transactional information that is actionable for revenue, tax, and shipping calculations in your Northbeam Dashboard. This function requires a full transactional object {} with distinct keys rather than the order_id string alone, which increases complexity and should only be used when actionable data is a crucial concern -AND- your corresponding backend Northbeam API upsert implementation is not synchronized to your Dashboard processing cycles.

firePurchaseEvent example

<script type="application/javascript">
  window.Northbeam.firePurchaseEvent({
  id: "ORD98" || "Missing - unmatched order",
  totalPrice: 100 || 0,
  shippingPrice: 10 || 0,
  taxPrice: 5.5 || 0,
  coupons: "SALE20, FAMILY10" || "",
  currency: "USD" || "USD",
  customerId: "customer-93" || "UNKNOWN VISITOR",
  lineItems: [
    {
      productId: "SKU-0001" || "UNKNOWN PRODUCT",
      variantId: "0001-A" || "",
      productName: "Pants" || "UNKNOWN VARIANT",
      variantName: "Blue" || "",
      price: 10 || 0,
      quantity: 1 || 0,
    }]
	})
</script>

• Note: The payload must be structured as an object and thus wrapped in curly brackets {}.

Considerations

• Values from totalPrice, shippingPrice and taxPrice will directly power Northbeam Dashboard metrics tied to revenue, shipping, and taxes respectively.
• The Northbeam Orders API is the ultimate source of truth. In case of a value conflict with the corresponding order_id payload: Values from firePurchaseEvent will be overwritten and replaced by the Northbeam API value.
• Timely/synchronized Northbeam Orders API upserts negate the need to use firePurchaseEvent. We recommend using fireSlimPurchaseEvent with synchronized API Upserts when possible.

Validation and testing

A valid/fully-compliant event trigger for either fireSlimPurchaseEvent or firePurchaseEvent shows a network request (nb-collector) with a payload containing the data object ue (data: [{e: "ue",…}]) alongside second payload containing the data object se (data: [{e: "se",…}]). The se_la key of the se object contains the order number we received .

These 2 events and network requests are only ever seen together as requests when the trigger is valid.

These events can can only be reviewed if the network console is open before the event fires. They can not be reviewed after the fact.

Sequencing

The Northbeam base pixel must fire before firePurchaseEvent.

If deploying via Google Tag Manager, configure tag sequencing correctly: https://support.google.com/tagmanager/answer/6238868?hl=en

Improper sequencing may prevent the purchase event from registering.

Publishing

If deploying via Google Tag Manager:

• Ensure the tag is configured correctly
• Publish the container

Unpublished containers will prevent tracking.

Final Checklist

Before going live, confirm:

• firePurchaseEvent fires on the confirmation page
• It fires once per order
• The Order ID matches backend data exactly (Orders API)
• The base pixel fires first
• GTM container is published

If these conditions are met, purchase matching will function correctly.