Purchase Events

A purchase event tells Northbeam that an order was completed in the visitor’s browser. Northbeam matches it to the order you send from your backend (through Shopify or the Orders API) and uses it to attribute that order. Every checkout flow on your site needs a purchase event. If one is missing, orders from that flow show as unattributed.

Which setup you need

Your store	How purchases are tracked
Shopify	Automatically, by the Northbeam Custom Pixel. Set it up in Shopify, step 2. You don’t need anything on this page.
Shopify checkout, custom backend	By the Northbeam Custom Pixel, with one line changed so it sends the order ID. See Shopify + Custom.
Custom	Add `fireSlimPurchaseEvent` to your order confirmation page. Follow this page.
Third-party checkout that can’t pass the order ID	Use `identify` instead. See Identify Events.

Choose a function

Use fireSlimPurchaseEvent. It sends only the order ID, which is all Northbeam needs. Northbeam uses the order ID to match the purchase to your backend order. Revenue, tax, shipping, and line items always come from your backend order data (through Shopify or the Orders API), never from the browser.

Function	What it sends	Use it?
`fireSlimPurchaseEvent`	The order ID	Yes. Recommended for every store.
`firePurchaseEvent`	The order ID plus order details	Still supported, but only the order ID is used. No need to switch if you already have it working.

Fire the function on the Order Confirmation or Thank You page, after the order is complete. You can add it to your site’s code or through Google Tag Manager.

Requirements

Whichever function you use, it must:

Fire after the Northbeam Pixel has loaded.
Fire only after the order is final and payment has been processed. This keeps cancelled transactions out.
Fire once per order. See Fire once per order.
Use the exact order ID your backend sends to Northbeam. See Match the order ID exactly.

Purchase data can’t be recovered later. If the event is set up incorrectly, those orders will be missing attribution. We strongly recommend that someone with basic JavaScript experience sets this up.

Match the order ID exactly

Northbeam uses the id value to match the purchase event to your backend order (the order_id you send through the Orders API). The two values must match exactly, including capitalization. If they don’t, the purchase won’t attribute.

Fire once per order

Your purchase event must fire exactly once for each order. If it fires more than once for the same order, Northbeam may not match the purchase to your backend order, and the order can show as unattributed.

Sending the same order more than once does not improve tracking. Duplicate purchase events can cause the order to lose its attribution.

Common causes of duplicate fires:

The customer refreshes or revisits the Order Confirmation page (for example, from a bookmark or a link in the confirmation email).
The script is installed twice (for example, hard-coded on the site and added in Google Tag Manager).
A Google Tag Manager trigger fires on more than one event (for example, both Page View and DOM Ready).
A single-page checkout re-renders the confirmation step.

To prevent this, make sure your checkout only fires the purchase event the first time the confirmation page loads for an order. Later page loads for the same order should not fire it again.

`fireSlimPurchaseEvent`

Sends only the order ID. This is the recommended function for every store.

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

Replace "A123" with the variable that holds your order ID. Pass the value directly. You don’t need to wrap it in an object.

Value	Type	Description	Example
`id`	String	The order number. Must exactly match the `order_id` in the Orders API. At least 1 character. Case-sensitive.	”A123”

You don’t need to send revenue or other order details. Northbeam gets those from your backend order data.

`firePurchaseEvent`

The original purchase function. It sends the order ID plus order details like revenue, tax, shipping, and line items. Northbeam only uses the order ID from this event. The other fields aren’t used for reporting, because order details come from your backend. If you’re setting up purchase tracking now, use fireSlimPurchaseEvent instead. If you already use firePurchaseEvent and it works, you don’t need to change it.

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

id is the only required field. It must exactly match the order_id in the Orders API. For other fields, an empty string ("") or 0 is fine when a value doesn’t apply. Avoid null.

Field reference

Order fields

