Regardless of your eCommerce platform (Shopify, WooCommerce, Magento, Custom, etc), all brands will need to begin our standard setup flow in order to create a Northbeam dashboard.

Before starting, there are a couple things to keep in mind.

Website Domain(s)

If you have multiple storefronts on different domains (subdomains or top-level) – for international stores, for example – and you’d like to onboard with all, it may make sense to create separate Northbeam dashboards for each store.

✏️ NOTE: This highly depends on the checkout flows of each store (shared or separate) and preferred reporting segmentation.

Please contact our Customer Success Team for any guidance here.

Checkout Flow(s)

If you use any other checkout flows or sales channels (ex. ClickFunnels), please contact our Customer Success Team – as we need to determine if it’s trackable by our system and if so, the appropriate scripts to use.

✏️ NOTE: Payment gateways such as PayPal and ShopPay are not considered checkout flows in themselves, but rather additional payment options available within the checkout process. We should be able to track these just fine.

If we discover any additional setup needed along the way, we can always schedule a call to evaluate.

Setup Requirements

To begin, sign up for an account at dashboard.northbeam.io.

This will create a Northbeam dashboard. Only one user needs to sign up for an account. If you need to add additional users or teammates, you’ll be able to once you’re in the onboarding flow.

Here are a few things to have handy to speed up the onboarding process:

Payment information (credit card)
Login credentials for connected platforms (i.e. Facebook, Klaviyo, TikTok, etc.)
Access to your domain provider (i.e. GoDaddy, Google Domains, BlueHost, Squarespace, etc.)
Admin access site tracking provider (i.e. Google Tag Manager) for placement of head tags and other scripts

If you don’t have access to any of these items, you can always add teammate(s) to your account who do.

Step 1: Enter Website Domain

Please enter your website’s top-level domain. It will look something like northbeam.io, google.com, or bbc.co.uk.

If you have multiple storefronts with different domains – top-level domain or subdomain (ex. mystore.com, us.mystore.com, mystore.co.uk) – please contact our Customer Success Team for guidance on the best path forward.

The setup here is highly dependent on whether each store has its own checkout flow and/or own order table. Once our team fully understands your setup, we’ll advise on the best path forward.

Step 2: Basic Details

Enter your basic company details

This information will be displayed in your dashboard and is required in order to activate your dashboard.

Bookmark the Knowledge Base

This is Northbeam’s repository of information that contains articles, documentation, tutorials, FAQs, and other resources that help users learn about and effectively use the Northbeam dashboard.

Return to Table of Contents

Step 3: Add the Pixel and Orders Sync

Integrating Northbeam with a custom setup involves a two-part process.

The frontend aspect requires the setup of our website conversion pixel and purchase event. This step enables us to receive essential data such as Pixel data, customer journeys, touchpoints, IP addresses, and cookies for channel attribution. By implementing this function, we can effectively track and analyze customer interactions on your website.

On the backend, we utilize a backend API call to send the corresponding order details to our database. This POST request provides us with important information such as revenue, historical orders, customer lifetime value (LTV), and unique customer ID identification. This data integration ensures accurate order tracking and attribution.

Both the frontend and backend setups work in harmony to properly attribute and track your orders. It's important to note that both components are necessary as they complement each other, creating a comprehensive and accurate system for order tracking and analysis.

Connect the Platform - During the 'Pixel Placement' step, make sure to select 'Other' as the platform. This selection is important as it allows you to customize the setup according to your specific needs and preferences.

By choosing the 'Other' platform, you will be directed to the necessary scripts and tools within the Northbeam dashboard. These resources enable you to generate a Client ID and API Key, both of which are essential for the setup process.

Frontend Setup

To ensure proper implementation of Northbeam on your site, the following scripts need to be added:

Northbeam Pixel - This is to be placed on the header of your site. It can be hardcoded in your global theme, or deployed via GTM. This script initializes the Northbeam tracking library, sets up the client ID, and tracks page views on your website.

The script is generated once the onboarding flow is started.

