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 firePurchaseEvent for any non-Shopify native checkout.

This event must fire when a transaction is completed — once the final order details are available — typically on the Order Confirmation or Thank You page.

This is required for purchase matching in Northbeam.

firePurchaseEvent Script

You may deploy this script in

• Via Google Tag Manager
• Or hardcoded directly on your website

The event must:

• Fire once per completed order
• Fire only after the order is finalized
• Fire after the Northbeam base pixel

<script type="application/javascript">
   window.Northbeam.firePurchaseEvent({
   id: "The order ID",
   totalPrice: 100,
   shippingPrice: 10,
   taxPrice: 5.5,
   coupons: "SALE20,FAMILY10",
   currency: "USD",
   lineItems: [
     {
       productId: "SKU1",
       variantId: "VARSKU1",
       productName: "Socks",
       variantName: "Blue",
       price: 12,
       quantity: 10,
     },
     {
       productId: "SKU2",
       variantId: "VARSKU2",
       productName: "Bucket",
       variantName: "Small",
       price: 180,
       quantity: 1,
     }]
   })
</script>

firePurchaseEvent Requirements

Improper implementation will result in missing attribution.

Historical purchase data cannot be recovered.
It is critical that firePurchaseEvent is configured correctly from day one.

It is recommended that someone with basic JavaScript knowledge implement this script.

Order ID (Critical Requirement)

The Order ID is the only required non-dummy value.

We use the Order ID to match the frontend purchase event to your backend source of truth (orders sent via the Orders API).

If the Order ID does not exactly match the corresponding server-side order, that purchase will not attribute correctly.

Other Fields (Dummy Values Allowed)

All other fields may use placeholder values if necessary, including:

• totalPrice
• shippingPrice
• taxPrice
• coupons
• currency
• lineItems
• CustomerId

These values are not used as the source of truth. The corresponding order values we receive via Orders API will be reported in the dashboard.

However:

• Values must not be null or undefined
• Use 0 for numeric fields
• Use "" for string fields

If Using Google Tag Manager

• Pass order details into the Data Layer
• Create variables for the required fields
• Ensure the tag fires once per completed order

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.