What is Client-Side Purchase Tracking?

Client-Side Purchase tracking is a script used to track purchase conversion events 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 offer two scripts to track these events -- each has a different name and track a different type of checkout.

Name of Script	What it tracks	Description
Order Status Page	Shopify's Native Checkout	This script uses Shopify's macros; therefore can only be used to track Shopify's Native Checkout. Note: This does not include Shop App.
firePurchaseEvent	All Other Checkouts	This is our generic Purchase script. Used to track all Non-Shopify Checkout Experiences

Order Status Page (For Shopify Stores)

The Order Status Page script is used to track Purchase conversion events from Shopify's Native Checkout.

This script contains your dashboard's Client ID, so every dashboard has a unique script. With this mind, it's very important not to mix and match the scripts if you manage multiple dashboards.

Where to Find the Order Status Page script

In the Onboarding Flow
In the onboarding flow, find the script under the “Pixel Placement” step. After selecting and connecting Shopify, click continue and find it under “Shopify: order status page".

In the Dashboard

Navigate to Settings
Click on Tracking Script Tags
Reference the script called Shopify: order status page

Additionally, find implementation instructions within the Tracking Script Tags menu.

firePurchaseEvent (For Non-Shopify Stores)

The firePurchaseEvent script is our generic script to track Purchase conversion events from any checkout, excluding Shopify Native.

This script can be deployed through Google Tag Manager, or hardcoded on your website. Please be sure it fires at the tail end of your customer journey -- normally on your 'order confirmation page' or 'thank you page'.

firePurchaseEvent

<script type="application/javascript">
  window.Northbeam.firePurchaseEvent({
  id: "The order ID", // A unique identifier for the order that was placed. Must be unique among all orders. 
  //  for custom setups on Shopify: Make sure this is the Order Number and not the Order Name or Order ID.
  totalPrice: 100, // The total amount collected for the purchase.
  shippingPrice: 10, // Shipping fees charged to the customer for this purchase.
  taxPrice: 5.5, // Taxes charged to the customer for this purchase.
  coupons: "SALE20,FAMILY10", // A comma separated list of discount codes used.
  currency: "USD", // A 3-character ISO currency code describing totalPrice, taxPrice, and shippingPrice.
	customerId: "The customer ID", // A unique identifier for the customer who made a purchase.
  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>

Field		Type	Description
`id`	required	String	A unique identifier for the order that was placed. Must be unique among all orders. For custom setups on Shopify, make sure this is the `Order Number` and not the `Order Name` or `Order ID`.
`totalPrice`		Number	The total amount collected for the purchase.
`shippingPrice`		Number	Shipping fees charged to the customer for this purchase.
`taxPrice`		Number	Taxes charged to the customer for this purchase.
`coupons`		String	A comma separated list of discount codes used.
`currency`		String	A 3-character ISO currency code describing totalPrice, taxPrice, and shippingPrice.
`customerId`		String	A unique identifier for the customer who made a purchase.
`lineItems`		Array<Product>
`lineItems.$.productId`		String	Product identifier
`lineItems.$.variantId`		String	Variant identifier
`lineItems.$.productName`		String
`lineItems.$.variantName`		String
`lineItems.$.price`		Number
`lineItems.$.quantity`		Number

firePurchaseEvent Considerations

To make sure that your firePurchaseEvent is triggering correctly, please see the below list of considerations. Any misfires will cause a lack of tracking and attribution for any associated orders.

Any missing or incorrect historical pixel data cannot be recovered. That said, it's extremely important that your firePurchaseEvent fires correctly from day one.

It's recommended that somebody with basic Javascript knowledge sets up the script to decrease the likelihood of any issues.

Macros

The values in the script above are placeholders (ex. "The Order ID", "100", "USD"). Be sure to replace these with the corresponding macros.

If deploying via Tag Manager, these order details need to be passed to the Data Layer. From here, variables will need to be created, which can then be used within your GTM Tag.

"CustomerId"

In some instances, some of our customers do not use a CustomerId (or an equivalent value) -- for something like guest checkout. If this applies to you, please use the customer email address as a last resort.

For context, we use the Customer IDs to inform our First Time and Returning Customer data, as well as Customer LTV data, so it's very important to populate these values as accurately as possible.

Values cannot be Empty or Null

If a specific value does not exist, please pass a "blank" or 0 value -- depending if it's asking for a string or numeric value.

For example, let's say there isn't taxPrice or coupons. The Keys and Values should look like the following:

  taxPrice: 0, 
  coupons: "",

Sequencing

Please make sure the Northeam Pixel fires BEFORE the Purchase Pixel. If you're deploying via Google Tag Manager, learn more about sequencing here.

Publishing

If deploying via Google Tag Manager, please make sure the tag is published in your container.