If you’re in the onboarding flow, find the script under “Pixel Placement” – called ‘Northbeam Pixel’
If your account is activated, find the script under Settings > Tracking Script Tags – called ‘Northbeam Pixel’

✏️ NOTE: This script is mandatory and all other Northbeam scripts rely on this to function properly.

💡TIP: Be sure this script is firing on every page on your top-level domain – even any landing pages that may be on a subdomain.

2. Conversion Pixel (firePurchaseEvent) - Find our firePurchaseEvent here. This Javascript snippet needs to fire after every order is completed. Usually on the confirmation page. This is how we track Purchase events; failure to trigger this script will result in no attribution

By including this snippet on your confirmation page, you trigger the firePurchaseEvent function, which sends the necessary data to Northbeam for tracking and attribution of purchase events. Make sure this script is executed after a successful order completion to capture the accurate purchase event information.

✏️ NOTE:

All variables need to be filled for the script to fire. This script does not accept partial fields.
There can be '0' values (except in the “id” field), but not null
The ‘customerId” field cannot be a dummy value
The values are CASE SENSITIVE. Expected to be lower case

TrackPageView

✏️ NOTE: If you have a single page application (SPA) website setup, we will need a secondary script called trackPageView.

Return to Table of Contents

Step 4: Orders Sync

Backend Setup - Setting Up Order Sync API

For the backend setup of Northbeam, you need to make an API call to send orders from your database. We use this endpoint to calculate revenue, LTV, and separate unique Customer IDs.

It is a JSON object that expects the same values as the firePurchaseEvent, but the names of the keys are slightly different.

For example:

Orders API	firePurchaseEvent
order_id	id
customer_id	customerId
purchase_total	totalPrice

✏️ NOTE:

Use our API guide as a point of reference
Reference the list of Objects that need to be called

Send the orders to your specific Data-Client-ID and API Key. You can find both in your dashboard, under the Pixel Placement section.

Data-Client-ID: xxxxxxxxxxxxxx
API Key: xxxxxxxxxxxxx

Where to send - Send to the following endpoint: https://api.northbeam.io/v1

Required Objects:

Time of Purchase - The timezone is expected to be formatted to ISO 8601 and must be adjusted to UTC and cannot be earlier than the firePurchaseEvent for the same transaction. This object is often a problem for clients
Order ID - This must be a universal id that must be unique across all of your existing orders. It should exactly match the ID that you send using firePurchaseEvent if that is a part of your workflow. For documentation on firePurchaseEvent please review our Northbeam Pixel API. This must not be the customer ID.
Customer ID - This must be a universal id that must be unique across all of your existing customers. The internal customer ID. This must not be the order ID. Email address can be used as a last resort, but not recommended.
Tax - The tax amount in the currency of the order
Currency - The currency of the order. Note, all subsequent fields will assume that the currency is the one passed in this field. Please use standard ISO-4217 currency codes
Purchase Total - The amount of money collected from the customer (including taxes, shipping, and other fees) in the currency of the order.
Products - A list of objects describing the products in the order
- Product ID - A unique identifier describing the product in the order
- Product Name - The name of the product
- Quantity - How many of this product was sold in the order
- Price - The price of the product in the currency of the order

Additional Objects:

Order Tags - A list of internal tags describing the order.

This is very important. Order tags are used to label and exclude certain un-trackable orders, which is a part of our Data Validation process.

There are orders that we don’t expect to track because our pixel doesn’t fire during the checkout process. This refers to any order that isn’t completed on your website

Common examples:

Replacement orders
Orders added manually through the backend
First-Time Subscription orders
- We please ask to tag these orders, even though these take often do happen on your website
Recurring Subscription orders

✏️ NOTE: Please label these types of orders with tags - as this will help us differentiate between the trackable and un-trackable orders. Once tagged, we’ll exclude the un-trackable from the Data Validation. The goal of this is to ensure all trackable orders are getting tracked.

Discount Codes - A list of discount codes used in the order

- Helpful for orders table in the dashboard