Field	Type	Description	Example
`id`	String	The order number. Must exactly match the `order_id` in the Orders API. At least 1 character. Case-sensitive.	”ORD98”
`totalPrice`	Number	The final amount paid, after taxes, shipping, and discounts. Must be a positive number.	12
`shippingPrice`	Number	Shipping charges. Must be a number, zero or more.	6
`taxPrice`	Number	Tax charges. Must be a number, zero or more.	7
`coupons`	String	Coupons applied to the order. Use one string; separate multiple coupons with commas (for example, `"coupon 1, coupon 2"`).	”PROMO 4”
`currency`	String	The 3-letter ISO 4217 currency code.	”USD”
`customerId`	String	The customer’s ID. At least 1 character.	”VICTOR12”
`lineItems`	Array of objects	One array, with one object per product. Each object needs every line item field below.	See below

Line item fieldsThese fields go inside each object in lineItems. They can’t be used outside it.

Field	Type	Description	Example
`productId`	String	The parent product’s ID. At least 1 character.	”SKU-01”
`variantId`	String	The variant’s ID, if the product has variants.	”VAR-01”
`productName`	String	The product name. At least 1 character.	”Hat”
`variantName`	String	The variant name, if the product has variants.	”Green Hat”
`price`	Number	The item’s gross price. Must be a positive number.	12
`quantity`	Number	How many of this item were purchased. Must be a positive number.	2

Validation and testing

Open your browser’s Network tab before you complete a test order. The requests can’t be reviewed after the fact. When the event fires correctly, you’ll see two nb-collector requests together:

One with a payload containing data: [{e: "ue",…}]
One with a payload containing data: [{e: "se",…}]. Its se_la value is the order number Northbeam received.

You only see these two requests together when the event is valid. To confirm the event fires only once, refresh the confirmation page with the Network tab open. You should not see a second nb-collector request for the same order number.

Google Tag Manager

If you add the purchase event through Google Tag Manager:

Sequence your tags. The Northbeam Pixel tag must fire before the purchase event tag. See Google’s guide to tag sequencing.
Use one trigger. Make sure the tag fires on a single event, so it doesn’t fire twice.
Publish the container. Unpublished changes don’t track anything.

Final checklist

Before going live, confirm:

The purchase event fires on the confirmation page
It fires exactly once per order, and refreshing the confirmation page does not fire it again
The order ID matches your backend order data exactly
The Northbeam Pixel fires first
Your Google Tag Manager container is published (if you use it)

Best practices

Log success and failure. Wrap the purchase function in code that logs whether it ran. This makes testing much easier.
Wait for the pixel. Check that window.Northbeam is ready before calling the function, and retry if it isn’t. This prevents load-order problems.

Example with logging and retry

<script type="application/javascript">
(function northbeamPurchaseRetry() {

    function attemptPurchaseEvent() {
        if (
            window.Northbeam &&
            typeof window.Northbeam.fireSlimPurchaseEvent === 'function'
        ) {
            console.log('Northbeam fireSlimPurchaseEvent fired');

            window.Northbeam.fireSlimPurchaseEvent(
                "A123" || "Missing - unmatched order"
            );

            console.log('Northbeam fireSlimPurchaseEvent successful');
        } else {
            console.log('Northbeam fireSlimPurchaseEvent not ready, retrying in 3 seconds...');

            setTimeout(attemptPurchaseEvent, 3000);
        }
    }

    attemptPurchaseEvent();

})();
</script>

Custom: full setup for custom stores
Identify Events: when your checkout can’t pass the order ID
Purchases or Orders Are Missing: troubleshooting unattributed orders

Overview

Set up your account

Install tracking

Pixel and events

Add orders

Add spend

Which setup you need

Choose a function

Requirements

Match the order ID exactly

Fire once per order

`fireSlimPurchaseEvent`

`firePurchaseEvent`

Validation and testing

Google Tag Manager

Final checklist

Best practices

Example with logging and retry

​Which setup you need

​Choose a function

​Requirements

​Match the order ID exactly

​Fire once per order

​fireSlimPurchaseEvent

​firePurchaseEvent

​Validation and testing

​Google Tag Manager

​Final checklist

​Best practices

​Example with logging and retry

​Related

Which setup you need

Choose a function

Requirements

Match the order ID exactly

Fire once per order

`fireSlimPurchaseEvent`

`firePurchaseEvent`

Validation and testing

Google Tag Manager

Final checklist

Best practices

Example with logging and retry

Related