✏️ NOTE: Amending Data -For any scenarios where you need to amend the order data (ex. refunds, change customer ID), you can send updated information in a new call. Our order tables will use the most up-to-date data.

Other Considerations:

Ensure that the firePurchaseEvent fires before the API call
The Customer ID and Order ID fields on firePurchase and API call need to match in order to properly attribute
Frequency - These do not need to be sent in real time. We recommend batching & queuing them and pushing 100 orders at a time, or once every hour – whichever happens first.
We cannot have duplicate Product IDs within the same order. Please use the quantity field to indicate multiple units of the same product.
- For example, if someone ordered two of the same product, please send one array and adjust the quantity to “2”, instead of duplicating the entire array
Should I send new AND historical orders? YES
- We strongly advise sending all orders (new and historical). Although the historical orders will not be attributed, this data is necessary to have accurate Customer LTV and New vs. Returning metrics (ex. nCAC, nROAS) within Northbeam.

Return to Table of Contents

Testing Order Sync API

Feel free to send test orders to: https://api.dev.northbeam.io

✏️ NOTE: Orders sent to the testing end point are not upserted or saved, it’s simply validating the structure of the API call

Once the test orders are sent, you’ll receive a message containing “validation passed” if test is successful
If a test order has failed, an error message will display which values need to be corrected

Return to Table of Contents

Step 5: Setup the DNS

Setting up a DNS entry improves our ability to track your customers when they return to your website after their first visit.

In your domain provider, create an A Record, named ‘i’, pointing to a specific address you’ll find in your dashboard. This allows first party tracking.

If the subdomain ‘i’ is already mapped to something, please get in touch with us so we can help you pick a different subdomain name.

There are instructions provided in the onboarding flow for multiple Domain providers:

Generic
GoDaddy
CloudFlare
Google Domains

Generic solution

In your DNS, add an A record that points the subdomain i to xx.xx.xxxx.xx
In the below example Host would be i and Points to would be xx.xx.xxxx.xx

If the subdomain i is already mapped to something, please get in touch with us so we can help you pick a different subdomain name.

Step 6: Set up Integrations

Setting up each integration is necessary to properly track each platform's data

Platforms listed in the onboarding flow are API integrated with Northbeam. Data included with the API integration includes:

Spend and Impressions
Campaign, Ad Set and Ad names

Connect your ad accounts via login credentials. Whoever makes the connection needs to have admin access.

✏️ NOTE: If you wish to connect multiple accounts (ex. 2 Meta, 3 Google, etc), please contact our Customer Success Team with the additional account ID's and we will make the update in our backend.

✏️ NOTE: If you wish to connect multiple Google accounts, be sure all accounts are housed under the same MCC.

Step 7: Append UTMs

Within our UTM guide, you’ll see that we have Northbeam-specific UTM parameters for most major ad platforms (ex. Facebook, Google, TikTok, Snapchat, etc.). If you’re on any of these platforms, please use our UTMs.

Keep in mind, UTMs are a crucial part of the onboarding process. Understandably, some brands prefer to prolong the UTM embedding process to prevent their ads going back into the ‘learning phase’. This is fine, although not ideal – as the absence of UTMs could result in fragmented data, making it challenging to find insights.

If you’re on any platform that isn’t listed on our UTM Guide, use Google’s standard UTMs (ex. source, medium, campaign, term, content) and we’ll pull in the data using this segmentation.

For the most granularity, use utm_campaign, utm_term, and/or utm_content.

utm_campaign will pull into the campaign level
utm_ term will pull into adset level
utm_content will pull into the ad level

💡TIP: Reference our UTM builder to help generate links with UTMs.

The goal here is to ensure that folks land on your site with UTM parameters attached. This can be difficult with certain channels like influencers, podcasts, or direct mail. However, we’ve seen vanity links work well.

These are essentially redirects. For example:

test.com/podcast redirects to test.com?utm_source=podcast
test.com/influencers redirects to test.com?utm_source=influencers

💡TIP: We’ve noticed that vanity links reduce the friction in terms of embedding the UTMs.

Return to Table of Contents

Step 8: Adding Account Managers

Add additional users to your account.

If you would like to invite a user, please add their email below and click Add Manager.

✏️ NOTE: Northbeam does not put a limit on the number of users in your account. Feel free to add as many people as you would like.

If the user does not receive an email, please check the spam folder. If they still do not receive an email, they can generate a password through the password reset flow on dashboard.northbeam.io.

Return to Table of Contents

Next Steps

That’s it! Our team will be monitoring your onboarding progress.

We’ll activate your account once the following are completed:

API is connected
Northbeam Pixel and Order Status Page scripts are placed and tracking properly
A-Record is created on your DNS record
UTMs are appended on all live ads

✏️ NOTE: Once activated, we’ll spend the next 3-5 days validating your data. We’ll ensure that your data is flowing in correctly and all connections are properly set up.

In the meantime, you’ll have access to the dashboard. Feel free to tour and prepare any questions for the first review with the team, which normally involves a platform walkthrough.

Please review the next section, which has additional setup items and features that you may be interested in.

Step 9: Additional Setup Items

The items below are not included in the Onboarding flow, but are recommended add ons to your dashboard setup.

Uploading Additional Spend

By default, our API pulls spend (and impressions) from the platforms that we have native integrations with. This includes all of the connected platforms within the ‘Integrations’ step in the onboarding flow, or ‘Connections’ menu when your dashboard is activated.

However, we can use a Custom Spend Sheet to ingest any costs from an alternative platform or source. Common examples include: Klaviyo spend, Attentive spend, Twitter spend, influencer costs, podcast spend, agency fees, etc.

✏️ NOTE: Please contact our Customer Success Team for a custom spreadsheet.

Once you receive the sheet, please follow the directions below:

Reference the 2nd tab called “Input”
Enter all spend sources in Row 1 (A1, B1, C1, etc).
Below each source, insert the corresponding costs. Feel free to add them on a daily, weekly, or monthly basis.
Updated numbers will populate in your next data refresh

✏️ NOTE:

Feel free to use your own automations to import spend into the “Input” tab (ex. “=importrange” function)
Please do not edit the tab called “__IMPORT_TARGET__”

💡TIP: You can access + edit the spendsheet in your dashboard, under Settings > Data Spreadsheets.

Once the costs are added, the spend data may be grouped under the platform called "Other". Feel free to make a label to group it into its own category.

Custom Events

By default, our system tracks Purchase events. If you’d like to track other events, please use our fireCustomGoalScript.

✏️ NOTE: If you are using Klaviyo's sign up forms, sign ups are collected through the API Integration

Common use cases are the following:

Non-Klaviyo Sign Ups
Add To Cart
Initiate Checkout
Quiz Submissions
Phone Calls
Leads
Any other action on your website

Custom Goal Setup Process

Step 1: Make sure the Base Pixel is firing

Please ensure the following:

The base Northbeam Pixel is firing on the page of where the event occurs
The page lives on the same top-level domain as your main website

Step 2: Implement our Custom Goal script.

Implement our fireCustomGoalScript to fire after every desired website event. This is our generic Custom Goal script. It strictly tracks the event count.

By default, you’ll see the ‘Goal ID’ (in green) is labeled as “add_to_cart”, but feel free to rename based on the goal. For example, “sms_signup”, “initiate_checkout, etc.

💡TIP: Custom events can be deployed through Google Tag Manager. Please use an HTML tag and be sure to define it as Javascript.[Example]

Step 3: Send Northbeam Your Goal ID

Please contact our Customer Success Team and let us know what ‘Goal ID’ you’re using (from Step 2). We’ll plug this into our backend, which will enable them in your dashboard view.

Step 4: Add Events into a Saved View

After the events are plugged in, you should see them populate within the Sales menu, under the customize metrics button. Don’t forget to add these metrics to a saved view for easy access.

✏️ NOTE: Once we upload the spend sheet to your account, you can always access + edit it in the platform by going to Settings > Data Spreadsheets

Return to Table of Contents