# Add order tags in Shopify
Source: https://docs.northbeam.io/docs/8c-add-order-tags-in-shopify
You only need to add additional tags that you don't already have setup.
## Create order tags
Note: Recharge customers don’t need to create order tags for subscriptions. You should still create order tags for other cases, like returns and exchanges.
1. Log in to Shopify
2. From your Shopify Admin, click on ‘Orders’
3. Select an order
4. In the ‘Tags’ section, enter the name of the tag you want to add. If you enter the name of a new tag - it will automatically be created for future use across all orders.
5. Click save
6. Once you’ve created order tags, you can bulk update orders from the ‘Orders’ page
# Configure Northbeam order exclusions (Shopify)
Source: https://docs.northbeam.io/docs/8d-configure-northbeam-order-exclusions-optional
Sometimes, you might want to exclude certain orders completely - like when you're analyzing ad attribution or revenue from your web store but also have orders from a brick-and-mortar store in your OMS. Common examples include: phone orders, customer service placed orders, gifting (influencers), replacements, warranty, cancellations, 3rd party retailer (Amazon, Walmart, Macys, etc.).
If you already have these order types tagged in Shopify, you can add the order tag exclusions directly in the onboarding flow in this step.
If you choose to complete this step at a later time you can add them to the "Exclude Orders by Tag" section in the Settings page of your Northbeam dashboard after your dashboard has been activated.
# Accounting Modes
Source: https://docs.northbeam.io/docs/accounting-modes
Our Accounting Modes are settings within the platform that determine when conversion and revenue credit are given.
## What are Accounting Modes?
| Accounting Mode | What is it best for? | Definition | Use Cases | Example Scenarios to Best Leverage |
| :- | :- | :- | :- | :- |
| Cash Snapshot | Best for **Reporting Purposes**. | Attribute **Credit** to the **Day** of the **Transactions**. | Measuring business cash flow; MER | 1. Which was the weekly/ monthly/ quarterly impact of all my channels on the business? 2. We had a really strong revenue day yesterday. Which channels contributed to the success? \_ |
| Accrual Performance | Best for **Daily Optimizations.** | Attribute **Credit** to the **Day** of the **Interaction**. | Scaling paid media; CAC/ROAS | 1. \_What campaign/ asset/ ad has been performing the best over the past 7 days? 2.We're seeing a drop in performance over the past 7 days, which channel is falling behind? |
They're named to roughly mirror cash basis vs. accrual accounting in corporate finance.
## Here are how the two modes differ
### What is Cash Snapshot?
In Cash Snapshot, revenue and transactional credit are given when a **transaction occurs**, or when an order was placed.
Cash Snapshot is useful for understanding the amount of money coming in on any given day (cash flow).
### What is Accrual Performance?
In Accrual Performance, revenue and transactional credit are given when a **contributory marketing touchpoint occurs**.
Marketing touchpoints refer to any interaction that results in a website visit, which triggers our [Northbeam Pixel](/docs/add-pixel)
Examples:
* Click on an Ad that lands on your site
* Click on an Email or SMS message that lands on your site
* Click on an Influencer link that lands on your site
* Click on an Affiliate link that lands on your site
* Click on an Organic Search link that lands on your site
* Click on an Organic Social link that lands on your site
* Direct Visit that lands on your site
In Conclusion:
Accrual Performance is meant to help understand the direct return of your marketing dollars and designed to show the full impact of marketing channels on your business.
#### Example: The difference between Cash Snapshot and Accrual Performance Accounting Modes
Let's say Dan visits the "Widgets Co" website on three different days:
1. Jan 1 - site visit from clicking on a Facebook Ad
2. Jan 2 - site visit from clicking on a Google Ad
3. Jan 3 - site visit after clicking on an affiliate link and **placed a \$90 order**
For simplicity, let's suppose we're using an equal-weight attribution model where all marketing channels receive equal credit (i.e. Linear attribution model), so the Facebook Ad, the Google Ad, and the affiliate link each get 1/3 credit for the purchase.
***
## In Cash Snapshot mode
All revenue and transactional credit is given to Jan 3 since the order was placed on Jan 3.
Here's a breakdown of the credit allocation:
| | Jan 1 | Jan 2 | Jan 3 |
| :- | :- | :- | :- |
| Facebook Ad | \$0 revenue; 0 transactions | \$0 revenue; 0 transactions | **\$30 revenue; 0.33 transactions** |
| Google Ad | \$0 revenue; 0 transactions | \$0 revenue; 0 transactions | **\$30 revenue; 0.33 transactions** |
| Affiliate Link | \$0 revenue; 0 transactions | \$0 revenue; 0 transactions | **\$30 revenue; 0.33 transactions** |
**What does this mean?**
All credit is given to Jan 3. Zero credit given to Jan 1 and 2, despite the touchpoints that occurred on these days.
As a result, it's easy to assume Jan 1 and 2 didn't have an influence on the purchase.
To take it one step further, let's say \$10 was spent on Facebook and Google on each day. Your data would look like something like this.
**Jan 1 Performance**
| | Spend | Revenue | MER |
| :- | :- | :- | :- |
| Facebook Ad | \$10 | \$0 | 0.0 |
| Google Ad | \$10 | \$0 | 0.0 |
| Affiliate Link | \$0 | \$0 | 0.0 |
**Jan 2 Performance**
| | Spend | Revenue | MER |
| :- | :- | :- | :- |
| Facebook Ad | \$10 | \$0 | 0.0 |
| Google Ad | \$10 | \$0 | 0.0 |
| Affiliate Link | \$0 | \$0 | 0.0 |
**Jan 3 Performance**
| | Spend | Revenue | MER |
| :- | :- | :- | :- |
| Facebook Ad | \$10 | \$30 | 3.0 |
| Google Ad | \$10 | \$30 | 3.0 |
| Affiliate Link | \$0 | \$30 | - |
How this could be misleading when scaling media:
* Jan 1 and 2 received no revenue credit, with 0.0 MER, so it's easy to assume these days had poor performance
* Jan 3 received all the credit, with 3.0 MER, so it's easy to assume this day had great performance
**This potential misleading effect is magnified if your business has a longer purchase conversion cycle.**
Suppose you're selling a higher AOV product and it takes roughly 30 days for a customer to convert. Today's ad performance on Cash Snapshot mode could be a result of marketing efforts from up to 30 days ago.
Pro Tip: Most Ad Managers report their numbers using the Cash Snapshot mode.
***
## In Accrual Performance mode
Revenue and transactional credit is divided between Jan 1, 2, 3 and assigned to the touchpoints that resulted to the site visits.
Here's a breakdown of the credit allocation:
| | Jan 1 | Jan 2 | Jan 3 |
| :- | :- | :- | :- |
| Facebook Ad | **\$30 revenue; 0.33 transactions** | \$0 revenue; 0 transactions | \$0 revenue; 0 transactions |
| Google Ad | \$0 revenue; 0 transactions | **\$30 revenue; 0.33 transactions** | \$0 revenue; 0 transactions |
| Affiliate Link | \$0 revenue; 0 transactions | \$0 revenue; 0 transactions | **\$30 revenue; 0.33 transactions** |
Keep in mind:
Accrual is our most popular accounting mode since credit is given to the different marketing touchpoints, which gives the most accurate view of ad performance.
With this in mind, the Overview and Sales page in our dashboard **default to Accrual accounting mode**.
***
## Cash Snapshot - Use Cases
#### Use Case 1: Goal Setting Based on Blended MER
Many businesses track their company's performance using a target MER Goal, as MER typically points to profitability.
For context, MER is calculated the same way as ROAS (Total Revenue / Total Spend), but the difference is that MER is used in Cash Snapshot mode, while ROAS is used in Accrual Performance mode.
**Why is MER used in Cash accounting, while ROAS is used in Accrual accounting?**
It boils down to the accounting modes. We know Cash Snapshot **does not** attribute the orders and transactions to the contributory touchpoints. While the same formula is used (Revenue/Spend), we merely see it as a ratio, also known as Media Efficiency Ratio (MER).
On the other hand, we attribute orders and transactions to the touchpoints in Accrual accounting. Therefore, we see (Revenue/Spend) in Accrual accounting as more of a true return on your ad spend (ROAS).
**Now, we can use a Blended MER goal to track business-level performance.**
To take it one step further, a Blended MER can waterfall down into lower-level ROAS or CAC goals at the platform levels. In this context, Blended MER refers to MER across all channels: total revenue / total spend.
Let's say your Blended MER goal was a 3.0 and looking at your historical data, you saw the following:
| Blended MER | Facebook ROAS (1DC) | Google ROAS (1DC) | TikTok ROAS (1DC) |
| :- | :- | :- | :- |
| 3.5 | 1.2 | 2.5 | 0.8 |
| **3.0** | **1.0** | **2.2** | **0.6** |
| 2.5 | 0.8 | 1.9 | 0.4 |
| 2.0 | 0.6 | 1.8 | 0.2 |
We can use the **benchmarks** for Facebook, Google, and TikTok when tracking performance using the Accrual accounting mode. In fact, we have a [Benchmarking Tool](/docs/profitability-benchmarks) that helps you do this within the Sales page.
# Adding / Removing Ad Accounts
Source: https://docs.northbeam.io/docs/ad-accounts
## Adding extra ad accounts
1. Go to **Settings › Connections**.
2. Find the platform whose account you want to add (e.g. Meta, Google) and open its connection.
3. Select **Add account** and complete the platform's authorization flow.
4. Confirm the new account appears as **Connected**. Spend and metrics for that account begin flowing on the next data refresh.
## Removing an ad account
1. Go to **Settings › Connections** and open the platform's connection.
2. Select the account you want to remove, then choose **Remove**.
3. The account stops syncing new data. Historical data already attributed remains in your dashboard.
Watch the walkthrough below for the same steps in the product. Everything shown is also written above.
| Action | Who has access |
| :- | :- |
| Connect Ad Accounts | All Users |
| Remove Ad Accounts | All Users |
| Update Google MCC Account | Admin-Only |
# Add Orders
Source: https://docs.northbeam.io/docs/add-orders
In addition to tracking client-side purchases, it's important to sync your source of truth for order data with Northbeam for accurate and up-to-date reporting.
# Background
For Northbeam's Multi-Touch Attribution (MTA) and Mixed Media Modeling (MMM) offerings, we use our customers' Orders as the ground truth for Revenue. This enables Northbeam to perform Ad Attribution on Purchases that took place (MTA) and to assist in predicting what will take place (MMM).
***
## There are 2 ways to send your order data to Northbeam:
1. [Shopify Connector ](/docs/shopify-order-sync)(If your backend orders management system is hosted on Shopify)
2. [Orders API](/docs/orders-api)(If your backend orders management system is NOT Shopify)
# Northbeam Pixel
Source: https://docs.northbeam.io/docs/add-pixel
What the Northbeam Pixel does, how to install it on your platform, and how to test it.
The **Northbeam Pixel** is a script that runs on every page of your site. It records each visit, the marketing touchpoint that brought the visitor in, and the pages they view. Northbeam uses this to build each customer's journey and attribute orders to the right channels.
It's the foundation for all other Northbeam tracking. Purchase events, custom goals, and other events all rely on the pixel being on the page first.
**The pixel must fire on every page, all the time.** If it doesn't, Northbeam can't see which channels drove those visits and orders, and **that data can't be recovered**.
## Which setup you need
Where the pixel goes depends on your store. Your platform guide walks you through every step.
| Platform | Where the pixel goes | Guide |
| :- | :- | :- |
| **Shopify** | Two places: the `` of your storefront (`theme.liquid` on standard themes), and a **Custom Pixel** in Shopify Customer events, which covers checkout. | [Shopify](/docs/shopify-installation) |
| **Custom** | The `` of every page, added in your site's code or through Google Tag Manager. | [Custom](/docs/non-shopify-installation) |
**Custom** means any store that doesn't use Shopify's checkout, and is available on Pro and Enterprise plans. Headless stores that use Shopify's checkout follow the **Shopify** guide.
### Where to find your scripts
Your scripts come pre-filled with your Client ID. You can find them in two places:
* **During onboarding:** in the **Pixel Placement** step. After you select and connect your platform, look under **Northbeam Pixel**.
* **In the dashboard:** go to [Settings → Northbeam Pixel and Event Tracking](https://dashboard.northbeam.io/settings/tracking-script-tags).
## What the pixel tracks
Once installed, the pixel records **page views automatically** every time a page loads. Everything else needs a small amount of extra setup.
| Tracking | Set up | Who needs it |
| :- | :- | :- |
| **Page views** | Automatic | Everyone |
| **[Purchase events](/docs/purchase-pixel)** | Shopify: automatic with the Custom Pixel. Custom: add to your confirmation page. | Everyone |
| **[Page views on single-page apps](/docs/page-view-events)** | Add to your site's router | **Only single-page apps (SPAs).** Most sites don't need this. |
| **[Custom goals](/docs/setting-up-custom-goals)** | Add wherever the action happens | Optional. For sign-ups, add-to-carts, form fills, and similar actions |
## How to test for the Northbeam Pixel
You can check the pixel on any page of your site using your browser's developer tools. These steps use Google Chrome.
Open any page on your site. If a cookie banner appears, **accept it**. On sites with a consent banner, the pixel doesn't send data until the visitor agrees.
Right-click anywhere on the page and click **Inspect**. Open the **Network** tab, then **refresh the page**. The Network tab only shows requests made while it's open.
In the Network tab's filter box, type `nb-collector`. Click one of the results and open its **Payload** tab.
Look for a `pv` field. `pv` means *page view*: the pixel recorded the visit and sent it to Northbeam.
In the same payload, find the `aid` value. This is the Client ID the pixel is sending data to. Confirm it matches your Northbeam account.
This matters most if you have more than one Northbeam dashboard (for example, one per region or brand). Data only shows up in the account that matches the `aid`, so don't mix pixels between dashboards.
### Don't see an nb-collector request?
* **Accept the cookie banner** and refresh. This is the most common cause.
* **Check that the pixel is installed** on that page. Follow your [platform guide](#which-setup-you-need) again.
* **Turn off ad blockers** and privacy extensions, then refresh. They can block tracking requests.
* **Check your Content Security Policy** if you have one. It must allow your `i.` subdomain. See [Custom, step 1](/docs/non-shopify-installation#1-install-the-northbeam-pixel).
Still stuck? [Contact our support team](https://www.northbeam.io/submit-a-support-ticket), or see [Troubleshooting Pixel Tracking](/docs/guide-to-troubleshooting-pixel-tracking) for deeper checks.
# Add Spend
Source: https://docs.northbeam.io/docs/add-spend
### Upload spend for any channels that do not integrate with Northbeam.
There are two main ways to do this:
1. [Spend API (preferred)](/docs/add-spend#option-1-spend-api)
2. [Spend Sheet](/docs/add-spend#option-2-spend-sheet)
This will allow you to:
* See cost-based metrics (ex. ROAS, CAC, CPC) for non-integrated channels
* Include ALL advertising costs to give you a full picture of total business performance
Background
Northbeam integrates with most major ad platforms and is able to fetch spend data. Platforms include Facebook, Google, TikTok, Snapchat, Pinterest, etc. See [Channel Tracking Overview](/docs/all-other-platforms-overview) for full list.
For any channels that don't integrate, you're able to upload spend data using the Spend API or a Spend Sheet.
***
### When to Use the Spend API Instead of a Spend Sheet
Spend Sheets let you share spend data for ad platforms we don’t natively support by using a Google Sheet. However, they can become challenging to manage when you have:
* Multiple ad platforms to support
* Numerous campaigns with complex structures per platform.
The Spend API was developed to simplify these cases. Consider using the Spend API if:
* You have developer resources to assist with setup
* Your spend data is complex enough that manually updating a sheet would be burdensome.
#### Comparison: Spend API vs. Spend Sheet
| | Spend Sheet | Spend API |
| - | - | - |
| Import ad spend data from any platform | ✅ | ✅ |
| No dev resources required | ✅ | ❌ |
| Minimal ongoing overhead to support | ❌ | ✅ |
| Supports Hourly data | ❌ | ✅ |
## Option 1: Spend API
### What is the Spend API?
The Spend API enables our customers to programmatically upload daily spend, clicks, and impressions metrics at the ad level of their choice (Campaign, Adset, Ad) for Ad platform integrations that we do not natively support. A common example is an email marketing platform (e.g. Mailchimp, SendGrid).
Read more about the Spend API [here](/docs/spend-api) and the API reference [here](/reference/post_spend).
### When should I use the Spend API?
If you want to associate spend with campaigns that Northbeam is tracking from platforms that we don't natively integrate with, upload spend data associated with those campaigns using the Spend API. To correctly associate spend with campaigns, you need to provide:
* The date the spend was committed
* This name of the platform to associate the spend with (this label will apply to the spend object in the dashboard)
* The campaign ID and name that the spend is for
* The currency and amount spent on the campaign
### How do I set up the Spend API?
Read more about the Spend API [here](/docs/spend-api) and the API reference [here](/reference/post_spend).
***
## Option 2: Spend Sheet
### What is a Spend Sheet?
A Spend Sheet is a Google Sheet where you can manually enter your spend data, which is then uploaded to your dashboard to reflect this data in the backend. This method provides an efficient way to track cost metrics like ROAS and CAC even for platforms or channels that don’t have direct integrations with Northbeam.
### When should I use a Spend Sheet?
If you don’t have development resources to set up an automated API POST request to send spend data on a regular cadence to your dashboard, the Spend Sheet is an effective alternative. While it requires more manual setup, there are ways to streamline and partially automate the process.
### How do I set up a Spendsheet?
#### Step 1: Request a Spend Sheet
First, check whether you already have a Spend Sheet in [Data Spreadsheets](https://dashboard.northbeam.io/settings/data-spreadsheets).
If not, [reach out our team](https://info.northbeam.io/knowledge/help) to request one. We’ll create it, share it with you, and connect it to your backend.
#### Step 2: Fill out the Custom Spendsheet
For detailed step-by-step instructions:
* Watch the instructional video above
* Refer to the **Instructions** tab directly in the spreadsheet
Key Steps for using the Spendsheet
1. **Daily Spend Entry:**
2. Enter platform and campaign names in the “Input” sheet. Platform names go in Row 1, and campaign names or spend labels go in Row 2.
3. Refer to the spreadsheet for examples and validation requirements.
4. **Use the Validation Tool:**
5. After entering data, use the “Validation Tool” tab to verify accuracy. Follow the instructions in the spreadsheet to ensure your spend data aligns properly between the “Input” and “IMPORT\_TARGET” sheets.
6. **Align Spend Names for Grouping with Revenue:**
7. To allow grouping of spend with revenue for cost-based metrics like ROAS and CAC, it’s crucial that campaign names in the “Input” sheet match exactly with utm\_campaign values. By maintaining consistency with UTM naming, Northbeam can group spend and revenue data effectively on the backend.
8. Simply set up the correct naming in the Spend Sheet, and our team will manage the labeling and categorization for seamless reporting.
> 4. **Automate Data Entry**
> 1. Utilize the “Raw Data Import” sheet as a sandbox. Automate data import here and transfer it into the “Input” sheet in the required format. (See spreadsheet notes for more on setting up data automation.)
**Spendsheet FAQs**
* **Removing or Adding Spend Sources:** See the FAQs tab in the spreadsheet for guidance on adding/removing spend sources without altering the spreadsheet structure.
* **Entering Data in USD:** Enter spend in U.S. dollars, regardless of dashboard currency. The spreadsheet will handle conversion.
* **Troubleshooting Missing Data in the Dashboard:** If data is missing, check the “Validation Tool” and the “Other” platform group on the dashboard. Reach out to our support team if needed.
### Step 3: Re-Categorize Custom Spend
When your spend data is uploaded, it might initially appear under the “**Other**” platform group in your dashboard. You can use the **Breakdowns Manager** to customize spend categories. This tool allows you to reassign spend to the appropriate platform, making it easier to analyze spend metrics by platform.
***
## FAQ
### **Why can't I find my spend?**
If you can't locate your spend data, try the following troubleshooting steps in order of priority:
**Check for Misclassified Spend:**\
Often, spend data is categorized under the "Other" platform group. Start by sorting spend from highest to lowest to bring it to the top. Alternatively, you can use the search bar at the campaign level and search for the spend source name. Applying the platform breakdown view can help reveal where it’s categorized
**Review the IMPORT\_TARGET Tab:**\
Although you shouldn’t have edit access, occasionally formulas can misalign. If the IMPORT\_TARGET tab appears out of sync with the Input tab, please reach out to our support team.
**Verify Spreadsheet Connection:**\
Ensure your spend sheet is connected to your dashboard by opening [Data Spreadsheets](https://dashboard.northbeam.io/settings/data-spreadsheets). This should already be set up by our team, but it’s worth confirming.
# Setting Up Multiple Stores or Regions
Source: https://docs.northbeam.io/docs/adding-a-store-or-dashboard
Use this page if you operate more than one store, brand, or region and want to understand how to structure your Northbeam setup.
A **segment** refers to any distinct part of your business you want to track separately in Northbeam. The most common examples are:
* **Multiple regions** — e.g. a US store and a UK store
* **Multiple business lines** — e.g. a DTC storefront and a wholesale storefront
* **Multiple brands** — e.g. Brand A and Brand B under the same parent company
***
## Start Here
Answer these two questions. If either answer is yes, you likely need multiple dashboards.
**1. Do your segments live on different top-level domains?**
Each Northbeam dashboard is tied to a single top-level domain via a DNS A Record. If you have multiple domains and want first-party tracking on each, each domain needs its own dashboard.
**2. Do you need fully separated data per segment?**
A single dashboard blends all data together. There is no way to separate orders, revenue, or attribution by segment at the order level within a single dashboard. If you need clean, independent reporting per store or region, you need multiple dashboards.
> If neither applies — multiple domains don't matter to you and blended data is fine — a single dashboard may be all you need. See [Option 1](#option-1-single-dashboard-blended) below.
***
## Option 1: Single Dashboard (Blended)
All segments feed into one dashboard. Data is not separated at the order or visit level.
**Works well when:**
* All segments are on the same top-level domain, OR you're fine with third-party tracking on additional domains
* You don't need independent revenue or attribution reporting per segment
* Consolidated reporting matters more than per-segment precision
**Key caveats:**
* **No order-level segmentation.** You cannot separate Store A orders from Store B orders within the dashboard.
* **Campaign naming conventions are the only segmentation lever.** You can filter by UTM parameters or campaign names in the Attribution view, but that's it.
* **Third-party tracking on additional domains.** If you connect a store on a different domain to an existing dashboard, that store will use third-party cookies instead of first-party. Modern browsers increasingly block third-party cookies, which reduces visit stitching accuracy and can increase unattributed revenue in your MTA data.
**What you'll need:**
* Northbeam pixel installed and firing on all stores' pages
* `firePixelEvent` purchase events firing on all stores' checkouts
* Orders and spend connected for each store
Need help with pixel setup? See [Troubleshooting Pixel Tracking](/docs/guide-to-troubleshooting-pixel-tracking).
***
## Option 2: Multiple Dashboards
Each segment gets its own Northbeam dashboard with fully independent data. This is the setup to use when you need clean, separated reporting or have multiple domains that each require first-party tracking.
There are two ways to get to multiple dashboards depending on your domain setup.
***
### Option 2A: Multiple Domains → One Dashboard Per Domain
If each segment has its own top-level domain (or subdomain), each gets its own Northbeam dashboard. This is the standard multi-dashboard setup.
**Examples:**
| Segment | Domain | Dashboard |
| - | - | - |
| US Store | `mystore.com` | US Dashboard |
| UK Store | `uk.mystore.com` | UK Dashboard |
| Brand B | `brandb.com` | Brand B Dashboard |
**Requirements:**
* Each segment has a distinct domain or subdomain
* Ad data can be separated by segment — either via unique ad accounts, or via consistent campaign/adset naming conventions (e.g. campaigns beginning with `US_`, `UK_`)
* Orders can be matched to the correct segment via store, shipping country, currency, or other order metadata
**What you'll need:**
* A new Northbeam dashboard provisioned for each domain (handled by the Northbeam team)
* Standard setup completed for each dashboard: pixel, DNS, orders, spend
* Once set up, you can switch between all your dashboards using a single login
New dashboards are always provisioned by the Northbeam team — there is no self-serve path. Reach out to your CSM to get started.
**Supported scenario examples:**
| Segment | Ads | Domain | Orders |
| - | - | - | - |
| US | US Meta Ads Account | `mystore.com` | `mystore-us.myshopify.com` |
| UK | UK Meta Ads Account | `uk.mystore.com` | `mystore-uk.myshopify.com` |
| DE | DE Meta Ads Account | `de.mystore.com` | `mystore-de.myshopify.com` |
✅ Supported — unique ad accounts, domains, and Shopify stores per segment.
| Segment | Ads | Domain | Orders |
| - | - | - | - |
| US | Campaigns begin with `US_` | `mystore.com` | Currency is `USD` |
| UK | Campaigns begin with `UK_` | `uk.mystore.com` | Currency is `GBP` |
| DE | Campaigns begin with `DE_` | `de.mystore.com` | Currency is `EUR` |
✅ Supported — campaign naming conventions and order metadata cleanly map to each segment.
| Segment | Ads | Domain | Orders |
| - | - | - | - |
| US | 1 shared account, campaigns begin with `US_` | `mystore.com` | Currency is `USD` |
| UK | 1 shared account, campaigns begin with `UK_` | `uk.mystore.com` | Currency is `GBP` |
✅ Supported — shared ad account with consistent naming conventions allows spend to be filtered per segment using Breakdown labels.
| Segment | Ads | Domain | Orders |
| - | - | - | - |
| US | 1 shared ad account, no naming convention | `mystore.com` | `mystore-us.myshopify.com` |
| UK | 1 shared ad account, no naming convention | `uk.mystore.com` | `mystore-uk.myshopify.com` |
Domains and orders are separable, but **ad data cannot be split without naming conventions**. Separate dashboards can still be created, but spend and impressions will not be accurately attributed per segment. Naming conventions must be added before proceeding.
***
### Shared Ad Accounts Across Segments
Having one ad account that serves multiple segments is supported — but it requires clean campaign naming conventions and an extra filtering step.
**How it works:**
* Connect the shared ad account to **each** segment dashboard. Because the account is shared, all campaigns will pull into every dashboard by default.
* Use **Breakdown labels** in each dashboard to filter to only the campaigns relevant to that segment (e.g. the UK dashboard filters to only show campaigns beginning with `UK_`). Northbeam will walk you through setting these up.
* **All campaigns must follow a consistent naming convention** so they can be cleanly attributed to the right segment.
**Consolidated campaigns** (e.g. a brand awareness campaign that isn't segment-specific) require a decision: include it in all dashboards, one dashboard, or exclude it entirely. There is no automatic way to split a single campaign across multiple dashboards.
If campaigns aren't named consistently, there is no reliable way to split ad spend by segment. The naming convention must be in place before Northbeam can configure Breakdown labels.
***
### Option 2B: Single Domain → Multiple Dashboards via Configurators
If all your segments live on one top-level domain but you still need separated data, Northbeam can split events and orders across multiple dashboards using **Configurators**. First-party tracking is maintained across the single domain.
**Examples:**
| Segment | Domain | Dashboard |
| - | - | - |
| US | `mystore.com/us` | US Dashboard |
| UK | `mystore.com/uk` | UK Dashboard |
| DE | `mystore.com/de` | DE Dashboard |
**How it works:**
* A **parent dashboard** receives all events from your domain
* **Child dashboards** each receive a split subset of events, routed by logic rules you define (e.g. page path, country code, order tags)
* Data is fully separated at the order and visit level in each child dashboard
* The parent always retains the blended view
**Requirements:**
* All segments must be cleanly separable using Northbeam's supported logic fields — the split cannot be arbitrary. See [Multi-Dashboard Setup with Configurators](/docs/multi-dashboard-setup-with-configurators) for the full list of supported fields.
* Ad data must still be separable by segment (unique ad accounts or campaign naming conventions)
**Not available to all customers.** Reach out to your CSM to find out if this setup is right for you.
For full details on how Configurators work, supported logic fields, and the setup process, see [Multi-Dashboard Setup with Configurators](/docs/multi-dashboard-setup-with-configurators).
***
## Decision Summary
| My situation | Recommended setup |
| - | - |
| One domain, blended data is fine | Single dashboard |
| One domain, need separated data per segment | Configurators (Option 2B) |
| Multiple domains, blended data is fine | Single dashboard (third-party tracking on additional domains) |
| Multiple domains, need first-party tracking | One dashboard per domain (Option 2A) |
| Multiple domains, need first-party + separated data | One dashboard per domain (Option 2A) |
***
## What's Next
* **Single dashboard setup** → See [Welcome to Northbeam](/docs/what-to-expect-during-implementation)
* **New dashboard for a new domain** → Contact your CSM
* **Configurator setup (single domain, multiple dashboards)** → Contact your CSM, then see [Multi-Dashboard Setup with Configurators](/docs/multi-dashboard-setup-with-configurators)
* **Questions?** [Submit a support ticket](https://www.northbeam.io/submit-a-support-ticket)
# Adding / Removing Users
Source: https://docs.northbeam.io/docs/adding-or-removing-users-copy
| Action | Who has access |
| :- | :- |
| Add Users | All Users |
| Remove Users | Admin-Only |
## Adding Users
To add or remove any users, reference the Account Managers menu:
1. Navigate to **Settings**
2. Click on **Account Managers**
3. Enter the email address of the requested user and click **Add Manager**
The user should receive an email invitation to create a password. Be sure to 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.
## Removing Users
Removing a User is an admin-only feature. *(The admin of your account is generally the user who initially created the Northbeam dashboard. To find out who your admin is, go to the Account Managers menu and find the email denoted with an "Admin" label in blue)*
To remove a User, navigate to the Account Managers menu and use the "Delete" button on the right right side.
# Changing Currency
Source: https://docs.northbeam.io/docs/adding-or-removing-users-copy-1
By default, we convert all currencies to US Dollars (USD) using the daily exchange rate.
## How do I change my currency?
Please submit an inquiry [here](https://www.northbeam.io/submit-a-support-ticket) and indicate which currency you'd like to change to.
## Can I easily toggle between two currencies?
Currency change is a manual process in our backend. Once it's been deployed, all numbers in your dashboard are converted. The only way to revert is to submit another request to our team.
## Are platform metrics converted too?
Yes, all Northbeam-reported and Platform-reported metrics will be converted to the client’s currency of choice.
If needed, there is an option to convert Northbeam-reported metrics, but not convert platform metrics. If this applies to you, please indicate it in your inquiry.
## How does this feature work with Custom Spendsheets?
For Custom Spendsheets, please insert spend in USD. It will be converted to your requested currency before populating in your dashboard.
## Does this feature have support in the Mobile App?
This is something our team is still working on. If this is requested, please submit an inquiry [here](https://www.northbeam.io/submit-a-support-ticket).
# All Other Platforms Overview
Source: https://docs.northbeam.io/docs/all-other-platforms-overview
This page will help you get started with Northbeam's API.
# Background
For Northbeam's Multi-Touch Attribution(MTA) and Mixed Media Modeling(MMM) offerings, we use our customers
* Ad Platform Spend Data as the ground truth for Ad Spend
* Orders as the ground truth for Revenue.
* Website Events (via Northbeam's pixel) to connect the journey from a customer clicking or seeing an ad to a potential purchase
This enables Northbeam to perform Ad Attribution on Purchases that took place (MTA) and to assist in predicting what will take place (MMM). While the mechanics of the Pixel are covered elsewhere, this documentation concerns itself with how your Orders and Spend data can be collected via Northbeam's API.
## Spend
Northbeam supports a wide variety of native integrations into your existing ad platforms. These include, but are not limited to:
* Facebook/Meta
* Google Ads
* Tiktok
* Bing/Microsoft Ads
* Snapchat
* Amazon Ads
For a full list, Please see the **PLATFORM SETUP GUIDES** section.
There are often cases where our customers leverage ad platforms that we do not have native integrations for. For these platforms, we have a *Custom Spend API* which provides a means by which our customers can send us data about their spend, to be surfaced and included in the Northbeam dashboard. The Custom Spend API is a standard solution that that accepts HTTP API calls where the payload contains a list of Ad Objects and their spend on a given date.
## Orders
For customers that use Shopify of Amazon as their ground truth for Orders, we support a Shopify and Amazon native integrations. These integrations sync a customer's Shopify/Amazon store and get information about orders. This data is subsequently used for attribution (MTA) or for predictive analytics (MMM).
It is sometimes the case that Shopify or Amazon are not the customer's go-to for the most up-to-date Order information. The native integrations (Shopify/Amazon) are covered elsewhere in the Guide and will not be covered in this section.
* In some cases, customers employ a collection of Shopify/Amazon stores from which they internally pull data into their own data pipelines for centralization, or downstream data transformation (i.e. currency conversion, time-zone manipulation, filtering of incomplete orders, or for tagging purposes)
* In other cases customers do not use either Shopify or Amazon and use an Order Management System that does not have native support in Northbeam
In either of these above cases (or others), we support the Custom Orders API so that Northbeam can obtain the order information needed to support operations for MMM and MTA. The Custom Orders API is a standard solution that accepts HTTP API calls where the payload contains a list of orders and associated metadata for the orders.
## Data Export
At Northbeam, data export is crucial because it allows for the seamless transfer of valuable information to different platforms, enabling enhanced data integration, analysis, and reporting.
This capability is particularly important for businesses seeking to leverage their data for strategic decision-making, ensuring that insights are accessible across various tools and departments.
By enabling data export, Northbeam helps organizations maximize the utility of their data, improve operational efficiency, and gain a competitive edge through informed data-driven strategies.
If you have any feedback, please submit a [Support](https://www.northbeam.io/submit-a-support-ticket) ticket.
# Announcing Incrementality
Source: https://docs.northbeam.io/docs/announcements/incrementality
Measure the causal impact of your marketing
NewAugust 2026 · Incrementality
Controlled experiments that measure the revenue a channel actually caused — above and beyond what would have happened anyway.
MTA tracks which touchpoints appeared in a customer's journey. MMM finds patterns between spend and revenue over time. Neither can answer whether a customer would have bought anyway, even without the ad. Incrementality testing answers exactly that.
## What's new
01Test vs. control experimentsa holdout group is withheld from your ads; the difference is your incremental impact
02Geo testingcomparable groups built by geography when a randomized holdout isn't possible
03Calibration for MTA and MMMresults feed back to correct over- and under-attribution
04Actionable outputsresults expressed as iROAS and calibrated ROAS
## Why it matters
Ad platforms report ROAS on their own attribution logic, which is almost always inflated — they only see their own touchpoints and have an incentive to take credit. And a significant portion of ad spend goes to customers who would have converted organically; high-ROAS retargeting is the classic example.
Signal lossGeo-based incrementality doesn't rely on user-level data or pixels, so it holds up as iOS privacy changes and cookie deprecation give MTA more blind spots.
# Apex FAQs
Source: https://docs.northbeam.io/docs/apex-faqs
Frequently asked questions about Northbeam Apex.
# FAQs
### What is Meta Custom Attribution, and how does it relate to Apex?
Custom Attribution is Meta's official way of letting advertisers optimize campaigns against an outside attribution model instead of Meta's default. Apex is the data connection that feeds Northbeam's attribution into Meta's Custom Attribution system.
### When will Custom Attribution be available to me?
All customers can enable Apex and start sending data to Meta today. Live optimization is in an invite-only beta, with broader rollout expected in 2026. Setting up Apex now means Meta is already training on your data when broader access opens up.
### Do I need to set anything up in Meta Business Manager?
No. Northbeam handles all Meta-side configuration as part of the in-app setup — we attach a Custom Attribution Source to your selected pixel(s) and configure the CAPI connection automatically. Your existing pixel and CAPI connection are unchanged.
### Will this affect my current CAPI connection or attribution?
No. Apex runs in parallel. It uses a custom event type (Passback) that Meta processes separately from your standard Purchase events, so your existing pixel and CAPI attribution are unchanged.
### What is the difference between a Meta Pixel and a Meta Custom Attribution Source (CAS)?
**TL;DR: The Pixel is what *collects* the data from your website or app. A Custom Attribution Source is what *feeds* your Meta algorithm.**
**Meta Pixel** is the browser-based tracking code you install on your site. It tracks user actions like purchases or sign-ups after they've interacted with an ad, sending that raw event data to Northbeam so actions (like purchases) can be attributed to your ads.
A **Meta Custom Attribution Source** is the object that appears in Meta Events Manager when you turn on Apex. Instead of raw events, it ingests already-attributed performance from Northbeam.
Northbeam's MTA model splits credit across every touchpoint in the customer journey, and Apex sends the Northbeam-attributed performance for each ad to Meta, which uses that signal to optimize delivery against the outcomes you actually measure — rather than how Meta measures by default.
The **North Star** metric is a specific attributed outcome you set up in Northbeam, serving as the exact definition of "good" that Meta's algorithm then optimizes toward.
Many brands have multiple pixels and, therefore, multiple Custom Attribution Sources. **A separate CAS is created for each pixel in a single Northbeam dashboard.**
**Example:**
### I'm already using a CAPI-based product. Should I turn it off?
**No. Do not turn off or change your existing pixel or CAPI setup.** Apex does not conflict with CAPI-based products — they solve different problems and can work together.
* **CAPI-based products** share conversion data and customer identifiers (order value, email, customer ID, phone, products purchased). This helps Meta match conversions back to the users and ad interactions that drove them.
* **Apex** shares attribution credit. Northbeam's MTA model decides how much of each conversion a touchpoint earned and sends Meta its share. This helps Meta understand which ads are most impactful.
**Example — one \$100 order:** Your CAPI setup sends the \$100 order and available customer identifiers to Meta. Apex then tells Meta that, of that \$100, Northbeam credits Meta with **\$45**.
**TL;DR:** CAPI-based products help Meta receive and match conversion data. Apex tells Meta how much credit those conversions should receive. They do not conflict.
See [Apex vs. CAPI and enrichment tools](/docs/northbeam-apex#apex-vs-capi-and-enrichment-tools) for the full breakdown.
### Is this data passed as standard CAPI events?
No. Apex uses custom event types (Passback and AppendAttribution events) specifically requested by Meta for improved signal quality. They are not Purchase events, do not appear as such in Ads Manager, and do not affect EMQ.
### What data does Meta actually see about my customers?
Ad-level attributed performance — transactions, spend, revenue, custom metrics — plus your attribution model, window, accounting mode, and breakdowns. At the order level, events include IP address and user agent (which Meta requires for any server-side CAPI event), but **no emails, names, phone numbers, or device IDs**.
### My North Star is Clicks + Deterministic Views (C+DV). Can I use it with Custom Attribution?
Not yet — Custom Attribution does not currently support C+DV. To run a Custom Attribution test today, set your North Star to **Clicks-only**. If you switch from C+DV to Clicks-only, wait at least **10 days** after the change before starting the test, and evaluate results under the Clicks-only model.
### I changed my North Star — do I need to wait again?
Yes. Changing your North Star resets the model's calibration period. Plan for approximately two weeks before running a new test. The model will still function during that period but will be re-learning from the new signal.
### My results in Meta Ads Manager don't match my Northbeam dashboard. Why?
Two main reasons: (1) Meta's Ads Manager renders results as blended even when your North Star isn't, and (2) there is a 48-hour reporting lag for Custom Attribution data in Ads Manager. Use Northbeam as your source of truth for all budget and performance decisions.
### Meta's reported ROAS went down after I turned on Apex. Is something wrong?
No — this is expected. When Apex is on, Meta's algorithm optimizes against Northbeam's attribution data, but Meta's surface reporting in Ads Manager still uses its own last-click model. The two are now misaligned by design. Evaluate performance in Northbeam, not Ads Manager, where all attribution is consistent.
### I turned on Apex but Meta still isn't optimizing. Why?
Three possible causes:
* **Meta is still warming up.** It takes approximately 10 days of high-quality signal before Custom Attribution becomes selectable in Ads Manager. Check the readiness indicator in Events Manager — it needs to show **High** before you can proceed.
* **You haven't created a Custom Attribution campaign yet.** Turning on Apex does not automatically apply to existing campaigns. Custom Attribution must be selected on a new (or duplicated) Sales-objective campaign at the ad-set level.
* **You're not on the beta whitelist yet.** Apex setup is available to all customers, but Meta-side optimization is invite-only. If you're not on the list, model training is happening but live optimization is not. Reach out to your CSM or [Support Team](https://www.northbeam.io/submit-a-support-ticket) to be added.
### My pixel isn't showing up in the Apex setup wizard. Why?
Two possible causes:
* The Meta login used to connect your Ads account in Northbeam is missing `business_management` permission for the business that owns that pixel. Reconnect using a login that has it. Agency-managed accounts typically only have `ads_management` — the brand side will need to reconnect with the correct login.
* The pixel may belong to a business that the connected user doesn't have access to administer. Confirm the pixel's owning business is one the connected user can manage.
### Can I run Apex and Incremental Attribution at the same time?
Yes, but not on the same ad set. Custom Attribution and Incremental Attribution are mutually exclusive at the ad-set level. You can run both within the same campaign by using different ad sets for each.
### I have multiple Meta ad accounts connected to Northbeam. Does my North Star apply to all of them?
Yes. All Meta ad accounts connected to a single Northbeam dashboard inherit the same North Star settings. If you need different settings for different accounts, those would need to be on separate Northbeam dashboards.
### I just had a positive test — what's next?
Scale as quickly as you can with confidence. The ideal next step is a **50/50 account-level A/B test** on Custom Attribution. If that's not feasible, move at least **20% of budget to Custom Attribution for at least two weeks** to confirm sustained performance before going broader.
Avoid letting it sit at a small budget share (1–3%). The model learns from the traffic it generates — at low spend it can't improve fast enough, results will be misleading, and you'll underrealize the gains even if your A/B test already showed it wins.
### Will Apex affect my Meta performance immediately?
No. Apex currently supports Meta model training. Live optimization begins once you create a Custom Attribution campaign and the 10-day warm-up period is complete.
### Will Apex eventually support TikTok, Google, or other channels?
Yes — additional platform integrations are on the roadmap.
### Can Meta's access to my data be audited?
Yes. Northbeam logs every data export. We can deactivate or revoke a partner's access and reconstruct exactly what was accessed and when.
***
Please reach out to your Customer Success Manager, Media Strategist, or [Support](https://www.northbeam.io/submit-a-support-ticket) if you have any questions.
# Attribution Models
Source: https://docs.northbeam.io/docs/attribution-models
Our Attribution Models are one of the most important concepts to understand.
Our Attribution Models assign **credit for conversion events to relevant marketing touchpoints**.
Northbeam offers 7 different attribution models, which are divided into two categories: Simple Attribution Models and Multi-Touch Attribution Models (MTA).
* **Simple Attribution Models**
* [First Touch](#first-touch)
* [Last Touch](#last-touch-and-last-non-direct-touch)
* [Last Non-Direct Touch](#last-touch-and-last-non-direct-touch)
* **Multi-Touch Attribution Models**
* [Linear](#linear)
* [Clicks-Only](#clicks-only)
* [Clicks + Modeled Views](#clicks--modeled-views)
* [Clicks + Deterministic Views](#clicks--deterministic-views)
***
## Simple Attribution Models
In Simple Attribution Models, all credit is **given to a single touchpoint**. These are legacy models that you may be used to seeing.
Here are our simple models:
* First Touch
* Last Touch
* Last Non-Direct Touch
Please Note
**Last Non-Direct Touch** is the default model used by most in-platform reporting (Facebook Ads, Google Ads, TikTok Ads, Pinterest Ads, Klaviyo, Attentive, etc.) and Google Analytics.
## Multi-Touch Attribution Models (MTAs)
In Multi-Touch Attribution Models, credit is **divided across multiple touchpoints**.
Here are our multi-touch models:
* Linear
* Clicks-Only
* Clicks + Modeled Views
* Clicks + Deterministic Views
Proprietary Models
Clicks-Only, Clicks + Modeled Views, and Clicks + Deterministic Views are Northbeam's proprietary models. Learn more below.
## Summary of Northbeam's Attribution Models
| Attribution Model | Data Source | Credit Allocation | High-Level Use Case |
| :- | :- | :- | :- |
| First Touch | Hard click data | Full credit is given to the **First touchpoint** | Understanding the impact of **Upper Funnel** channels. |
| Last Touch | Hard click data | Full credit is given to the **Last touchpoint** | Understanding the impact of your **Lower Funnel** channels. |
| Last Non-Direct Touch | Hard click data | Full credit is given to the **Last touchpoint, excluding Direct visits**. | Understanding the impact of your **Lower Funnel** channels. |
| Linear | Hard click data | Credit is **divided equally among all touchpoints** | Understanding the impact of **All channels** using an MTA model, where everything is weighted equally. |
| Clicks-Only | Hard click data | Credit is **divided equally among all touchpoints, excluding lower funnel touchpoints** | Understanding the impact of **Upper Funnel** channels, with emphasis given to Upper Funnel |
| Clicks + Modeled Views | Hard click data + machine learning Modeling | Two parts: (1) Clicks-Only (2) NB's proprietary View-model | Understanding the impact of **Upper Funnel** channels, with even more emphasis given to Upper Funnel. |
| Clicks + Deterministic Views | Hard click data + platform-verified views | Two parts: (1) Clicks-Only (2) Verified Views | Understanding the impact of **Upper-Funnel** channels using deterministic, non-modeled view data. |
***
### First Touch
**When to Use First Touch**: Anytime you want to give credit to the very first touchpoint (ie, subscriptions, or gut checking MTA data). In this model, full credit is given to the first touchpoint of the customer journey.
***
### Last Touch and Last Non-Direct Touch
**When to use Last Touch**: This is the least-used model in our system, but its great for reviewing lift in direct traffic or performance over time.
**When to use Last Non-Direct Touch**: This model compares consistently well with Google Analytics' "Last Click" and is a strong number to compare to ground data in a familiar environment. It is also great for monitoring Bottom of Funnel performance.
In these models, full credit is given to the last touchpoint of the customer journey, but Last Non-Direct Touch does not give credit to Direct if it is the final touchpoint.
As an example, let's take the following customer journey that resulted in a \$90 order.
| | Revenue Credit using Last Touch | Revenue Credit using Last Non-Direct Touch |
| :- | :- | :- |
| Jan 1 - Facebook Click | \$0 | \$0 |
| Jan 2 - Google Click | \$0 | \$90 |
| Jan 3 - Direct Visit | \$90 | \$0 |
This model is great to understand the impact of your lower funnel channels — Branded Search, Organic Search, and Email/SMS to name a few.
***
### Linear
**When to use Linear**: Typically for channels that are in the middle of the funnel (i.e. organic social).
Linear divides credit equally across all channels.
***
### Clicks-Only
**When to use Clicks-Only**: Great for day-to-day decision making. This will be more conservative, but makes for a very useful prospecting compass.
This proprietary model is **similar to linear,** where credit is divided equally between all touchpoints.
Difference between Clicks-Only and Linear
Generally speaking, Clicks-Only is similar to Linear, but gives an emphasis to your Upper Funnel channels.
In Clicks-Only, **credit is not given to Lower Funnel touchpoints if there are Upper Funnel touchpoints in the journey**. The only instance where Lower Funnel touchpoints receive credit is if there are no Upper Funnel touchpoints in the journey.
#### You may be asking yourself
* "What's an Upper Funnel Touchpoint?"
* "What's a Lower Funnel Touchpoint?"
* "How does the credit allocation work?"
* "Why isn't credit given to Lower Funnel Touchpoints?"
Let's dive in to your questions:
What are Upper Funnel and Lower Funnel channels?
#### Lower Funnel Channels
* Direct Visits (Labeled as "Organic" in the dashboard)
* Organic Search
* Paid Branded Search
* Email or SMS
#### Upper Funnel Channels
* Any channel that is NOT a lower funnel channel (ex. Paid Social, Paid Search (excluding Brand), PMax, Organic Social, Affiliate, Influencer, Display, etc)
Please Note
We understand these "Upper Funnel" channels may not always be used to grow the top of the funnel in your particular media strategy.
#### Clicks-Only: Example 1
Let's take the following journey and assume we're on the Accrual accounting mode, where credit is given to the following touchpoints.
1. Jan 1 - Facebook Ad click
2. Jan 2 - TikTok Ad click
3. Jan 3 - Google Branded Search Ad click, resulting in a \$90 purchase.
| | Jan 1 | Jan 2 | Jan 3 |
| :- | :- | :- | :- |
| Facebook Ad | **\$45 revenue; 0.5 transactions** | \$0 revenue; 0 transactions | \$0 revenue; 0 transactions |
| TikTok Ad | \$0 revenue; 0 transactions | **\$45 revenue; 0.5 transactions** | \$0 revenue; 0 transactions |
| Google Branded Search Ad | \$0 revenue; 0 transactions | \$0 revenue; 0 transactions | \$0 revenue; 0 transactions |
**Explanation:** Although the Branded Search pushed the conversion, Branded Search does not get credit with Clicks-Only because this is a Lower Funnel Channel. Therefore, credit is distributed equally to Facebook and TikTok.
#### Clicks-Only: Example 2
Here's another example. Let's say the entire journey is made up of Lower Funnel Touchpoints:
1. Jan 1 - Google Branded Search Ad click
2. Jan 2 - Direct Visit
3. Jan 3 - Email click, resulting in a \$90 purchase.
| | Jan 1 | Jan 2 | Jan 3 |
| :- | :- | :- | :- |
| Google Branded Search Ad | **\$30 revenue; 0.3 transactions** | \$0 revenue; 0 transactions | \$0 revenue; 0 transactions |
| Direct Visit | \$0 revenue; 0 transactions | **\$30 revenue; 0.3 transactions** | \$0 revenue; 0 transactions |
| Email | \$0 revenue; 0 transactions | \$0 revenue; 0 transactions | **\$30 revenue; 0.3 transactions** |
**Explanation:** Because all the touchpoints are Lower Funnel, credit is distributed evenly. Credit is only pulled when an Upper Funnel touchpoint is recognized in the journey.
Why is Clicks-Only Useful?
**Clicks-Only Puts Emphasis on Upper Funnel Channels**
The whole idea of Clicks-Only is to see the directional impact of your Upper Funnel channels, as this is where budget is normally controlled and where businesses scale.
Let's say there are 50 conversions attributed to a Lower Funnel channel like Branded Search. That's normally great to see, Branded Search is likely doing its job and cleaning purchase journeys. The challenge lies in its actionability. In other words, this channel usually isn't super actionable, particularly from a media buying or budget adjustment standpoint. It's normally difficult to scale lower funnel channels due to their finite audience. As a matter of fact, these conversions are usually a result of an Upper Funnel Channel touchpoint. Therefore, by moving the credit up the funnel, we're able to pull the curtain back and see what actually drove the conversion.
**Clicks-Only is Conservative**
Clicks-Only is strictly based on hard click data — like all the other models, except for Clicks + Modeled Views. What we mean by this is that we're only attributing conversions that resulted in a click from a referring channel or campaign. We're not doing any modeling, unlike in Clicks + Modeled Views. We also divide credit between the touchpoints, resulting in an even more conservative view.
The upside here is that it's very directionally accurate. If a channel or campaign has strong performance in Click-Only, there's normally strong conviction that it's driving **incremental revenue** for your business.
***
### Clicks + Modeled Views
Our Northbeam attribution models leverage machine learning to ingest your data and stitch together customer journeys so you can start accounting for view-through data when analyzing attribution decisions.
Clicks + Modeled Views provides directionality on which ads within a channel are driving the most results and which ones are ineffective.
Utilizing the Clicks + Modeled Views model in conjunction with Northbeam’s Clicks-Only attribution model can help you fill in any “click-through” gaps, particularly for channels like Social and Video that are highly view-oriented.
#### What exactly is the Clicks + Modeled Views Attribution Model?
Clicks + Modeled Views is Northbeam’s proprietary machine learning model that accounts for impression and ad engagement data when making attribution decisions. This model looks to split attribution credit on a multi-touch basis.
it reduces attribution credit to any direct, organic search, paid branded search, or email/SMS touchpoints in the customer's journey, and gives appropriate credit to Views at any point throughout the customer's journey.
Note: View-Through data measures how many visitors saw your ad but did not click.
We built this model because unattributed traffic is not helpful for marketers when trying to analyze which channels are powering their highest-converting paths. Although our Clicks-Only model is our most accurate model because clicks are hard data, there are many conversions that won’t be captured: clicks don’t represent the entire picture.
We understand that many customers eventually convert via direct visits after watching a TikTok, YouTube, or Facebook ad. This is why our Clicks + Modeled Views model tries to assign proper credit to any ad views throughout a conversion path. This can help make your data actionable by giving you a more complete picture of what’s going on with your campaigns.
#### How does Clicks + Modeled Views work?
At a high level, our model tracks engagement metrics (impressions, video views, etc.) and looks for correlations between those metrics and any corresponding organic spikes. Our model then makes an educated guess using machine learning to assign organic traffic and conversions to the ad campaign that were mostly likely to prompt that behavior.
Please note the attribution window for Clicks + Modeled Views is 1 day view only, regardless of which option you select.
#### When do you use Clicks + Modeled Views?
Keep in mind, our Clicks + Modeled Views model takes 25-30 days to "learn" from the historical data collected by our tracking pixels.
One of the most common questions we get is: *Which attribution model is the best one to use to make media buying decisions?*
The answer is: **Clicks + Modeled Views offers directionality of which views are driving incremental revenue**.
Look for big gaps between revenue reported in Clicks Only vs. Clicks + Modeled Views to better understand what assisted organic conversions.
We recommend using [Model Comparison](https://dashboard.northbeam.io/model-comparison) in Northbeam to do this. You can also open it from the menu in the top-right corner of your dashboard.
Let’s say you notice that Clicks + Modeled Views captures a revenue attributed to YouTube ads that weren’t captured in Clicks Only. This could mean that YouTube ads are driving revenue, but we should try and validate these results before dramatically scaling spend.
One way to do that is to conduct post-purchase surveys and track where incremental revenue is coming from. You could also slowly ramp up spend on YouTube while keeping an eye on blended revenue numbers to see if they’re highly correlated. If post-purchase surveys are also indicating YouTube as a leading channel, then you can be reasonably confident that YouTube ads are having a positive and additive impact on your business.
#### What is the benefit of looking at the Clicks + Modeled Views model?
Ultimately, the Clicks + Modeled Views can help you better allocate your marketing dollars. You spend less on conversion ads if more people view them, don’t click, and then later purchase.
It is great for understanding the full impact of prospecting performance, and also useful for monthly reporting on prospecting channels.
***
### Clicks + Deterministic Views
Clicks + Deterministic Views (C+DV) is Northbeam’s most advanced multi-touch attribution model. It builds on the Clicks-Only framework and extends beyond Clicks + Modeled Views by incorporating platform-verified impression and view data from participating ad platforms.
While Clicks + Modeled Views uses machine learning to infer the impact of ad views, Clicks + Deterministic Views only assigns view credit when an impression is explicitly verified by the ad platform and deterministically linked to a conversion.
At a high level, this means:
* Combines first-party paid click data with platform-verified ad views to measure the full impact of paid media.
* Uses deterministic matching only. Views are credited only when explicitly verified by the ad platform and linked to a conversion.
* Excludes lower funnel touchpoints (Direct, Organic, Branded Search, Email, SMS) from receiving credit when paid clicks or verified views are present.
* Assigns view credit at the platform level, then distributes that credit across individual **verified** view touchpoints from that platform.
* Provides clearer insight into view-heavy channels like Paid Social, Video, and CTV that last-click models miss.
**When to use Clicks + Deterministic Views**:\
Use this model when you want the most accurate view of upper funnel impact and when participating ad platforms are enabled for deterministic view matching.
For full details on how Clicks + Deterministic Views works, including credit allocation logic, examples, platform eligibility, and setup instructions, see the dedicated documentation:
👉 Clicks + Deterministic Views: [/docs/clicks-deterministic-views](/docs/clicks-deterministic-views)
# Attribution Home Page
Source: https://docs.northbeam.io/docs/attribution-page
This is your operational hub.
The **Attribution Home Page** is your central hub for daily actions and changes.
Here, your team of media buyers, channel managers, and any related-to-platform team can decide which platforms, campaigns, ads, and assets to adjust and improve for better performance.
Your default setting on this page is **Attribution**: *Revenue*, which shows the following:
* Sales
* New Customers
* Returning Customers
- Top of Funnel (Demand Capture)
- Bottom of Funnel (Demand Generation)
- Organic and Owned Media
On the right side of your screen, you will see Profitability, which cannot be utilized until you have passed the 90-day learning period with Northbeam. Learn more about [Profitability Benchmarks here](/docs/profitability-benchmarks).
You will also see the other tabs that contain:
* *Product Analytics*
* *Orders*
* *Creative Analytics*
# ✅ Up next
This Attribution Home Page allows you to understand daily performance and evaluate performance across campaigns, channels, and funnel stages. Let's dive deeper into the different Attribution Home Page settings.
# Attribution Windows
Source: https://docs.northbeam.io/docs/attribution-windows
We offer a variety of Attribution Windows to help inform your decision-making
The length of time in which a touchpoint receives credit for a purchase.
Accrual onlyAttribution windows are only available using the Accrual accounting mode.
## Which attribution windows are available?
Click-based models
All click-based models except Clicks + Modeled Views
Windows are also offered for any formulaic metric that contains a conversion metric, such as ROAS and CAC.
Within the dashboard, every metric with an Attribution Window has either a "(d)" or "LTV." For example: Attributed Rev (1d), LTV Attributed Revenue, ROAS (7d), LTV ROAS, CAC (3d), LTV CAC.
| Attribution Window | Meaning | Definition |
| :- | :- | :- |
| (1d) | 1-day window | Credit is given from conversions that occurred within 1 day after the touchpoint. |
| (3d) | 3-day window | Credit is given from conversions that occurred within 3 days after the touchpoint. |
| (7d) | 7-day window | Credit is given from conversions that occurred within 7 days after the touchpoint. |
| (14d) | 14-day window | Credit is given from conversions that occurred within 14 days after the touchpoint. |
| (30d) | 30-day window | Credit is given from conversions that occurred within 30 days after the touchpoint. |
| (60d) | 60-day window | Credit is given from conversions that occurred within 60 days after the touchpoint. |
| (90d) | 90-day window | Credit is given from conversions that occurred within 90 days after the touchpoint. |
| LTV | Infinite Window | Credit is given from conversions that occurred any time after the touchpoint. |
## Attribution window examples
To understand the credit allocation based on the different attribution windows, let's take an example.
01Jan 1 — Facebook Ad click
02Jan 3 — Google Ad click
03Jan 5 — Direct visit resulting in a purchase for \$90
For simplicity, let's say we're using an equal weighting model (Linear) in the Accrual Accounting Mode.
### Jan 1 performance
| Platform | Attributed Rev (1d) | Attributed Rev (3d) | Attributed Rev (7d) | LTV Attributed Rev |
| :- | :- | :- | :- | :- |
| Facebook | \$0 | \$0 | **\$30** | **\$30** |
| Google | \$0 | \$0 | \$0 | \$0 |
| Direct | \$0 | \$0 | \$0 | \$ |
Remember, we're using the Accrual mode, so credit is only given to touchpoints that occurred on Jan 1st, which in this case is Facebook.
The purchase happened 4 days after the Facebook touchpoint. As a result, the 1-day and 3-day windows do not get credit. But, the 7-day and LTV windows do since 4 days falls within both of these windows.
### Jan 3 performance
| Platform | Attributed Rev (1d) | Attributed Rev (3d) | Attributed Rev (7d) | LTV Attributed Rev |
| :- | :- | :- | :- | :- |
| Facebook | \$0 | \$0 | \$0 | \$0 |
| Google | \$0 | \$30 | \$30 | **\$30** |
| Direct | \$0 | \$0 | \$0 | \$0 |
We're using the Accrual mode so only the touchpoints that occurred on Jan 3 receive credit, which in this case is Google.
The purchase happened 2 days after the Google touchpoint. Therefore, 1-day window does not get credit. But, 3-day, 7-day and LTV do since 2 days falls within all of these windows.
### Jan 5 performance
| Platform | Attributed Rev (1d) | Attributed Rev (3d) | Attributed Rev (7d) | LTV Attributed Rev |
| :- | :- | :- | :- | :- |
| Facebook | \$0 | \$0 | \$0 | \$0 |
| Google | \$0 | \$0 | \$0 | \$0 |
| Direct | **\$30** | **\$30** | **\$30** | **\$30** |
Again, we're using the Accrual mode so only the touchpoints that occurred on Jan 5 receive credit, which in this case is Direct.
The purchase happened the same day as the Direct touchpoint. Because this was less than 24 hours, this falls within all of the attribution windows.
### Jan 1–5 performance
Let's put it all together. As a reminder, this is our journey:
01Jan 1 — Facebook Ad click
02Jan 3 — Google Ad click
03Jan 5 — Direct visit resulting in a purchase for \$90
| Platform | Attributed Rev (1d) | Attributed Rev (3d) | Attributed Rev (7d) | LTV Attributed Rev |
| :- | :- | :- | :- | :- |
| Facebook | \$0 | \$0 | **\$30** | **\$30** |
| Google | \$0 | **\$30** | **\$30** | **\$30** |
| Direct | **\$30** | **\$30** | **\$30** | **\$30** |
# Authentication
Source: https://docs.northbeam.io/docs/authentication
Every Northbeam API request is authenticated with two headers
All Northbeam APIs use the same two headers, on every request:
| Header | Value |
| :- | :- |
| `Authorization` | Your API key |
| `Data-Client-ID` | Your client ID |
## Where to find your credentials
Both values live in the Northbeam dashboard under [API Keys](https://dashboard.northbeam.io/settings/api-keys):
* **API Key** — sent as the `Authorization` header
* **Client ID** — sent as the `Data-Client-ID` header
## Example
```bash theme={null}
curl --request GET \
--url https://api.northbeam.io/v2/orders \
--header 'Authorization: ' \
--header 'Data-Client-ID: '
```
A `401 Unauthorized` response means the API key or `Data-Client-ID`
header is missing or invalid. See [Errors](/docs/errors) for the full
list of response codes.
## Keep credentials out of your client
Treat the API key like a password: send it only from your servers, never
from a browser or mobile app, and rotate it if it's ever exposed.
# Best Practices by Teams and Departments
Source: https://docs.northbeam.io/docs/best-practices-by-teams-and-departments
Proven strategies and tips to help you get the most out of Northbeam.
This section provides recommended best practices tailored to common teams and departments. Whether you are setting up attribution models, analyzing reports, or optimizing campaigns, these tips are designed to guide you:
#### [Paid Social Team](/docs/paid-social-team)
#### [Paid Search Team](/docs/paid-search-team)
#### [Executive Team](/docs/executive-team)
#### [Email/SMS/Retention Team](/docs/email-sms-retention)
#### [Offline Channel](/docs/offline-channel)
#### [Influencer](/docs/tracking-for-other-platforms)
These best practices are based on the most common requests we hear from users, so let us know if you have any other questions or requests.
Otherwise, you can move on to the next section: **[Dashboard Day 30, 60, 90](/docs/northbeam-apex).**
# Business Information
Source: https://docs.northbeam.io/docs/business-information
Add your basic details about you and your company.
## Company name
* This is the going to be the name of your Dashboard. We recommend using the business name, as opposed to a different entity associated to the business such as an agency.
* That said, this can be always be adjusted down the road (post-onboarding).
## Timezone
* The selected timezone is used across your dashboard for all users in your account.
* This is important to understand when you begin comparing Northbeam-reported data with any other in-platform data. If the timezones don't align, there will likely be disparity in the data.
* For example, if Northbeam is set to Pacific Time, but Facebook Ads is set to Eastern Time. The ad spend for a selected date range may not line up.
# Case scenario: Cash snapshot vs Accrual performance
Source: https://docs.northbeam.io/docs/case-scenario-cash-vs-accrual
**Cash snapshot** accounting mode is the typical report-based accounting mode, where the credit for the purchase is applied on the date that the purchase took place. The **Accrual performance** accounting mode, on the other hand, shifts the credit to the date that the marketing touchpoint occurred.
Accrual performance is important because it aligns revenue and transactions with the media spend that drove it, empowering media buyers to make decisions based on the entire customer journey, rather than just based on a given purchase date.
# Is there a normal/standard delta between cash and accrual?
There is **no standard delta** between our cash and accrual accounting modes.
Since the Accrual Performance accounting mode is credited and fractionalized based on when the marketing touch point(s) took place, the **delta between cash/accrual will change based on how many touch points there were and how much time has passed since the touch point(s)**. Your revenue will also change based on which attribution window (1d, 30d, 90d, etc.) you’re looking at.
**The delta is also significantly different between businesses in different industries,** because customer journeys are so unique.
* A business with a very short conversion cycle will typically have a smaller delta
* A business with a long conversion cycle will typically have a larger delta
The important thing to remember about this is that while **cash snapshot** accounting is often best for reporting and budget-making, **accrual performance** accounting is often the best for profitable media buying and decision-making when looking at individual channels.
# Release Notes
Source: https://docs.northbeam.io/docs/changelog
What's new in Northbeam.
Reorganized the documentation into a product-led structure, consolidated
duplicate content, and added dedicated pages for Incrementality and Mixed
Media Modeling.
# Amazon FAQ
Source: https://docs.northbeam.io/docs/channels/amazon/faq
## Amazon Integration FAQ
### I've connected my Amazon Accounts, but don't see any data?
After connecting, we begin importing your Amazon data, starting with the **oldest orders and moving to the newest.** The time required to backfill your orders varies based on order volume.
| Metric | Source | How Long Before Data Fully Populates? | How Much Historical Data is Included? | Additional Details |
| :- | :- | :- | :- | :- |
| Revenue | Amazon Seller Central | Typically 1-2 days | From January 1, 2000, to the present. | Populates oldest to newest. High order volumes and Amazon's API limitations on data retrieval slow the process compared to other platforms. |
| Spend | Amazon Ads | Typically 2-3 days | From 58 days prior to connecting your account to Northbeam. | Populates oldest to newest. Spend data is limited to the past 58 days by Amazon's API, which we retrieve shortly after connecting your account. |
### How can I check the progress of the backfilling process?
Revenue and Spend are both retrieved starting from the most historical data (Oldest to Newest). Revenue typically takes longer due to the larger volume of data.
You can track revenue and order progress anytime on the [Orders page](https://dashboard.northbeam.io/orders) (see graphic below).
### Can Northbeam distinguish between First-time and Returning Amazon Customers?
Yes, for **Fulfilled by Amazon (FBA)** orders.
Northbeam can recover the buyer identifier needed to classify FBA orders as New or Returning.
This also applies to historical FBA orders. Orders that were previously classified as **Unknown** after the February 2026 Amazon change are backfilled and can be updated to New or Returning.
A few limitations apply:
* **Merchant-fulfilled orders** cannot currently be classified as New or Returning.
* **Recent FBA orders** may appear as Unknown for a few days because the buyer identifier becomes available after shipment.
* **Canceled orders** may not include the buyer identifier needed for classification.
Orders that cannot be classified still count toward total Amazon Revenue and Orders.
### Is there any way to identify New vs Returning Amazon customers now?
There are two options:
**1. Within Northbeam (orders-based)** Historical Amazon orders fetched prior to February 10, 2026 — where we received a buyer identifier — still retain their New/Returning classification.
**2. Amazon Ads "New-to-Brand" platform metrics** Amazon Ads provides its own "new-to-brand" metrics that estimate whether a purchase is from a new customer (Amazon's definition, 14-day lookback). These are calculated by Amazon, not Northbeam's orders-based identity model, but can serve as a directional signal for new customer acquisition on Ads.
You can find these metrics under **Amazon Ads reported** in your metrics selector:
### Why are my Amazon orders showing as Unknown?
An Amazon order appears as **Unknown** when Northbeam does not have the buyer identifier needed to classify it as New or Returning.
This can happen when:
* The FBA order has not shipped yet.
* Amazon has not made the shipment data available yet.
* The order is merchant-fulfilled.
* The order was canceled.
Recent FBA orders may remain Unknown for a few days after the order is placed.
Historical FBA orders that were previously Unknown are backfilled and can be updated to New or Returning once the required data is available.
Unknown orders still count toward total Amazon Revenue and Orders.
### Why don't my New + Returning totals match my Amazon totals?
New vs. Returning classification is available for **FBA orders**, but not for merchant-fulfilled Amazon orders.
Some recent FBA orders may also temporarily appear as Unknown while Northbeam waits for shipment data from Amazon.
Because these orders still count toward total Amazon Revenue and Orders:
> **New + Returning may be lower than your total Amazon Revenue or Orders.**
For the most complete view of Amazon performance, use total Amazon metrics instead of adding New + Returning together.
### How do I connect an extra account or remove an account?
Reference our step-by-step guide below:
When your Amazon connections are removed, your historical data will still be stored in your dashboard. If you'd like to remove your data, please [submit an inquiry](https://www.northbeam.io/submit-a-support-ticket).
### Is there an integration with Amazon DSP or Vendor Central?
We're afraid we do not support Amazon DSP or Vendor Central at this time. If you'd like to upload costs from Amazon DSP, feel free to use a Custom Spendsheet.
### Why can’t I see Amazon data on hourly view?
Amazon Ads does not provide access to hourly data, thus the data you will see will not be reflective of what is going on hour by hour. However, Amazon Seller does provide reporting accurate to the hour.
### How do I integrate with Amazon?
Open [Connections](https://dashboard.northbeam.io/settings/connections), then connect **Amazon Seller** and **Amazon Ads**. Follow the steps for each that Amazon provides until you’re redirected back to Northbeam. You should see the account become connected.
### How do I connect multiple Amazon accounts?
Northbeam supports multiple Amazon account connections.
**Amazon Ads (PPC spend)**
For Amazon Ads, you can connect multiple regional ad profiles under the same business accounts (e.g., Business (US), Business (CA), Business (UK)).
**Amazon Seller Central (Revenue)**
For Amazon Seller Central, you can also connect multiple marketplace groups (e.g., North America, Europe, Far East). However, each connection pulls revenue for all countries within that marketplace group, and it’s not currently possible to filter revenue by individual country within a group.
If you're operating across multiple regions or businesses, you can connect as many accounts as needed to get a full view of your Amazon ad spend and revenue in Northbeam.
### What is the difference between the Amazon and Amazon Seller connections?
Our Amazon Ads connection gives Northbeam access to your Amazon advertising channel. This includes impression data and spend data broken down by country.
The Amazon Seller connection gives us access to your Amazon Seller account data that provides access to your order history.
### How often is Amazon data updated within Northbeam?
We will update hourly. However, due to limitations in the Amazon APIs, you should treat any data from the last 24 hours as "preliminary results".
### How far back does Amazon Ads data go?
For Amazon Ads, we retrieve spend data for the past 58 days from the date the account was linked. For Amazon Seller, we gather orders data starting from January 1, 2000, up to the present.
### How should I review Amazon data? (By day / week)
We recommend reviewing Amazon data on 3 and 7 day look backs vs day of data.
### Is this Amazon integration able to see attribution from Facebook / TikTok ads or influencers?
Not currently, though this is something we’re planning to work on in the future.
### Why are there discrepancies between my daily Amazon Ads spend on Northbeam when compared to looking at the Amazon Ads dashboard?
If there is a difference between the time zone you've configured in Amazon Ads and the time zone you've configured in Northbeam, you may see a minor discrepancy in your daily spend totals for Amazon Ads.
### Why is the data seen in Northbeam's dashboard different from what I see in Amazon's Seller Central (e.g. Business Report - Sales & Traffic)?
The data can differ due to a variety of reasons:
* Timezone: Northbeam's data is presented in the UTC timezone.
* Order status:
* Canceled orders are not considered in the total revenue
* For merchant-fulfilled orders, we do not have the order total when it's in Pending status.
* Some discrepancies are expected across Amazon's reports. This is due to how the data is pivoted and the data source. Go to the following link for more information: [https://sellercentral.amazon.com/help/hub/reference/200633570](https://sellercentral.amazon.com/help/hub/reference/200633570)
### Where does Northbeam fetch my sales data?
Currently, Northbeam fetches data from three different sources: All Orders Report, Product Fees API, and Order Returns Report.
### How an order revenue is calculated?
The order total is calculated using this formula:
### Why do I see a data discrepancy?
##### Spend Discrepancies
If there is a difference between the time zone you've configured in Amazon Ads and the time zone you've configured in Northbeam, you may see a minor discrepancy in your daily spend totals for Amazon Ads.
##### Order Discrepancies
Our orders and revenue should match the following report in Amazon Seller Central: *Business Report - Sales & Traffic*
However, the data can differ due to a variety of reasons:
* Timezone: Northbeam's data is presented in the UTC timezone.
* Order status:
* **Canceled orders** are not considered in the total revenue
* For merchant-fulfilled orders, we do not have the order total when it's in **Pending** status.
Some discrepancies are expected across Amazon's reports. This is due to how the data is pivoted and the data source. Go to the following link for more information: [https://sellercentral.amazon.com/help/hub/reference/200633570](https://sellercentral.amazon.com/help/hub/reference/200633570)
#### If you suspect a tracking issue, please review the following
* **Connection**: Make sure your accounts are still connected. Open [Connections](https://dashboard.northbeam.io/settings/connections) and check for any errors. Connections could break for a variety of reasons, but most commonly, the user losing access to the ad account.
# Amazon Setup
Source: https://docs.northbeam.io/docs/channels/amazon/overview
Connect Amazon Seller Central and Amazon Ads so Northbeam reports your Amazon revenue and ad spend.
When you're done, Northbeam shows your total revenue from Amazon Seller Central and your ad spend from Amazon Ads.
**Before you start**, make sure you have:
* An **Amazon Seller Central** account
* An **Amazon Ads** account
* An Amazon login with **admin access** to the ad account
Connect Amazon Seller for revenue and Amazon Ads for spend.
Check the connections and wait for the backfill.
Connect **both** accounts. Northbeam uses the Amazon Seller and Amazon Ads APIs to pull your revenue and PPC spend from your Amazon marketplaces.
| Connection | What it pulls |
| :- | :- |
| [Amazon Seller Central](https://sellercentral.amazon.com/) | Total revenue reported in Seller Central |
| [Amazon Ads](https://advertising.amazon.com/) | Total spend reported in Amazon Ads (e.g. PPC costs) |
1. Open [Connections](https://dashboard.northbeam.io/settings/connections). If you're still in onboarding, go to **Integrations** instead.
2. Find **Amazon Seller** and click **Connect**. Then do the same for **Amazon Ads**.
3. Sign in with an Amazon login that has **admin access** to the ad account, and follow Amazon's steps until you're sent back to Northbeam.
**If you skip this step:** without Amazon Seller, your Amazon revenue is missing. Without Amazon Ads, your Amazon spend is missing.
**Allow time for the backfill.** Northbeam imports Amazon data from oldest to newest. Revenue usually takes 1–2 days to fill in, and spend 2–3 days. You can track revenue and order progress on the [Orders page](https://dashboard.northbeam.io/orders).
To check the connections, follow [Checking platform connections](/docs/checking-api-connections) to confirm both accounts show as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## What the Amazon integration covers
**We're still working on Amazon attribution.** Today the integration is mainly for reporting: it pulls the revenue and spend reported in your Amazon accounts.
Northbeam only supports **Amazon Seller Central** and **Amazon Ads** right now. Other Amazon channels, like **Vendor Central** and **DSP**, aren't supported yet. They're on the roadmap, with no ETA.
In the meantime, you can use a Spendsheet or the Spend API to get their costs into your dashboard. If your business uses these channels, please [tell our team](https://www.northbeam.io/submit-a-support-ticket). We treat it as product feedback, and it helps shape what we build next.
## Need help?
Common Amazon setup and reporting questions.
Start here if a check above fails.
# AppLovin FAQ
Source: https://docs.northbeam.io/docs/channels/applovin/faq
## AppLovin FAQ
### 1. Where is my data?
Your data should populate in Northbeam after the next data refresh. Typically, this occurs within 24 hours of completing the integration. If data is still missing, double-check that the Report API Key and Account ID were entered correctly.
### 2. What attribution models does the AppLovin integration support?
The AppLovin integration supports all attribution models available in Northbeam.
### 3. What should I do if my AppLovin data isn't appearing?
1. Verify that your AppLovin Report API Key and Account ID are correctly configured in [Connections](https://dashboard.northbeam.io/settings/connections).
2. Ensure Northbeam UTM parameters have been added to your creatives — including any creatives using **"Use another URL"**, which require UTMs to be set at the creative level separately.
3. Check if your spend source was previously uploaded via a custom spend sheet or API. If so, make sure there is no duplication causing discrepancies. Refer to [Remove custom spend (optional)](/docs/channels/applovin/overview#remove-custom-spend-optional).
### 4. Why isn't my ad spend lining up?
Discrepancies in ad spend can often arise due to differences in **timezones** between Northbeam and AppLovin. By default, AppLovin reports data using **UTC**, whereas your Northbeam timezone is likely set to a different time zone, which you configured during onboarding.
To verify your Northbeam timezone:
1. Open [Profile](https://dashboard.northbeam.io/settings/profile) in your Northbeam account.
2. Locate the Timezone field.
For any additional questions, feel free to submit a [Support ticket](https://www.northbeam.io/submit-a-support-ticket).
# AppLovin Setup
Source: https://docs.northbeam.io/docs/channels/applovin/overview
Connect AppLovin with your Report API Key and Account ID, then select Northbeam as the measurement partner so spend and revenue line up.
When you're done, Northbeam shows your AppLovin spend, impressions, visits, and attributed revenue on the same campaigns, ad sets, and ads, alongside your other channels.
**Before you start**, make sure you have:
* The AppLovin **master user account** login (sub-user accounts won't work)
* Access to edit your AppLovin campaigns and creative sets
Copy your Report API Key and Account ID into Northbeam.
Select Northbeam as the measurement partner on your campaigns.
Check that parameters and spend are reaching Northbeam.
**Copy your Report API Key**
1. Log in to **AppLovin** with your **master user account**. Sub-user accounts won't work.
2. Open the top-right menu → **Keys**.
3. Copy the **Report Key**. This is your API Reporting Key.
**Find your Account ID**
1. Still logged in with the master user account, open the top-right menu → **Other Settings**.
2. Copy your **Account ID**.
**Add your credentials in Northbeam**
1. Open [Connections](https://dashboard.northbeam.io/settings/connections) in your Northbeam dashboard.
2. Find the **AppLovin** section.
3. Enter your **Account ID** and **Report API Key**.
**If you skip this step:** campaign, ad set, and ad names are missing, along with spend, impressions, and AppLovin-reported metrics.
**On every campaign**
1. Click **Edit Campaign**, then **Objective**.
2. Scroll down to **Tracking Parameters** and click **Edit**.
3. Under **Measurement Partner Parameters**, select **Northbeam**.
4. Click **Confirm**.
**On creatives set to "Use another URL"**
You only need this if a creative's Destination URL is set to **"Use another URL"**. Those creatives have their own URL and UTMs and don't inherit the campaign-level Northbeam UTMs, so add Northbeam at the creative level too:
1. Open the **Creative Set Settings**.
2. Scroll to **Tracking Parameters** and click **Edit**.
3. Under **Measurement Partner Parameters**, select **Northbeam**.
4. Click **Confirm**.
**If you skip this step:** Northbeam can't tie visits and orders to your AppLovin ads, so spend and revenue show up on separate lines.
Data usually shows up after the next data refresh, typically within 24 hours of connecting. If it's still missing, check that the Report API Key and Account ID were entered correctly.
For a full check:
* **Parameters captured:** follow [Checking UTM tracking](/docs/checking-utm-tracking) to confirm the Northbeam parameters reach your landing pages.
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## Remove custom spend (optional)
If you used to upload AppLovin spend through a custom spend sheet or API, adjust or remove those entries so spend isn't counted twice now that the integration pulls it in.
1. **Find the source.** Review your custom spend sheet or API setup (see [Add spend](/docs/add-spend)).
2. **Check for overlap** with the spend the AppLovin integration now pulls in.
3. **Adjust if needed.** If there's overlap, adjust or remove the overlapping entries. If there's no overlap, leave them as they are.
Duplicate spend entries can cause incorrect reporting and data discrepancies in Northbeam.
## Need help?
Common AppLovin setup and reporting questions.
Start here if a check above fails.
# Attentive FAQ
Source: https://docs.northbeam.io/docs/channels/attentive/faq
## Attentive FAQ
### 1. Do I need specific UTM parameters?
Nope - as long as you're using standard tracking parameters with any values you'd like, we'll be all set.
Standard Tracking Parameters:
* utm\_source
* utm\_medium
* utm\_campaign
### 2. Does Northbeam import Attentive spend?
We do not import your ad spend from Attentive account.
If you'd like, you could upload your spend numbers through a Custom Spendsheet. Reference [this article](/docs/tracking-for-other-platforms) under "Step 2: Upload Costs via Custom Spendsheet".
### 3. Why do I see a data discrepancy?
**Discrepancies in Revenue and Orders are expected.** The reason for this lies in the differences between Northbeam's attribution model and the corresponding platform's attribution model. Each attribution model has a unique method of allocating credit.
For example, Northbeam's Clicks-Only model divides credit across all touchpoints and tries to push credit to your upper funnel channels. Let's say your in-platform model uses Last Click, which gives credit to the last touchpoint in the journey. This is going to cause a discrepancy.
To take it one step further, let's say both Northbeam and in-platform are using Last Click. Northbeam is unique in that we recognize all touchpoints from every single channel. Whereas most platforms only recognize touchpoints from that same platform.
In addition, there's often a difference in the attribution window. By default, Northbeam leverages a 1-Day window, which is different than many other platforms' default.
To get the most apples to apples comparison, be sure to compare data using same Attribution Model and Attribution Window. But keep in mind, it will never be exact.
#### Attribution Models and Windows
**Attentive:**
* Attribution Model: Last Click
* Attribution Window: 30-Day Click, 1-Day View
* [Source: Attentive Attribution Settings](https://help.attentivemobile.com/hc/en-us/articles/7050482152212-FAQs-Attentive-s-attribution-model#h_01HK8G692Z2ZPSXCM7ZWPJJHD3)
**Northbeam:**
* Attribution Model: Varies (default is Clicks-Only)
* Attribution Window: 1-Day (default, can extend to an infinite lifetime value)
#### If you suspect a tracking issue, please review the following checklist
* **Connection**: Make sure your Attentive SFTP Credentials did not change. Reference[ this guide](https://docs.attentive.com/pages/developer-guides/sftp-solution/connect-to-attentive-sftp/) on how to check your credentials. You're able to use an SFTP client (ex. Cyberduck) to test your credentials.
* If your credentials changed, please [reach out to our team](https://www.northbeam.io/submit-a-support-ticket).
* **Northbeam Pixel**: Ensure the Northbeam Pixel is firing on your landing page. Note that some site themes may not automatically transfer to landing pages on certain third-party apps, necessitating manual pixel placement.
* **Purchase Pixel:** Confirm that the Purchase Pixel is firing on your checkout page.
* **A-Record Setup:** Verify that the A-Record is correctly configured in your DNS Settings.
# Attentive Setup
Source: https://docs.northbeam.io/docs/channels/attentive/overview
Connect Attentive's SFTP data feed so Northbeam can report sign-ups, visits, and revenue from your Attentive campaigns.
When you're done, Northbeam shows the visits, revenue, and orders from your Attentive campaigns and flows, plus email and SMS sign-ups from Attentive's opt-in forms.
**Before you start**, make sure you have:
* An Attentive login with access to the **Settings** tab
* An **Attentive SFTP account**. If you don't have one, ask your Attentive Client Strategy Representative or Attentive's White Glove team ([whiteglove@attentivemobile.com](mailto:whiteglove@attentivemobile.com)).
Set up an SFTP data feed and send Northbeam the login.
See which channels drive your sign-ups.
Check that parameters and data are arriving.
Northbeam connects directly to [Attentive's SFTP data feed](https://docs.attentive.com/pages/developer-guides/sftp-solution/attentive-sftp-data-feeds/), so you need an Attentive SFTP account.
**A. Check for an SFTP account**
1. Log in to Attentive and open the **Settings** tab.
2. Look for **SFTP Account Management**.
If you don't see it, you don't have an SFTP account yet. Request one from your Attentive Client Strategy Representative or [whiteglove@attentivemobile.com](mailto:whiteglove@attentivemobile.com).
**B. Create a permanent password**
New accounts usually get a temporary password. Set a **permanent password** so the connection doesn't break when the temporary one expires. From [Attentive's docs](https://docs.attentive.com/pages/developer-guides/sftp-solution/connect-to-attentive-sftp/):
1. Log in to Attentive and open the **Settings** tab.
2. Select **SFTP Account Management**. If you don't see it, contact [whiteglove@attentivemobile.com](mailto:whiteglove@attentivemobile.com) or your CSM and ask them to create your SFTP account.
3. Click **Reset SFTP Password**. This sends a reset request to Attentive.
4. Follow the instructions in Attentive's email to enter a **Validation Code** and choose your new password.
**C. Ask Attentive to send daily logs**
Once your SFTP account exists, ask your Attentive Client Strategy Representative or [whiteglove@attentivemobile.com](mailto:whiteglove@attentivemobile.com) to turn on daily logs. You can use this email:
> Hi there!
>
> Northbeam is a multi-touch attribution system that helps us understand our customers' digital journey. We are currently working with them and would love to integrate Attentive Mobile reporting into our analytics within their platform.
>
> We'd like to establish a SFTP data feed and would like the following events from the **General Events data feed**:
>
> Daily logs for the following Attentive Mobile events:
>
> * JOIN
> * IMPRESSION
> * CLICK
> * MESSAGE\_RECEIPT
> * MESSAGE\_LINK\_CLICK
> * SUBSCRIPTION\_OPTED\_OUT
> * PURCHASE
>
> Let me know if there's any more information you need for us!
**D. Enter your SFTP login in Northbeam**
After the data feed is set up, add your SFTP credentials (an email address and password):
1. Open [Connections](https://dashboard.northbeam.io/settings/connections).
2. Scroll down to **Attentive**.
3. Enter your **Username and Password**.
4. Click **Connect**.
**If you skip this step:** sign-up volume is missing and the related metrics stay empty.
The connection counts your sign-ups, but it can't tell which channel drove them. To see that (for example, "Facebook Ads drove X sign-ups"), set up a [Custom Goal](/docs/setting-up-custom-goals) that fires when a visitor submits your sign-up form.
Use your custom goal to see which channels drive sign-ups. **Email Sign Ups** shows your total sign-ups from Attentive.
**If you skip this step:** sign-ups show as Unattributed.
For a full check:
* **Parameters captured:** follow [Checking UTM tracking](/docs/checking-utm-tracking) to confirm UTM parameters reach your landing pages.
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## UTMs and spend
**UTM parameters (required):** Attentive doesn't need special Northbeam parameters. Use the standard `utm_source`, `utm_medium`, and `utm_campaign` on your Attentive links, with any values you like. If they're missing, visits and revenue aren't attributed to your Attentive campaigns.
**Spend (optional):** Northbeam doesn't import Attentive spend. To get cost-based metrics like ROAS and CAC, upload your costs with a [Custom Spendsheet](/docs/tracking-for-other-platforms#step-2-upload-costs-via-custom-spend). Without it, no costs are tied to Attentive.
## Need help?
Common Attentive setup and reporting questions.
Start here if a check above fails.
# Channel changelog
Source: https://docs.northbeam.io/docs/channels/changelog
Platform-side changes, outages, and data-definition changes — logged per channel
Ad platforms change: APIs go down, integrations break, and platforms
sometimes redefine what their data means. When that happens, it shows up
in your numbers — this log records it.
This log starts now. Going forward, platform-side incidents, integration
changes, and data-definition changes will be recorded here per channel,
with dates — so when a number moves, you can check whether the channel
itself changed first.
A number moved and there's no entry here? Run
[Diagnose a ROAS drop](/docs/use-cases/diagnose-a-roas-drop) — most
differences are measurement, not outages.
# Google + YouTube Ads FAQ
Source: https://docs.northbeam.io/docs/channels/google/faq
## Google Ads FAQ
### 1. How do I connect an extra account or remove an account?
Reference our step-by-step guide below:
#### Adding an Extra Google Ads Account
Google Ads lets you manage multiple ad accounts under one **Manager Account (MCC)**. Before adding an extra account in Northbeam, you'll need your Manager Account ID handy.
**Before you start:**
* All Google Ads accounts you want to connect to a single Northbeam dashboard must be under the same Manager Account.
* The user shown next to **Connected Account** in your [Connections Page](https://dashboard.northbeam.io/settings/connections) is the one who authenticated the integration. This person must have **Admin access** to both the Manager Account and each individual account being added. Without this, the connection will fail.
***
#### Step 1: Find your Manager Account ID
Log into Google Ads and go to **Accounts**. Your Manager Account ID is the number in the top header (e.g. `651-XXX-XXXX`).
***
#### Step 2: Update the MCC ID in Northbeam
1. Open [Connections](https://dashboard.northbeam.io/settings/connections) and select **Google Ads**.
2. In the field labeled **"Update your login customer id (parent MCC account)"**, replace the existing value with your MCC Account ID.
3. Click **Save**
4. Once saved, click **Add another account** to expand the search panel
5. Search for and select the account you want to add
6. Confirm the connection
**Seeing a warning?**
It usually means your Manager Account ID doesn't match the account you're trying to add. Double-check the ID and try again.
***
#### Removing an Account
To remove a connected account, click the **Delete** button next to the account name in the Connections panel.
### 2. Why do I see a data discrepancy?
**Discrepancies in Revenue, Orders, and Visits are expected.** The reason for this lies in the differences between Northbeam's attribution model and the corresponding platform's attribution model. Each attribution model has a unique method of allocating credit.
For example, Northbeam's Clicks-Only model divides credit across all touchpoints and tries to push credit to your upper funnel channels. Let's say your in-platform model uses Last Click, which gives credit to the last touchpoint in the journey. This is going to cause a discrepancy.
To take it one step further, let's say both Northbeam and in-platform are using Last Click. Northbeam is unique in that we recognize all touchpoints from every single channel. Whereas most platforms only recognize touchpoints from that same platform.
In addition, there's often a difference in the attribution window. By default, Northbeam leverages a 1-Day window, which is different than many other platforms' default.
To get the most apples to apples comparison, be sure to compare data using same Attribution Model and Attribution Window. But keep in mind, it will never be exact.
#### Attribution Models and Windows
**Google:**
* Attribution Model: Last Click (default)
* Attribution Window: 30-Day Click (default)
* [Source: Google Conversion Windows](https://support.google.com/google-ads/answer/3123169?hl=en)
**Northbeam:**
* Attribution Model: Varies (default is Clicks-Only)
* Attribution Window: 1-Day (default, can extend to an infinite lifetime value)
### 3. I think there's an issue with tracking. Please help!
Please reference our [Correct System Setup FAQ](/docs/confirm-setup-requirements).
* **Connection**: Make sure your Ad Account is still connected. Open [Connections](https://dashboard.northbeam.io/settings/connections) and check for any errors. Connections could break for a variety of reasons, but most commonly, the User losing access to the Ad Account.
* **UTMs**: Ensure all your ads contain Northbeam UTMs, as listed in the UTM step above.
* **Northbeam Pixel**: Ensure the Northbeam Pixel is firing on your landing page. Note that some site themes may not automatically transfer to landing pages on certain third-party apps, necessitating manual pixel placement.
* **Purchase Pixel:** Confirm that the Purchase Pixel is firing on your checkout page.
* **A-Record Setup:** Verify that the A-Record is correctly configured in your DNS Settings.
# Google + YouTube Ads Setup
Source: https://docs.northbeam.io/docs/channels/google/overview
Connect your Google Ads account and add the Northbeam parameter so spend and revenue line up.
When you're done, Northbeam shows your Google and YouTube spend, impressions, visits, and attributed revenue on the same campaigns, ad groups, and ads.
**Before you start**, make sure you have:
* A Google login with **admin access** to the Google Ads account
* An **Account Name** set in Google Ads (**Admin > Account Settings > Account Name**)
* Access to **Google Ads** to edit the account-level **Final URL Suffix**
Sync spend, impressions, and campaign structure from Google Ads.
Add `nbt` once in the account-level Final URL Suffix.
Check that the parameter and the connection are working.
1. Open [Connections](https://dashboard.northbeam.io/settings/connections). If you're still in onboarding, go to **Integrations** instead.
2. Find **Google Ads** and click **Connect**.
3. Sign in with a Google login that has **admin access** to the ad account.
The account must have a name in Google Ads. Go to **Admin > Account Settings > Account Name** and make sure one is set. Accounts without a name can't sync into Northbeam. If the name or admin access is missing, the connection fails or your dashboard gets incomplete data.
The connection pulls your current and historical campaigns, ad groups, and ads from the Google Ads API, along with spend, impressions, and Google-reported metrics. Impressions also power the **Clicks + Modeled Views** attribution model.
**Have more than one Google Ads account?** All accounts you connect to one Northbeam dashboard must be under the same **Manager Account (MCC)**. See [Adding an extra Google Ads account](/docs/channels/google/faq#adding-an-extra-google-ads-account).
**If you skip this step:** campaign, ad group, and ad names are missing, along with spend, impressions, and Google-reported metrics.
In Google Ads, add this to the **Final URL Suffix** at the **account level**:
```
nbt=nb%3Aadwords%3A{network}%3A{campaignid}%3A{adgroupid}%3A{creative}
```
**Have existing UTM parameters?** Add the Northbeam parameter to the end (or beginning) and join them with an ampersand (`&`). For example:
```
utm_source=paid&utm_medium=google&nbt=nb%3Aadwords%3A{network}%3A{campaignid}%3A{adgroupid}%3A{creative}
```
To have Northbeam add the parameter to all Google ads in your connected accounts automatically, [ask Support](https://www.northbeam.io/submit-a-support-ticket) to turn on UTM auto-appending.
### UTM Parameter Priority
Google Ads applies UTM parameters by level. **A lower level always overrides a higher level.** From highest to lowest priority:
1. **Ad** level
2. **Ad group** level
3. **Campaign** level
4. **Account** level
So if a campaign, ad group, or ad has its own UTMs, they override the account-level Final URL Suffix you set above.
**Already have UTMs at the campaign, ad group, or ad level?** You have two options:
* **Move your existing UTMs up** to the account level, so all tracking lives in one place.
* **Move the Northbeam parameter down** to the same level as your existing UTMs.
Either works, as long as UTMs are applied consistently and nothing at a lower level overrides them.
**If you skip this step:** Northbeam can't tie visits and orders to your Google ads, so spend and revenue show up on separate lines.
* **Parameters captured:** follow [Checking UTM tracking](/docs/checking-utm-tracking) to confirm the Northbeam parameter reaches your landing pages.
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## Need help?
Extra accounts, data discrepancies, and other common questions.
Start here if a check above fails.
# Impact FAQ
Source: https://docs.northbeam.io/docs/channels/impact/faq
## Impact FAQ
### 1. Can I connect multiple Impact accounts?
At this time, Northbeam supports connecting one Impact account per dashboard.
If you manage multiple Impact accounts, you can still track the others by:
* Connecting one account through the native Impact integration
* Sending spend for additional accounts via a Spend Sheet or Spend API
* Using standard UTMs for tracking on those additional accounts
Any non-connected Impact accounts will work similarly to other [Non-Integrated Channels](/docs/tracking-for-other-platforms).
### 2. Can I use other UTM parameters alongside Northbeam's?
Yes — Northbeam's `nbt` parameter is additive and will not interfere with any other parameters you're already using. Feel free to keep parameters like `utm_source`, `utm_medium`, `utm_campaign`, or any other tracking params for Google Analytics or other platforms. Northbeam only uses `nbt` for attribution.
### 3. I was already using Northbeam's previous recommended UTMs for Impact. Do I need to switch?
You can either swap them out for the new `nbt` parameter or simply add `nbt` alongside your existing params — there's no harm in leaving the old ones in place. Northbeam uses `nbt` to tie sessions back to the correct ad spend, so as long as `nbt` is present, attribution will work correctly.
### 4. Why do I see a data discrepancy?
**Discrepancies in Revenue and Orders are expected.** The key reason is a difference in attribution methodology:
* **Impact's attribution** credits 100% of each conversion to a single partner using Impact's own click-based rules
* **Northbeam's attribution** treats Impact data as one input into cross-channel, multi-touch attribution — so conversions may be shared with or re-assigned to other channels
For more details: [Why are my metrics different in Northbeam than in-platform reporting?](/docs/what-is-northbeam#why-do-my-in-platform-metrics-look-different-from-northbeam)
### 5. I think there's an issue with tracking. Please help!
Please reference our [Troubleshooting Northbeam Data](/docs/troubleshooting-tracking-issues).
* **Connection**: Open [Connections](https://dashboard.northbeam.io/settings/connections) and check for any errors on the Impact connection.
* **UTMs**: Ensure all Impact click URLs include the Northbeam `nbt` parameter listed in [Step 2](/docs/channels/impact/overview#add-northbeam-parameters-to-your-ads)
* **Northbeam Pixel**: Confirm the Northbeam pixel is firing on your landing page
* **Purchase Pixel**: Confirm the Purchase pixel is firing on your checkout page
# Impact Setup
Source: https://docs.northbeam.io/docs/channels/impact/overview
Connect Impact with API credentials and add the Northbeam parameter so spend and revenue line up.
When you're done, Northbeam shows your Impact spend, visits, and attributed revenue on the same programs, partners, and ads.
**Before you start**, make sure you have:
* An Impact user with the **Account Administrator** or **Implementation Specialist** role, so you can create API credentials
* Access to Impact **Settings** to edit the program tracking template
Create an Impact API token and paste it into Northbeam.
Add `nbt` once to your program tracking template.
Check that parameters and spend are reaching Northbeam.
Northbeam connects with Impact's **Legacy API Token**. You need your **Account SID** and **Auth Token**.
Only users with the **Account Administrator** or **Implementation Specialist** role in Impact can see API credentials. If you don't see the API section in Settings, ask your Impact admin to give you one of these roles or to get the credentials for you.
**Create the token in Impact**
1. In Impact, go to **\[User profile] → Settings → Technical → API**.
2. Click **Create Access Token**. See [Impact's guide](https://help.impact.com/brand/what-would-you-like-to-learn-about/account-administration/account-settings/api-tokens/create-an-api-access-token-as-a-brand) for details.
3. Complete the **Setup** and **Contact Information** steps.
4. On the **API Scopes** step, select these scopes (all GET):
* `/Advertisers//Campaigns`
* `/Advertisers//Actions`
* `/Advertisers//Ads`
* `/Advertisers//MediaPartners`
* `/Advertisers//ReportExport/{ReportId_or_Handle}`
* `/Advertisers//Reports`
* `/Advertisers//Reports/{ReportId}`
5. Click **Create**.
**Connect in Northbeam**
1. Open [Connections](https://dashboard.northbeam.io/settings/connections) and select **Impact**. If you're still in onboarding, go to **Integrations > Impact** instead.
2. Paste your **Account SID** and **Auth Token**, then click **Connect**.
If you see *"An error occurred: Invalid credentials,"* check both values and try again.
**If you skip this step:** campaign, partner, and ad names are missing, along with spend metrics.
Add this parameter to the click URLs for all new and existing Impact ads:
| Parameter | Value |
| :- | :- |
| `nbt` | `nb:impact::{ircid}:{irpid}:{iradid}` |
1. In Impact, go to **\[User profile] → Settings → Gateway**.
2. Under **Program Tracking Template**, add a new parameter row with **Name** `nbt` and **Value** `nb:impact::{ircid}:{irpid}:{iradid}`.
3. Click **Save**.
**If you skip this step:** Northbeam can't tie visits and orders to your Impact ads, so spend and revenue show up on separate lines.
* **Parameters captured:** follow [Checking UTM tracking](/docs/checking-utm-tracking) to confirm the Northbeam parameters reach your landing pages.
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## How Impact data maps to Northbeam
Impact data follows Impact's own hierarchy: programs (campaigns) contain partners, and partners use individual ads.
| Impact level | Northbeam level |
| :- | :- |
| Program (Campaign) | Campaign Level |
| Partner | Adset Level |
| Ad | Ad Level |
## Remove Impact custom spend (optional)
Once connected, Northbeam pulls up to **3 years of historical spend** from Impact. If you already send Impact spend through a Spend Sheet or the Spend API, remove the overlap so it isn't reported twice.
For example, if you connect on `5/10/26`, Northbeam backfills Impact spend to `5/10/23`. If you have Impact spend older than that window and want to keep it, leave those older records in place.
**From a Spend Sheet**
1. Go to [Settings > Data Spreadsheets](https://dashboard.northbeam.io/settings/data-spreadsheets).
2. Find the sheet tied to Impact.
3. **Zero out** the Impact spend that overlaps the backfill period. For example, if you connect on `5/10/26`, zero out Impact spend from `5/10/23` onward.
**Don't delete rows, columns, or cells** from the Spend Sheet. Replace the overlapping Impact spend values with `0` instead. Custom spend sheets vary: some use formulas tied to raw data import tabs, others use manually entered spend.
**From the Spend API**
Delete the existing Impact spend records with the [Delete Spend endpoint](/reference/delete_spend).
If you're not sure which values to remove, [submit a support ticket](https://www.northbeam.io/submit-a-support-ticket) and we'll help.
## Need help?
Common Impact setup and reporting questions.
Start here if a check above fails.
# Keynes FAQ
Source: https://docs.northbeam.io/docs/channels/keynes/faq
## Keynes FAQ
### 1. Does the Keynes integration support attribution or revenue tracking?
No. Keynes is currently a spend-only integration.
Because Keynes is a CTV platform, the integration does not currently support:
* UTMs or NBT parameters
* Revenue attribution
* Conversion attribution
* Click-based attribution
The integration is designed to import Keynes spend and campaign reporting data into Northbeam.
### 2. Can I connect multiple Keynes accounts?
At this time, Northbeam supports connecting one Keynes account per dashboard.
If you manage multiple Keynes accounts, you can still track the others by:
* Connecting one account through the native Keynes integration
* Sending spend for additional accounts via a Spend Sheet or Spend API
Any non-connected Keynes accounts will work similarly to other non-integrated channels.
### 3. Why don't I see revenue or ROAS metrics tied to Keynes?
The Keynes integration currently imports spend data only.
Because there are no UTMs, click identifiers, or deterministic conversion signals passed from Keynes into Northbeam, revenue and conversion metrics cannot currently be attributed directly to Keynes campaigns.
### 4. Why does Keynes spend differ from The Trade Desk at the daily level?
Keynes spend may differ from Northbeam at the daily level due to timezone reporting differences.
Keynes reports spend in UTC, while the original source data, such as The Trade Desk, may report spend in the account’s timezone, such as America/Los\_Angeles. Since Northbeam receives daily-level data from Keynes, we cannot reliably convert that spend into the account’s local timezone at the hourly level.
As a result, individual daily totals may not match exactly. However, spend should generally reconcile closely at the monthly level.
### 5. I think there's an issue with my Keynes integration. Please help!
Please reference our [Troubleshooting Northbeam Data](/docs/troubleshooting-tracking-issues).
* **Connection**: Open [Connections](https://dashboard.northbeam.io/settings/connections) and check for any errors on the Keynes connection.
* **Credentials**: Double-check that your AWS Access Key ID and Secret Access Key were entered correctly
* **Data Sync Timing**: Spend data may take some time to appear after connecting, depending on Keynes data sync timing
# Keynes Setup
Source: https://docs.northbeam.io/docs/channels/keynes/overview
Connect Keynes with AWS credentials so Northbeam imports your Keynes spend and campaign reporting.
When you're done, Northbeam shows your Keynes spend and campaign-level reporting data. Keynes is a CTV platform, so this integration is **spend-only**: it doesn't support click attribution, UTMs, or revenue attribution.
**Before you start**, make sure you have these Keynes AWS credentials (ask your Keynes representative for them):
* **AWS Access Key ID**
* **AWS Secret Access Key**
Paste your Keynes AWS credentials into Northbeam.
Check that the connection is live and spend is arriving.
Northbeam connects to Keynes with AWS credentials from the Keynes team.
1. Ask your Keynes representative for your **AWS Access Key ID** and **AWS Secret Access Key**.
2. Open [Connections](https://dashboard.northbeam.io/settings/connections) and select **Keynes**. If you're still in onboarding, go to **Integrations > Keynes** instead.
3. Paste your **AWS Access Key ID** and **AWS Secret Access Key**, then click **Connect**.
Once the connection works, your Keynes accounts appear on the Connections page.
**Historical spend backfill:** once connected, Northbeam automatically backfills up to 3 years of historical Keynes spend.
**If you skip this step:** Keynes spend and campaign reporting data don't appear in Northbeam.
Keynes is spend-only, so there are no UTMs to check. Follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and spend is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## Need help?
Common Keynes setup and reporting questions.
Start here if a check above fails.
# Klaviyo FAQ
Source: https://docs.northbeam.io/docs/channels/klaviyo/faq
## Klaviyo FAQ
### 1. I can't find my Klaviyo data
Your Klaviyo data may be categorized in another platform group called "Other" or "Other Email". Learn how to recategorize them using [Breakdowns.](/docs/manage-breakdowns)
### 2. Can I connect multiple ad accounts?
We currently do not support multiple Klaviyo accounts at this time, but as long as the extra account is utilizing UTM parameters, we'll track your campaigns and flows.
### 3. Why do I see a data discrepancy?
**Discrepancies in Revenue and Orders are expected.** The reason for this lies in the differences between Northbeam's attribution model and the corresponding platform's attribution model. Each attribution model has a unique method of allocating credit.
For example, Northbeam's Clicks-Only model divides credit across all touchpoints and tries to push credit to your upper funnel channels. Let's say your in-platform model uses Last Click, which gives credit to the last touchpoint in the journey. This is going to cause a discrepancy.
To take it one step further, let's say both Northbeam and in-platform are using Last Click. Northbeam is unique in that we recognize all touchpoints from every single channel. Whereas most platforms only recognize touchpoints from that same platform.
In addition, there's often a difference in the attribution window. By default, Northbeam leverages a 1-Day window, which is different than many other platforms' default.
To get the most apples to apples comparison, be sure to compare data using same Attribution Model and Attribution Window. But keep in mind, it will never be exact.
#### Attribution Models and Windows
**Klaviyo:**
* Attribution Model: Last Click
* Attribution Window: 5-day Opened or Click (default)
**Northbeam:**
* Attribution Model: Varies (default is Clicks-Only)
* Attribution Window: 1-Day (default, can extend to an infinite lifetime value)
#### For more details on discrepancies, review the articles below
[How to change your email and SMS attribution settings in Klaviyo](https://help.klaviyo.com/hc/en-us/articles/11118357030555)
### 4. Suspect a Tracking Issue?
Please reference our [Troubleshooting Northbeam Data](/docs/troubleshooting-tracking-issues).
* **Connection**: Make sure your Ad Account is still connected. Open [Connections](https://dashboard.northbeam.io/settings/connections) and check for any errors. Connections could break for a variety of reasons, but most commonly, the User losing access to the Ad Account.
* **UTMs**: Ensure all your ads contain Northbeam UTMs, as listed in the UTM step above.
* **Northbeam Pixel**: Ensure the Northbeam Pixel is firing on your landing page. Note that some site themes may not automatically transfer to landing pages on certain third-party apps, necessitating manual pixel placement.
* **Purchase Pixel:** Confirm that the Purchase Pixel is firing on your checkout page.
* **A-Record Setup:** Verify that the A-Record is correctly configured in your DNS Settings.
# Klaviyo Setup
Source: https://docs.northbeam.io/docs/channels/klaviyo/overview
Connect Klaviyo with API keys and add Northbeam UTMs so sign-ups and revenue tie back to your campaigns and flows.
When you're done, Northbeam shows the visits, revenue, and orders from your Klaviyo campaigns and flows, plus email and SMS sign-ups from Klaviyo's forms.
**Before you start**, make sure you have:
* A Klaviyo login that can view and create API keys (**Settings → API Keys**)
* Access to edit your Klaviyo campaigns and flows
Paste your Klaviyo API keys into Northbeam.
Add `nb_klid` and UTMs to your campaigns and flows.
See which channels drive your sign-ups.
Check that parameters and data are arriving.
The connection imports all Klaviyo events tagged "new subscriber". They show up under the **Email Sign Ups** metric, along with **Cost per Email Sign Up** and **Email Sign Up Rate**.
**A. Find your Public API Key**
1. Log in to Klaviyo.
2. Go to **Settings → API Keys**.
3. Copy the **Public API Key**.
**B. Create a Private API Key**
1. In Klaviyo, go to **Settings → API Keys**.
2. Under **Private API Keys**, click **Create Private API Key**.
3. Name the key something like **Northbeam (Read-only)**.
4. Set permissions to **Read-only**.
5. Click **Create**.
**C. Enter the keys in Northbeam**
Open [Connections](https://dashboard.northbeam.io/settings/connections), select **Klaviyo**, and paste your **Public API Key** and **Private API Key**.
Klaviyo's own help pages: [Finding your Public API Key](https://help.klaviyo.com/hc/en-us/articles/115005062267) and [Creating a Private API Key](https://help.klaviyo.com/hc/en-us/articles/7423954176283).
**If you skip this step:** sign-up volume is missing, and Email Sign Ups, Cost per Email Sign Up, and Email Sign Up Rate stay empty.
Set these as account-wide UTMs in Klaviyo. Northbeam looks for `utm_source`, `utm_medium`, `utm_campaign`, and `nb_klid`.
| UTM key | Campaign value | Flow value |
| :- | :- | :- |
| `utm_source` | Klaviyo\* | Klaviyo\* |
| `utm_medium` | email\* | email\* |
| `utm_campaign` | Campaign Name\* | Flow Message Name\* |
| `nb_klid` | Klaviyo profile ID | Klaviyo profile ID |
\*These are *recommended* values. You can use your own, but they affect how Klaviyo shows up in your dashboard. The walkthrough video below explains how.
The only required value is `nb_klid` = the Klaviyo profile ID, for both campaigns and flows.
For more detail on the Sales page, also add:
* `utm_term`: shows at the **Ad set** level
* `utm_content`: shows at the **Ad** level
**If you skip this step:** revenue isn't attributed to your Klaviyo campaigns or flows.
The connection counts your sign-ups, but it can't tell which channel drove them. To see that (for example, "Facebook Ads drove X email sign-ups"), set up a [Custom Goal](/docs/setting-up-custom-goals) that fires when a visitor submits your sign-up form.
Use your custom goal to see which channels drive sign-ups. **Email Sign Ups** shows your total sign-ups from Klaviyo.
**If you skip this step:** sign-ups show as Unattributed.
For a full check:
* **Parameters captured:** follow [Checking UTM tracking](/docs/checking-utm-tracking) to confirm the Northbeam parameters reach your landing pages.
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## Add Klaviyo spend (optional)
The Klaviyo connection doesn't pull spend or cost data. To get cost-based metrics like ROAS and CAC for Klaviyo, upload your costs with a [Custom Spendsheet](/docs/tracking-for-other-platforms#step-2-upload-costs-via-custom-spend).
Custom spend lands under a platform called **Other**. Use the [Breakdowns Manager](/docs/manage-breakdowns) to move it into **Klaviyo**.
**If you skip this:** no costs are tied to Klaviyo.
## Need help?
Common Klaviyo setup and reporting questions.
Start here if a check above fails.
# LiveIntent FAQ
Source: https://docs.northbeam.io/docs/channels/liveintent/faq
## LiveIntent FAQ
### 1. Why is there no LiveIntent adset-level reporting?
LiveIntent line items ("adsets") are primarily used as an internal optimization layer rather than a standard customer-facing reporting level. Accordingly, Northbeam supports LiveIntent attribution at the Campaign and Ad levels.
A placeholder appears at the Adset level to preserve Northbeam’s reporting hierarchy, but performance should be evaluated using the Campaign and Ad views.
### 2. Do I need to add the tracking parameters to every creative?
Yes.
LiveIntent click URLs are configured at the creative level. Every existing and newly created creative must include the Northbeam tracking parameters.
Northbeam does not automatically add or update these URLs through the LiveIntent API.
### 3. Can I use other UTM parameters alongside Northbeam's parameters?
Yes.
The `nbt` and `decisionid` parameters can be used alongside standard parameters such as:
* `utm_source`
* `utm_medium`
* `utm_campaign`
* Other analytics or tracking parameters
Make sure each parameter is separated using `&`.
### 4. Why do my Northbeam results differ from LiveIntent?
Differences are expected because LiveIntent and Northbeam use different attribution methodologies.
LiveIntent reports conversions based on the attribution settings configured for the advertiser and may credit both post-click and post-view conversions. Northbeam evaluates LiveIntent alongside the customer’s other marketing touchpoints, which may result in fewer conversions being attributed to LiveIntent.
LiveIntent attribution settings may vary by advertiser. Contact your LiveIntent account team to confirm the windows and post-view credit settings applied to your account.
### 5. Why do I see spend but no attributed revenue?
The LiveIntent connection and Northbeam click tracking serve different purposes.
The connection imports platform reporting such as spend, impressions, and clicks. The Northbeam parameters connect LiveIntent clicks to visits and conversions.
If spend appears without attributed revenue:
* Confirm every creative contains both `nbt` and `decisionid`.
* Confirm the macros were not URL-encoded.
* Confirm the Northbeam pixel fires on the landing page.
* Confirm the URL parameters are not removed by a redirect.
* Confirm purchase tracking is working.
### 6. Why is hourly LiveIntent data different from the LiveIntent dashboard?
LiveIntent does not provide hourly reporting through the API used by Northbeam.
LiveIntent reporting is imported daily, and any hourly breakdown displayed in Northbeam is derived downstream. Because of this, hourly bucketing may not match the LiveIntent interface exactly.
### 7. How long does LiveIntent data take to populate?
Initial LiveIntent reporting may take several hours to appear after the account is connected.
LiveIntent data may continue updating for up to 48 hours. Northbeam waits three days before considering the reporting stable.
### 8. I think there's an issue with tracking. What should I check?
* **Connection:** Open [Connections](https://dashboard.northbeam.io/settings/connections) and check the LiveIntent connection for errors.
* **Advertiser:** Confirm the correct LiveIntent advertiser was selected.
* **Click URLs:** Confirm all creative URLs contain `nbt` and `decisionid`.
* **Macros:** Confirm `${CAMPAIGN_ID}`, `${CREATIVE_ID}`, and `${DECISION_ID}` were not URL-encoded.
* **Redirects:** Confirm redirects preserve the URL parameters.
* **Northbeam Pixel:** Confirm the Northbeam pixel fires on the landing page.
* **Purchase Tracking:** Confirm Northbeam receives purchase events from the checkout.
If the issue continues, please [submit a support ticket](https://www.northbeam.io/submit-a-support-ticket).
# LiveIntent Setup
Source: https://docs.northbeam.io/docs/channels/liveintent/overview
Connect LiveIntent with your login and add Northbeam parameters to every creative so spend and revenue line up.
When you're done, Northbeam shows your LiveIntent spend, impressions, clicks, visits, and attributed revenue on the same campaigns and creatives.
Attribution for LiveIntent is click-based today. Deterministic impression and view-through attribution is planned for a future release.
**Before you start**, make sure you have:
* A LiveIntent username and password with access to the advertiser account you want to connect
* Access to edit the click URLs on your LiveIntent creatives
Sign in to LiveIntent from Northbeam and pick your advertiser.
Add `nbt` and `decisionid` to every creative's click URL.
Check that parameters and spend are reaching Northbeam.
Northbeam connects with your LiveIntent **username** and **password**. It uses them to sign in to LiveIntent and get an access token. Use a login that has access to the advertiser account you want to connect.
1. Open [Connections](https://dashboard.northbeam.io/settings/connections) and select **LiveIntent**. If you're still in onboarding, go to **Integrations > LiveIntent** instead.
2. Enter your LiveIntent username and password.
3. Once sign-in succeeds, select the right LiveIntent advertiser.
4. Click **Save**.
**If you skip this step:** LiveIntent spend, impressions, clicks, and campaign and creative names won't appear in Northbeam.
Add the Northbeam parameters to the click URL of every LiveIntent creative, existing and new. Northbeam doesn't add or update these URLs through the LiveIntent API.
Append this string to each click URL:
```
nbt=nb%3Aliveintent%3A%3A${CAMPAIGN_ID}%3A%3A${CREATIVE_ID}&decisionid=${DECISION_ID}
```
Use `?` if the click URL doesn't have any parameters yet:
```
https://example.com?nbt=nb%3Aliveintent%3A%3A${CAMPAIGN_ID}%3A%3A${CREATIVE_ID}&decisionid=${DECISION_ID}
```
Use `&` if it already has parameters:
```
https://example.com?utm_source=liveintent&nbt=nb%3Aliveintent%3A%3A${CAMPAIGN_ID}%3A%3A${CREATIVE_ID}&decisionid=${DECISION_ID}
```
For more on click URLs, see Zeta Global's [Click-URL Macros and Accepted Characters](https://knowledgebase.zetaglobal.com/liveintent/click-url-macros-and-accepted-characters) docs.
**If you skip this step:** spend and platform metrics may still appear, but Northbeam may not be able to attribute visits and conversions to your LiveIntent campaigns and creatives.
LiveIntent reporting can take several hours to appear after you connect, and may keep updating for up to 48 hours.
For a full check:
* **Parameters captured:** follow [Checking UTM tracking](/docs/checking-utm-tracking) to confirm the Northbeam parameters reach your landing pages.
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## How LiveIntent data maps to Northbeam
| LiveIntent level | Northbeam level |
| :- | :- |
| Campaign | Campaign Level |
| \[Placeholder Value] | Adset Level |
| Creative | Ad Level |
LiveIntent performance is reported at the Campaign and Ad levels. The Adset level shows a placeholder to keep Northbeam's reporting hierarchy.
## Need help?
Common LiveIntent setup and reporting questions.
Start here if a check above fails.
# Meta Ads FAQ
Source: https://docs.northbeam.io/docs/channels/meta/faq
## Meta Ads FAQ
### 1. How do I connect an extra account or remove an account?
Follow the walkthrough below:
### 2. Will my Meta Ads be reset to the learning phase?
Editing URL parameters on an active Meta Ad may affect its delivery or require Meta to process the change.
**Our recommendation:**
* Before changing existing ads, check whether they already use a supported Triple Whale, Hyros, Rockerbox, or Wicked Reports setup.
* If you need to update your ads, consider making the changes together so your tracking stays consistent.
* If you want to reduce disruption, make the change during a lower-traffic period or as part of your next creative refresh.
* Ads without supported tracking parameters may not receive full visit and conversion attribution in Northbeam.
### 3. Can Northbeam ingest UTMs from other tracking platforms?
Yes.
Northbeam supports specific Meta tracking parameter structures from:
* Triple Whale
* Hyros
* Rockerbox
* Wicked Reports
If your ads already use a supported structure, you may not need to replace those parameters with Northbeam's UTM Parameters (`nbt` and `nb_placement`).
The parameter names and values must match the supported formats exactly.
See [Using Supported Parameters From Another Attribution Platform](/docs/channels/meta/overview#using-supported-parameters-from-another-attribution-platform) for the supported formats.
### 4. Can you track conversions from Meta Shops?
#### For Shopify
Yes. Northbeam can identify completed Meta Shop orders using Shopify order data.
Make sure your store is connected to **Facebook and Instagram by Meta** in Shopify.
No additional Northbeam order tagging is required for the standard Shopify setup.
#### For All Other Platforms
Northbeam needs a way to identify which orders came from Meta Shops.
**Step 1:** Add a unique Order Tag using the `order_tags` field in the [Orders API](/reference/post_orders), then send the applicable orders to Northbeam.
**Step 2:** [Notify our team](https://www.northbeam.io/submit-a-support-ticket) and provide the name of the tag used for Meta Shop orders.
**Step 3:** Our team will confirm when the setup is complete.
### 5. How can I see Meta Shops credit?
Meta Shop conversion credit is included in **Attributed Revenue** and **Transactions** based on the Northbeam attribution model you are viewing.
This includes models such as **Clicks Only** and **Clicks + Modeled Views**.
**Note:**
The Northbeam Pixel does not fire inside Meta Shops.
Because of this, Northbeam does not record a standard website Visit for an order completed entirely inside Meta Shops.
Visit-based metrics such as CPC can therefore appear inflated for Campaigns, Ad Sets, or Ads that send traffic to Meta Shops.
### 6. Why do I see a data discrepancy?
Differences between Northbeam and Meta are expected.
The two platforms can use different:
* Attribution models
* Attribution windows
* Conversion definitions
* Available touchpoints
Northbeam can evaluate touchpoints across multiple marketing channels. Meta mainly evaluates touchpoints that Meta can observe.
For the closest comparison, make sure you compare:
1. The same date range
2. The same attribution window
3. The most comparable attribution model
4. The same conversion definition
Even with these settings aligned, the totals may not match exactly.
#### Attribution Models and Windows
**Meta:**
Common Meta reporting windows include:
* 1-Day Click
* 1-Day View
* 7-Day Click
* 7-Day Click + 1-Day View
The attribution setting can vary by Ad Set.
[Source: Meta Attribution Settings](https://www.facebook.com/business/help/460276478298895?id=561906377587030)
**Northbeam:**
Northbeam offers multiple attribution models and configurable attribution windows.
The model and window you select determine how Northbeam assigns conversion credit across eligible touchpoints.
#### For more details on discrepancies, review the articles below
[Why are my metrics different in Northbeam than in-platform reporting?](/docs/what-is-northbeam#why-do-my-in-platform-metrics-look-different-from-northbeam)
### 7. Why doesn't Meta-reported Purchases in Northbeam match in-platform?
Northbeam imports Meta purchase conversion volume and value for specific attribution windows, including:
* 1D Click
* 1D View
* 7D Click
* 7D Click + 1D View
Meta's standard **Purchases** metric can differ because each Ad Set can use its own attribution setting.
If the totals do not match, check these areas:
* **Mixed Attribution Settings** - Meta's total can include Ad Sets using different attribution settings. The combined total may not match any single attribution-window column.
* **Incremental Model** - Ad Sets using Meta's **Incremental** attribution model use a holdout-based methodology. Northbeam does not ingest this as one of the standard click or view attribution-window metrics.
* **Overlapping attribution windows** - Attribution windows are not additive. For example, 7-Day Click includes conversions that also qualify for 1-Day Click. Adding the columns together will double count conversions.
If any Ad Sets use Meta's **Incremental** attribution model, Northbeam may not match Meta's standard in-platform Purchase total.
#### What to do
* Compare Northbeam with Meta's **Purchases by attribution setting**, not only Meta's default Purchase total.
* Check whether your Ad Sets use different attribution settings.
* Check whether any Ad Sets use Meta's **Incremental** attribution model.
* Do not add overlapping attribution-window columns together.
### 8. I think there's an issue with tracking. Please help!
Start with [Troubleshooting Northbeam Data](/docs/troubleshooting-tracking-issues).
Then check the following:
* **Connection:** Open [Connections](https://dashboard.northbeam.io/settings/connections) and confirm that your Meta Ad Account is still connected and does not show an error.
* **Tracking parameters:** Confirm that your Meta Ads use Northbeam's UTM Parameters (`nbt` and `nb_placement`) or one of the supported alternative structures in [Step 2](/docs/channels/meta/overview#add-northbeam-parameters-to-your-ads).
* **Off-domain traffic:** If an ad first lands on another root domain, confirm that you are using a Northbeam Redirect Link or preserving the original Northbeam UTM Parameters until the visitor reaches your main domain.
* **Northbeam Pixel:** Confirm that the Northbeam Pixel fires on the landing page. Some third-party landing-page tools or themes may require a separate pixel installation.
* **Purchase tracking:** Confirm that your Purchase Pixel or server-side purchase tracking is working correctly.
* **A-Record Setup:** Confirm that the Northbeam A-Record is configured correctly in your DNS settings.
If the issue continues, [contact Northbeam Support](https://www.northbeam.io/submit-a-support-ticket).
# Meta Ads Setup
Source: https://docs.northbeam.io/docs/channels/meta/overview
Connect your Meta ad account and add Northbeam parameters so spend and revenue line up.
When you're done, Northbeam shows your Meta spend, impressions, visits, and attributed revenue on the same campaigns, ad sets, and ads.
**Before you start**, make sure you have:
* A Meta login with **admin access** to every ad account you plan to connect, with `ads_read` and `ads_management` permissions
* Access to **Meta Ads Manager** to edit your ads
Sync spend, impressions, and campaign structure from Meta.
Add `nbt` and `nb_placement` so visits and orders tie back to your ads.
Test a live ad to check the parameters and the Pixel.
1. Open [Connections](https://dashboard.northbeam.io/settings/connections). If you're still in onboarding, go to **Integrations** instead.
2. Find **Meta Ads** and click **Connect**.
3. Sign in with a Meta user that has admin access to every ad account you want to connect.
The connection pulls your current and historical campaigns, ad sets, and ads from the Meta Ads API, along with spend, impressions, Meta-reported conversions, and creative metrics. Impressions also power the **Clicks + Modeled Views** attribution model.
The connecting user needs `ads_read` and `ads_management` permissions. To check them, go to **Meta Business Manager → App Dashboard → App Review → Permissions and Features**. See [Meta's permissions guide](https://developers.facebook.com/docs/marketing-api/get-started/authorization/#permissions-and-features) for details.
**If you skip this step:** campaign, ad set, and ad details may be missing, along with spend, impressions, and Meta-reported metrics.
Most advertisers add the two Northbeam parameters below. Two cases are different:
* **You already use Triple Whale, Hyros, Rockerbox, or Wicked Reports parameters.** You may not need to add anything. See [supported parameters from other platforms](#using-supported-parameters-from-another-attribution-platform).
* **Your ad lands on a different domain first**, like an advertorial. See [off-domain pages](#sending-meta-traffic-to-an-off-domain-page).
### Northbeam UTM Parameters
In **Meta Ads Manager**, add these two parameters to every new and existing ad:
| Parameter | Value |
| :- | :- |
| `nbt` | `nb:fb:{{site_source_name}}:{{campaign.id}}:{{adset.id}}:{{ad.id}}` |
| `nb_placement` | `{{placement}}` |
1. Open the ad and find the **URL parameters** section.
2. Click **Build a URL parameter**, then **Add parameter** twice.
3. Enter `nbt` and `nb_placement` exactly as shown above, then click **Apply**.
4. Check the **Parameter preview** before you publish.
The **Parameter preview** should show `nbt=nb%3Afb%3A{{site_source_name}}%3A{{campaign.id}}%3A{{adset.id}}%3A{{ad.id}}&nb_placement={{placement}}`. Meta turns `:` into `%3A` on its own. **Don't type `%3A` yourself**, or it gets encoded twice (`%253A`) and tracking breaks.
These work alongside your usual `utm_source`, `utm_medium`, and `utm_campaign` values. To have Northbeam add the parameters to new Meta ads automatically, [ask Support](https://www.northbeam.io/submit-a-support-ticket) to turn on UTM auto-appending.
### Using Supported Parameters From Another Attribution Platform
If your ads already use one of these structures, you don't need to add `nbt` and `nb_placement`. Names and values must match **exactly**, including capitalization. Other parameters from these platforms aren't supported.
Platform
Supported Parameters
**Triple Whale**
Requires **both:** (1) a supported source parameter and (2) a supported Ad ID parameter.
**Source parameter:**
* `tw_source={{site_source_name}}`
* `tw_source=facebook`
* `utm_source=facebook`
* `utm_source={{site_source_name}}`
**Ad ID parameter:**
* `tw_adid={{ad.id}}`
* `fbadid={{ad.id}}`
Example:
`tw_source=facebook&tw_adid={{ad.id}}`
If yours don't match, use the [Northbeam UTM Parameters](#northbeam-utm-parameters).
### Sending Meta Traffic to an Off-Domain Page
If your ad sends people to a different root domain before your site (for example, `Meta Ad → advertorial.com → yourstore.com`), Northbeam needs the original Meta tracking when the visitor reaches your site. You have two options:
* **Option 1: Northbeam Redirect Link (recommended).** The ad points to a redirect on your own domain, which sends the visitor on to the off-domain page. Northbeam records the visit before they leave.
* **Option 2: Preserve the Northbeam UTM Parameters.** If you control the off-domain page, pass the original Northbeam parameters along on the link back to your site. `utm_source=facebook` on its own isn't enough.
See [Tracking Ads using Off-Domain Sites](/docs/tracking-for-off-domain-sites) for full setup.
**If you skip this step:** Northbeam can't tie visits and orders to your Meta ads, so spend and revenue show up on separate lines.
* **Parameters and Pixel on a live ad:** follow [Test a live ad](#test-a-live-ad) below.
* **Parameters captured:** follow [Checking UTM tracking](/docs/checking-utm-tracking).
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections).
### Test a live ad
A **Live Preview Link** from Meta Ads Manager tests the parameters and the Northbeam Pixel in one go. If your ad uses an off-domain page, test the full journey through to your site.
1. **Get the link.** In Meta Ads Manager, open the ad, click **Preview**, then **Share → Share a link**, and copy it.
2. **Open the ad like a customer.** Paste the link into your browser, find the ad in your feed (scroll if it isn't at the top), and click through to your site.
3. **Check the parameters.** Accept any cookie banner, open **Developer Tools → Network**, and refresh. Open the first Northbeam request and look in the **Payload** for an `nbt` value like `nb:fb:fb:XXXXXXXXX:XXXXXXXXXX:XXXXXXXXXXX`.
4. **Check the Pixel.** In the same tab, search for `nb-collector` or `tp2` and confirm one request's **Payload** contains `pv`.
If both show up, Northbeam records the visit and can attribute orders to the right Meta campaign, ad set, and ad.
**Chrome / Edge / Brave / Opera:** right-click the page and select **Inspect**, or press `Cmd+Option+I` on Mac / `Ctrl+Shift+I` on Windows. Then open the **Network** tab.
**Firefox:** right-click the page and select **Inspect**, or press `Cmd+Option+E` on Mac / `Ctrl+Shift+E` on Windows. Then open the **Network** tab.
**Safari:** go to **Safari → Settings → Advanced** and enable **Show Develop menu**. Then go to **Develop → Show Web Inspector** and open the **Network** tab.
If any check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
**Sell on Meta Shops?** Shopify stores should connect [Facebook and Instagram by Meta](https://help.shopify.com/en/manual/online-sales-channels/facebook-instagram-by-meta/setup). Custom stores should tag Meta Shops orders with a unique `order_tag` through the [Server API](https://northbeam-orders-api.readme.io/reference/post_orders), then [tell our team](https://www.northbeam.io/submit-a-support-ticket) the tag name. See [Meta Shops and TikTok Shops](/docs/tracking-for-shops).
## Optional Meta features
These are separate from the setup above and need their own configuration.
An attribution model that credits Meta ads people saw but didn't click, using verified view data.
Sends Northbeam attribution back to Meta so it can optimize toward it. Runs alongside your Pixel and Conversions API.
## Need help?
Common Meta setup and reporting questions.
Start here if a check above fails.
# Microsoft Ads FAQ
Source: https://docs.northbeam.io/docs/channels/microsoft/faq
## Microsoft Ads FAQ
### 1. Do I need specific UTM parameters?
Nope! Once your account is connected, our pixel tracks all the data without needing to manually insert UTM parameters.
### 2. How far back does Microsoft Ads data backfill?
When you connect your Microsoft Ads account, Northbeam backfills spend and performance data for up to 180 days prior to the connection date.
Data earlier than 180 days before connection is not pulled automatically. This limitation exists because Microsoft only makes hourly spend data available for the last 180 days, and Northbeam’s Microsoft integration is built to process data at an hourly granularity.
If you need more than 180 days of historical Microsoft Ads spend, we recommend ingesting that data via a [Spend Sheet or Spend API](/docs/add-spend).
### 3. How do I connect an extra account or remove an account?
Reference our step-by-step guide below:
### 4. Why do I see a data discrepancy?
**Discrepancies in Revenue and Orders are expected.** The reason for this lies in the differences between Northbeam's attribution model and the corresponding platform's attribution model. Each attribution model has a unique method of allocating credit.
For example, Northbeam's Clicks-Only model divides credit across all touchpoints and tries to push credit to your upper funnel channels. Let's say your in-platform model uses Last Click, which gives credit to the last touchpoint in the journey. This is going to cause a discrepancy.
To take it one step further, let's say both Northbeam and in-platform are using Last Click. Northbeam is unique in that we recognize all touchpoints from every single channel. Whereas most platforms only recognize touchpoints from that same platform.
In addition, there's often a difference in the attribution window. By default, Northbeam leverages a 1-Day window, which is different than many other platforms' default.
To get the most apples to apples comparison, be sure to compare data using same Attribution Model and Attribution Window. But keep in mind, it will never be exact.
#### Attribution Models and Windows
**Microsoft:**
* Attribution Model: Last Click
* Attribution Window: 30-Day Click
* [Source: Microsoft Attribution Settings](https://help.ads.microsoft.com/apex/index/3/en/56710)
**Northbeam:**
* Attribution Model: Varies (default is Clicks-Only)
* Attribution Window: 1-Day (default, can extend to an infinite lifetime value)
### 5. Suspect a Tracking Issue?
Please reference our [Troubleshooting Northbeam Data](/docs/troubleshooting-tracking-issues)
##### Check for Manually Applied Northbeam URL Parameters
Northbeam automatically injects the required tracking parameters for Microsoft Ads, so manually adding Northbeam UTMs or URL parameters is uncommon and may cause issues.
If tracking is not working correctly, check the **Final URL Suffix** field at the account, campaign, or ad level for any manually added Northbeam-specific parameters.
Manually added parameters may override the ones Northbeam automatically injects, since Microsoft Ads prioritizes the first matching parameter it sees. If those values are outdated or use invalid Microsoft macros, this can cause issues such as missing visits, blank Ad IDs, or incorrect campaign mapping.
If you find manually added Northbeam parameters, remove them and allow the automatically injected parameters to take over instead.
#### Still having trouble?
* **Connection**: Make sure your Ad Account is still connected. Open [Connections](https://dashboard.northbeam.io/settings/connections) and check for any errors. Connections could break for a variety of reasons, but most commonly, the User losing access to the Ad Account.
* **UTMs**: Ensure all your ads contain Northbeam UTMs, as listed in the UTM step above.
* **Northbeam Pixel**: Ensure the Northbeam Pixel is firing on your landing page. Note that some site themes may not automatically transfer to landing pages on certain third-party apps, necessitating manual pixel placement.
* **Purchase Pixel:** Confirm that the Purchase Pixel is firing on your checkout page.
* **A-Record Setup:** Verify that the A-Record is correctly configured in your DNS Settings.
- If the Microsoft Advertising application ID (d42ffc93-c136-491d-b4fd-6f18168c68fd) doesn't exist in your Azure tenant: This can happen if you are trying to authenticate to a tool provider and never created your own Azure App registration and added **msads.manage** to it. To fix this, you will need to contact the Active Directory administrator to enable the service via a [Microsoft Graph API call](https://learn.microsoft.com/en-us/advertising/guides/authentication-oauth-register?view=bingads-13#register-an-application-with-entra-id).
# Microsoft Ads Setup
Source: https://docs.northbeam.io/docs/channels/microsoft/overview
Set up your Microsoft account and connect Microsoft Ads so spend and revenue show up in Northbeam.
When you're done, Northbeam shows your Microsoft (Bing) Ads spend, impressions, visits, and attributed revenue on the same campaigns, ad groups, and ads.
**Before you start**, make sure you have:
* Help from your **Microsoft Azure Active Directory administrator**
* A **Global Administrator** login for the [Microsoft Entra admin center](https://entra.microsoft.com)
* A **Business** Microsoft account (not a Personal account) for Microsoft Ads
Set up API access, user consent, and a business account.
Sync spend, impressions, and campaign structure from Microsoft Ads.
Check that the connection is working.
**Requirement 1: Verify the Microsoft Advertising API Service for your Azure tenant.** Ask your Microsoft Azure Active Directory administrator to make sure:
* At least one admin user from your Azure AAD tenant is added and enabled for work accounts in the Microsoft Advertising web application.
* The **Microsoft Advertising API Service** (App ID: `d42ffc93-c136-491d-b4fd-6f18168c68fd`) is active with **msads.manage** and **ads.manage** permissions.
**Requirement 2: Enable user consent in Microsoft Entra.**
1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as a Global Administrator.
2. Go to **Identity → Applications → Enterprise Applications → Consent and permissions → User consent settings**.
3. Choose either **Allow user consent for apps from verified publishers, for selected permissions** or **Let Microsoft manage your consent**.
**Requirement 3: Confirm you have a Business Microsoft account.** Your account must be a **Business** account, not a Personal account.
1. In the Microsoft Ads portal, go to **Settings > My Settings > Signed In With**.
2. If it says Personal, follow the link there to switch to Business.
**If you skip this step:** the connection can fail with Error 105 or Error 106 (see the next step).
1. Open [Connections](https://dashboard.northbeam.io/settings/connections). If you're still in onboarding, go to **Integrations** instead.
2. Find **Microsoft Ads** and click **Connect**.
3. Sign in with the **Business** Microsoft account from step 1.
The connection pulls your current and historical campaigns, ad groups, and ads from the Microsoft Ads API, along with spend and impressions. Your dashboard then shows attributed revenue, transactions, and visits for them. Impressions also power the **Clicks + Modeled Views** attribution model.
**Seeing an error when you connect?**
* **Error 105** is a permissions error. Third-party access needs to be enabled on your Microsoft account. See Requirement 1 above.
* **Error 106** is an account type error. Connect with a Business Microsoft account, not a Personal one. See Requirement 3 above.
**Historical spend backfill:** Northbeam backfills spend and performance data for up to **180 days** before the date you connect your Microsoft Ads account. Older data isn't pulled automatically. If you need it, add it with a [Spend Sheet or Spend API](/docs/add-spend).
**No UTM parameters needed.** Once your account is connected, Northbeam adds the tracking parameters to your Microsoft ads automatically. Don't add Northbeam parameters by hand. They can override the automatic ones and cause tracking issues. See the [Microsoft Ads FAQ](/docs/channels/microsoft/faq#1-do-i-need-specific-utm-parameters).
**If you skip this step:** all Microsoft Ads performance is missing from Northbeam.
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## Need help?
UTMs, backfill, extra accounts, and data discrepancies.
Start here if a check above fails.
# MNTN FAQ
Source: https://docs.northbeam.io/docs/channels/mntn/faq
## FAQs
### **1. Why am I not seeing MNTN data after enabling CDV?**
If you’ve connected your account and turned on CDV but no data is visible:
* Ensure order IDs are aligned between MNTN and Northbeam.
* Confirm CDV consent was enabled in Northbeam (Account Settings → Attribution Models).
* Allow up to **48 hours** post-consent for impression data to appear.
* Verify that the advertiser is actively running campaigns in MNTN.
* Check “Last retrieved” and “Last processed” timestamps in the dashboard.
If all checks pass and data is still missing, contact Support for further investigation.
### 2. Why do MNTN conversions and revenue differ between Northbeam and GA4?
Northbeam and GA4 attribute MNTN CTV performance in fundamentally different ways, so conversion and revenue numbers will not match — and this is expected.
#### How GA4 attributes MNTN conversions
* MNTN’s Verified Visits create direct sessions in GA4 when a user visits your site after viewing a CTV ad.
* GA4 then attributes conversions based on its session-level model (such as DDA or last non-direct click).
* These conversions are not tied to UTMs, since CTV impressions do not pass them.
#### How Northbeam attributes MNTN conversions
* Northbeam uses deterministic impression matching under Clicks + Deterministic Views (C+DV).
* If a user converts after being exposed to a valid MNTN impression within the attribution window, Northbeam attributes that conversion to MNTN.
* This does not rely on sessions or UTMs.
#### Why they differ
* GA4 attributes conversions to direct sessions triggered after a CTV impression.
* Northbeam attributes conversions to deterministically matched impressions, independent of session source.
* Because the attribution logic is different, conversion and revenue totals will not align between the two platforms.
### **3. How long does the initial sync take?**
The initial sync from MNTN can take up to **72 hours**, depending on historical data volume.\
After that, updates occur **3× per day**.
# MNTN Setup
Source: https://docs.northbeam.io/docs/channels/mntn/overview
Connect MNTN with an API key and turn on Clicks + Deterministic Views so Northbeam can credit your MNTN impressions.
When you're done, Northbeam shows your MNTN spend and uses MNTN impressions to give view credit under **Clicks + Deterministic Views (C+DV)**.
**Before you start**, make sure you have:
* A **MNTN account** login with access to **My Account → API** and **My Account → Integrations**
* Access to [Connections](https://dashboard.northbeam.io/settings/connections) and **Model Settings** in Northbeam
* The same **order ID** format sent to MNTN and Northbeam (for example, Shopify order numbers)
Add your MNTN API key in Northbeam, then turn on Northbeam in MNTN.
Select MNTN as a C+DV platform in Model Settings.
Check that order IDs match and data is arriving.
**Select your MNTN channels**
1. Open [Connections](https://dashboard.northbeam.io/settings/connections) and scroll down to **MNTN**.
2. Select the **MNTN channels** you advertise on.
CTV is fully supported under Clicks + Deterministic Views (C+DV). Earlier docs said CTV attribution was limited. That's no longer true. The channel selector is informational only and doesn't affect your integration.
**Enter your API key**
1. Log in to your **MNTN account**.
2. Click the **menu icon** in the top-right corner and go to **My Account → API**.
3. Copy your **API Key**.
4. In Northbeam, open [Connections](https://dashboard.northbeam.io/settings/connections) and select **MNTN**.
5. Paste your **API key** and click **Connect**.
**Turn on the integration in MNTN**
After you connect your API key in Northbeam, finish setup from inside MNTN:
1. Sign in to your **MNTN account**.
2. Click your account name in the top-right corner and select **My Account**.
3. In the left menu, click **Integrations**.
4. Under **Analytics Integrations**, find **Northbeam** and click **Connect**.
You'll see a confirmation message, and data starts syncing automatically within 24–48 hours. For full instructions, see MNTN's [Integration Guide](https://help.mountain.com/en/articles/11644276-integrate-northbeam).
**Remove legacy tags.** If you set up legacy MNTN impression tags for Northbeam in the past, remove them after you turn on the new C+DV integration. Keeping them can cause duplicate or conflicting impression data.
**If you skip this step:** Northbeam doesn't get your MNTN spend or the impressions it needs for C+DV matching.
Once your MNTN connection is active in Northbeam:
1. Go to **Settings → Model Settings → Attribution Models**.
2. Select **Clicks + Deterministic Views (C+DV)**.
3. Under **Available Platforms**, check the box for **MNTN**.
4. Click **Save Changes**.
5. Allow up to 48 hours for MNTN impression data to show up in your dashboard.
**How MNTN data processes**
* After first setup, data can take up to **3 days** to fully backfill.
* Once live, **C+DV data processes 3× per day**.
* **Last retrieved** is when Northbeam last received data from MNTN.
* **Last processed** is when that data was last processed and visible in the dashboard.
**If you skip this step:** MNTN impression data doesn't show up in Northbeam.
**Check that order IDs match.** MNTN uses order IDs for deterministic matching.
1. In Northbeam, go to **Orders → Order ID** and note your order ID format (for example, Shopify order numbers).
2. In MNTN, make sure the **same order ID format** is being passed to Northbeam.
3. If they don't match, update your MNTN setup or [contact Support](https://www.northbeam.io/submit-a-support-ticket) to adjust the configuration.
Mismatched order IDs block deterministic matching, so C+DV data won't show up.
Then run the full check:
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## Supported attribution models
The MNTN integration supports these Northbeam attribution models:
* First Touch
* Last Touch
* Last Non-Direct Touch
* Clicks-Only
* Clicks + Deterministic Views (C+DV)
**Clicks + Modeled Views** isn't supported for MNTN.
## Need help?
Missing C+DV data, GA4 differences, and sync timing.
Start here if a check above fails.
# Neon Pixel FAQ
Source: https://docs.northbeam.io/docs/channels/neon-pixel/faq
## Neon Pixel FAQ
### 1. Does Neon Pixel support attribution and revenue tracking?
Yes. Neon Pixel supports deterministic view attribution through the **Clicks + Deterministic Views** model after the connection is active and impression setup has been finalized.
### 2. How long does Neon Pixel data take to appear?
Once the connection and impression setup are complete, allow approximately 48 hours for data to begin flowing.
### 3. Why can I see spend but not attributed revenue?
Check that:
* **Enable C+DV for Neon Pixel** is turned on in the connection card.
* **Clicks + Deterministic Views** is enabled in Model Settings.
* Neon Pixel is selected under the model's platform list.
* Your Neon Pixel representative has finalized impression data setup.
* At least 48 hours have passed since setup was completed.
Revenue and ROAS populate only when eligible impressions can be matched to orders.
### 4. What is Apex data sharing?
When enabled, Apex data sharing sends Northbeam performance signals to Neon Pixel. The setting is optional and can be managed from the Neon Pixel connection card.
### 5. Will switching to Neon Pixel delete historical data?
No. Historical data from the previous connection is not deleted. However, saved views and columns that reference the inactive platform may appear blank and should be updated.
### 6. Why do saved views and exports need to be reviewed?
Northbeam automatically updates built-in platform references, but it does not automatically rewrite user-created configurations. Review custom metrics, breakdowns, saved views, scheduled exports, and Marketing Mix Modeling mappings after switching.
### 7. What should I do if Neon Pixel data is missing?
* Confirm that the connection card is green and the correct account is linked.
* Confirm that the correct Neon Pixel channel was selected.
* Check that the API key is still valid.
* Confirm that Clicks + Deterministic Views is enabled in both the connection and Model Settings.
* Ask your Neon Pixel representative to confirm that impression setup is complete.
* Allow approximately 48 hours after setup before troubleshooting further.
### 8. Where do I get a Neon Pixel API key?
Contact your Neon Pixel representative for the API key and the channel information required for your account.
### 9. What should I do if the API key is lost or invalid?
Contact your Neon Pixel representative for a replacement key, then reconnect the account from **Settings > Connections > Neon Pixel**.
# Neon Pixel Setup
Source: https://docs.northbeam.io/docs/channels/neon-pixel/overview
Connect Neon Pixel with your API key and turn on Clicks + Deterministic Views for spend reporting and deterministic view attribution.
When you're done, Northbeam shows your Neon Pixel spend and platform data, and uses Neon Pixel impressions for deterministic view attribution in the **Clicks + Deterministic Views** model.
**Before you start**, make sure you have:
* A Neon Pixel API key
* The channel information from your Neon Pixel representative
* Contact details for your Neon Pixel representative
**Need an API key?** Contact your Neon Pixel representative. Keep the key secure. Don't add it to landing page URLs or share it outside the people responsible for this integration.
Paste your API key and pick your channel.
Ask your Neon Pixel rep to finish impression setup.
Turn on Clicks + Deterministic Views for Neon Pixel.
Check the connection and wait about 48 hours.
1. In Northbeam, go to [**Settings > Connections**](https://dashboard.northbeam.io/settings/connections).
2. Find **Neon Pixel** and click **Connect**.
3. Under **Neon Pixel Channels**, select the channel or channels your Neon Pixel representative gave you (for example, **Multi-touch**).
4. Paste your Neon Pixel API key into the **API Key** field.
5. Optional: turn on **Apex data sharing** if you want Northbeam to send performance signals to Neon Pixel.
6. Review the data sharing terms.
7. Turn on **Clicks + Deterministic Views** so Northbeam can receive impressions for this attribution model.
8. Click **Connect**.
**If you skip this step:** Neon Pixel data won't appear in Northbeam. If you leave Apex data sharing off, the account still connects, but Northbeam won't share Apex performance signals with Neon Pixel.
After the account connects, Northbeam shows a **Finalize Neon Pixel impression setup** message.
1. Click **Done** to close the message.
2. Contact your Neon Pixel representative and ask them to finalize your impression data setup.
**Required for view attribution.** Connecting the account doesn't complete impression setup. Your Neon Pixel representative must finalize it before deterministic impression data can flow to Northbeam.
**If you skip this step:** Neon Pixel impression data won't populate.
1. In Northbeam, go to [**Settings > Model Settings**](https://dashboard.northbeam.io/settings/model-settings).
2. Turn on **Clicks + Deterministic Views** under **Attribution Models Available**.
3. In the platform list below the model, select **Neon Pixel**.
4. Save your changes if prompted.
The model must be on both in Model Settings and for Neon Pixel.
**If you skip this step:** spend may appear, but deterministic view attribution won't be available.
Once the connection and impression setup are complete, allow about **48 hours** for data to start flowing.
Go back to [**Settings > Connections > Neon Pixel**](https://dashboard.northbeam.io/settings/connections) and confirm that:
* The connection card shows a green confirmation icon.
* The correct Neon Pixel ad account ID is linked.
* **Enable C+DV for Neon Pixel** is turned on.
* Apex data sharing matches your preferred setting.
Then check that:
* **Clicks + Deterministic Views** and **Neon Pixel** are both turned on in Model Settings.
* Your Neon Pixel representative has confirmed impression setup is complete.
* In Sales Attribution, with the **Clicks + Deterministic Views** model selected, Neon Pixel spend appears for the expected date range.
* Revenue and ROAS populate when eligible impressions are matched to orders.
For a full check, follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## After switching: items to review
Switching to Neon Pixel doesn't delete historical data from the previous connection. Northbeam updates built-in platform references automatically, but it doesn't rewrite configurations you created. Saved views and columns that point to the inactive platform may show up blank.
After switching, review your:
* Custom metrics
* Breakdowns
* Saved views
* Scheduled exports
* Marketing Mix Modeling mappings
## Need help?
Common Neon Pixel setup and reporting questions.
Start here if a check above fails.
# Pinterest Ads FAQ
Source: https://docs.northbeam.io/docs/channels/pinterest/faq
## Pinterest Ads FAQ
### 1. How do I connect an extra account or remove an account?
Reference our step-by-step guide below:
### 2. Why do I see a data discrepancy?
**Discrepancies in Revenue and Orders are expected.** The reason for this lies in the differences between Northbeam's attribution model and the corresponding platform's attribution model. Each attribution model has a unique method of allocating credit.
For example, Northbeam's Clicks-Only model divides credit across all touchpoints and tries to push credit to your upper funnel channels. Let's say your in-platform model uses Last Click, which gives credit to the last touchpoint in the journey. This is going to cause a discrepancy.
To take it one step further, let's say both Northbeam and in-platform are using Last Click. Northbeam is unique in that we recognize all touchpoints from every single channel. Whereas most platforms only recognize touchpoints from that same platform.
In addition, there's often a difference in the attribution window. By default, Northbeam leverages a 1-Day window, which is different than many other platforms' default.
To get the most apples to apples comparison, be sure to compare data using same Attribution Model and Attribution Window. But keep in mind, it will never be exact.
#### Attribution Models and Windows
**Pinterest:**
* Attribution Model: Last Click
* Attribution Window: 30-Day Click/30-Day Engagement/1-Day View
**Northbeam:**
* Attribution Model: Varies (default is Clicks-Only)
* Attribution Window: 1-Day Click (default, can extend to an infinite lifetime value)
Pinterest relies on limited third-party data, particularly post iOS14, resulting in a constrained 7-Day Click/1-Day View attribution window. This limitation often leads to inflated metrics due to the exclusive focus on their own marketing touchpoints.
Northbeam, on the other hand, leverages its proprietary pixel and first-party data to comprehensively analyze a customer's entire journey. Our flexibility allows for attribution windows ranging from 1-Day to an infinite lifetime, providing a more nuanced and accurate representation of customer paths.
### 3. Suspect a Tracking Issue?
Please reference our [Troubleshooting Northbeam Data](/docs/troubleshooting-tracking-issues).
* **Connection**: Make sure your Ad Account is still connected. Open [Connections](https://dashboard.northbeam.io/settings/connections) and check for any errors. Connections could break for a variety of reasons, but most commonly, the User losing access to the Ad Account.
* **UTMs**: Ensure all your ads contain Northbeam UTMs, as listed in the UTM step above.
* **Northbeam Pixel**: Ensure the Northbeam Pixel is firing on your landing page. Note that some site themes may not automatically transfer to landing pages on certain third-party apps, necessitating manual pixel placement.
* **Purchase Pixel:** Confirm that the Purchase Pixel is firing on your checkout page.
* **A-Record Setup:** Verify that the A-Record is correctly configured in your DNS Settings.
# Pinterest Ads Setup
Source: https://docs.northbeam.io/docs/channels/pinterest/overview
Connect your Pinterest ad account and add Northbeam parameters so spend and revenue line up.
When you're done, Northbeam shows your Pinterest spend, impressions, visits, and attributed revenue on the same campaigns, ad groups, and ads.
**Before you start**, make sure you have:
* A Pinterest login with **admin access** to the ad account
* Access to **Pinterest Business Manager** to change ad account settings
Sync spend, impressions, and campaign structure from Pinterest.
Add `nbt` and `nb_platform` once in your ad account settings.
Click a live ad and check the landing page URL.
1. Open [Connections](https://dashboard.northbeam.io/settings/connections). If you're still in onboarding, go to **Integrations** instead.
2. Find **Pinterest Ads** and click **Connect**.
3. Sign in with a Pinterest login that has **admin access** to the ad account.
The connection pulls your current and historical campaigns, ad groups, and ads from the Pinterest Ads API, along with spend, impressions, and Pinterest-reported conversion and creative metrics. Impressions also power the **Clicks + Modeled Views** attribution model.
**If you skip this step:** campaign, ad group, and ad names are missing, along with spend, impressions, and Pinterest-reported metrics.
Add these two custom parameters in your ad account settings. They apply to every campaign in the account.
| Parameter | Value |
| :- | :- |
| `nbt` | `nb:pinterest::{campaignid}:{adgroupid}:{adid}` |
| `nb_platform` | `pinterest` |
1. Log in to your **Pinterest Business account**.
2. Click the menu icon (top-left) → **Business Manager**.
3. Select **Ad Accounts** and choose your ad account.
4. Open the **Settings** tab → **Parameter Settings**.
5. Under **Custom Parameters**, add both parameters above.
Pinterest adds standard GA UTMs (`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`) by default. Northbeam doesn't need them, so you can keep or remove them. To have Northbeam add the parameters to new Pinterest ads automatically, [ask Support](https://www.northbeam.io/submit-a-support-ticket) to turn on UTM auto-appending.
**If you skip this step:** Northbeam can't tie visits and orders to your Pinterest ads, so spend and revenue show up on separate lines.
**Quick check:** click one of your live Pinterest ads and look at the landing page URL. `nbt` should show real numbers where `{campaignid}`, `{adgroupid}`, and `{adid}` are. If you see that placeholder text, check the parameters against the table above.
For a full check:
* **Parameters captured:** follow [Checking UTM tracking](/docs/checking-utm-tracking) to confirm the Northbeam parameters reach your landing pages.
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## Need help?
Common Pinterest setup and reporting questions.
Start here if a check above fails.
# Channel quickstart
Source: https://docs.northbeam.io/docs/channels/quickstart
Every channel follows the same three steps — pick yours to start
Every channel setup follows the same three steps:
Link the platform to Northbeam so spend and campaign structure sync.
Add Northbeam parameters to your ads so visits attribute back to them. View-based and spend-only channels, like most CTV, skip this step.
Verify UTMs are captured and the connection is syncing.
Some channels add an FAQ for platform-specific questions.
## Pick your channel
**Paid Social & Search**
[Meta](/docs/channels/meta/overview) · [Google + YouTube](/docs/channels/google/overview) · [TikTok](/docs/channels/tiktok/overview) · [Microsoft](/docs/channels/microsoft/overview) · [Pinterest](/docs/channels/pinterest/overview) · [Snapchat](/docs/channels/snapchat/overview) · [X](/docs/channels/x/overview) · [Reddit](/docs/channels/reddit/overview) · [OpenAI](/docs/tracking-for-openai-ads)
**CTV & Streaming**
[MNTN](/docs/channels/mntn/overview) · [Neon Pixel](/docs/channels/neon-pixel/overview) · [Tatari](/docs/channels/tatari/overview) · [Vibe.co](/docs/channels/vibe/overview) · [Paramount](/docs/tracking-for-paramount) · [Universal Ads](/docs/channels/universal/overview) · [Keynes](/docs/channels/keynes/overview) · [Bliss Point](/docs/tracking-for-bliss-point-by-tinuiti)
**Programmatic, Display & Apps**
[TradeDesk](/docs/channels/tradedesk/overview) · [AppLovin](/docs/channels/applovin/overview) · [LiveIntent](/docs/channels/liveintent/overview)
**Commerce & Marketplaces**
[Amazon](/docs/channels/amazon/overview) · [Meta & TikTok Shops](/docs/channels/shops/overview) · [ShopMy](/docs/tracking-for-shopmy) · [ROKT](/docs/channels/rokt/overview)
**Email & SMS**
[Klaviyo](/docs/channels/klaviyo/overview) · [Attentive](/docs/channels/attentive/overview)
**Affiliate & Partnerships**
[Impact](/docs/channels/impact/overview) · [Rakuten](/docs/channels/rakuten/overview)
**Other Setups**
[Non-integrated channels](/docs/tracking-for-other-platforms) · [Off-domain sites](/docs/tracking-for-off-domain-sites) · [Multiple stores & regions](/docs/adding-a-store-or-dashboard)
## Channel missing?
Any platform can be tracked with
[Spend API + UTMs](/docs/non-integrated-channel-setup-spend-api-utms).
# Rakuten Setup
Source: https://docs.northbeam.io/docs/channels/rakuten/overview
Add Northbeam link parameters in Rakuten and send Northbeam two scheduled reports so spend and revenue line up.
When you're done, Northbeam shows your Rakuten spend, impressions, visits, and attributed revenue on the same campaigns, publishers, and ads.
**Before you start**, make sure you have:
* Access to your [Rakuten Advertising Dashboard](https://dashboard.linkshare.com/) to edit link parameters and schedule reports
* Rakuten reports set to **USD** (if your account isn't in USD, contact Rakuten support to change the report output currency)
* Access to [Connections](https://dashboard.northbeam.io/settings/connections) in your Northbeam dashboard
Add four link parameters once in Rakuten.
Schedule two daily reports, then turn on the integration.
Check that parameters and spend are reaching Northbeam.
Do this first. You'll confirm it's done when you turn on the integration in the next step.
1. Open your [Rakuten Advertising Dashboard](https://dashboard.linkshare.com/).
2. In the header, click **Links**, then **Link Parameters**.
3. Add these four parameters:
| Parameter type | Parameter name | Parameter value | Mapping in Northbeam |
| :- | :- | :- | :- |
| Advertiser | `nb_platform` | `rakuten` | Categorizes traffic under the "Rakuten" channel |
| Linkshare | `nb_offer_id` | Offer ID *(selected from the Linkshare dropdown)* | Pulls Campaign Names into the Campaign Level of the Sales Page |
| Linkshare | `nb_publisher_sid` | Publisher SID *(selected from the Linkshare dropdown)* | Pulls Publisher Names into the Adset Level of the Sales Page |
| Linkshare | `nb_creative_id` | Creative ID *(selected from the Linkshare dropdown)* | Pulls Ad Names into the Adset Level of the Sales Page |
**If you skip this step:** Northbeam can't tie visits and orders to your Rakuten ads, so spend and revenue show up on separate lines.
Northbeam gets your Rakuten campaign and ad names, spend, and impressions from scheduled email reports. Impressions also power Northbeam's view-through modeling. Create **two** reports for full coverage:
* **This Month**, named `nb_reporting_tm`
* **Last Month**, named `nb_reporting_lm`
**Reports must be in USD.** Northbeam assumes all Rakuten data is in USD. If your Northbeam dashboard uses another currency, Northbeam converts spend with the daily exchange rate, but the conversion will be wrong if your Rakuten reports aren't in USD. If your Rakuten account isn't in USD, contact Rakuten support to change the report output currency.
Switching to USD only fixes reports sent after the change. To fix spend already imported in the wrong currency, [re-send the report](#fix-past-spend).
**Get your Northbeam report email**
1. In Northbeam, open [Connections](https://dashboard.northbeam.io/settings/connections).
2. Scroll to **Rakuten** and copy the **Email Address**. It looks like `[your_client_id]zzznbzzzrakuten@robot.northbeam.io`.
**Only Rakuten's scheduled reports work.** Northbeam reads the download link inside Rakuten's automated report email. Don't email or forward a CSV to this address yourself. Northbeam can't read it, so the data never imports.
**Report 1: This Month (`nb_reporting_tm`)**
1. Open your [Rakuten Advertising Dashboard](https://dashboard.linkshare.com/).
2. In the header, click **Reports > Reporting > Create New Report**.
3. Add these fields and metrics:
```
# of clicks
# of impressions
Offer ID
Offer Name
Publisher ID
Publisher Name
Publisher Encrypted ID
Total Commission
Transaction Date
Publisher Group ID
Publisher Group ID Name
Link ID
Link Name
```
4. Click **Save Report** and name it `nb_reporting_tm`.
5. Click **Manage Report > Schedule Report**.
6. Set these fields:
* **Date Range:** This Month
* **Time Zone:** (GMT+00:00) GMT
* **Date Type:** Transaction Date
* Uncheck **Include Summary**
* **Schedule Time:** Daily, with the hour set anywhere between 10AM and 6PM
* Check **Deliver report to Email** and paste the email address you copied from Northbeam
7. Click **Set Scheduling**.
**Report 2: Last Month (`nb_reporting_lm`)**
Repeat the steps above with two changes. Everything else stays the same.
* **Report name:** `nb_reporting_lm`
* **Date Range:** Last Month
**Turn on the integration**
1. Open [Connections](https://dashboard.northbeam.io/settings/connections) and scroll to **Rakuten**.
2. Check the boxes to confirm you've set up **Click UTMs** and **Scheduled Report**.
3. Click **Connect**.
**If you skip this step:** Rakuten campaign and ad names are missing, along with spend and impressions.
* **Parameters captured:** follow [Checking UTM tracking](/docs/checking-utm-tracking) to confirm the Northbeam parameters reach your landing pages.
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## Troubleshooting
### How do I fix incorrect spend?
Re-send the report. Northbeam always uses the latest report it receives and overwrites spend for the dates in it. This works for any dates, for example spend from before your reports were in USD. The `nb_reporting_lm` report isn't limited to last month.
1. Make sure your Rakuten reports are in USD.
2. Open the `nb_reporting_lm` report and set **Date Range** to cover the dates you need to fix. If Rakuten lets you, pick just those days.
3. Wait for the next scheduled delivery.
4. Set **Date Range** back to **Last Month**.
Emailing a corrected CSV yourself won't work. It has to come from Rakuten's scheduled report.
## Need help?
Start here if a check above fails.
# Reddit Ads FAQ
Source: https://docs.northbeam.io/docs/channels/reddit/faq
## Reddit Ads FAQ
### 1. Does the Reddit Ads integration support attribution and revenue tracking?
Yes. Reddit Ads supports click-based attribution when the account connection is active and the required Northbeam tracking parameter is present on each ad.
### 2. Which Northbeam attribution models are supported?
Reddit Ads supports:
* Clicks Only
* Last Click
* First Click
* Linear
Clicks + Modeled Views and Clicks + Deterministic Views are not currently supported for Reddit Ads attribution.
### 3. What Northbeam tracking parameter should I use?
Use:
```text theme={null}
nbt=nb:reddit_ads:reddit_ads:{{CAMPAIGN_ID}}:{{ADGROUP_ID}}:{{AD_ID}}
```
Add it to the **Destination URL** for every Reddit ad.
### 4. Can I add the tracking parameter at the campaign or ad group level?
No. The Northbeam tracking parameter must be added at the individual ad level for Reddit Ads.
### 5. Does Northbeam pull platform-reported clicks from Reddit Ads?
Yes. Northbeam pulls platform-reported click data from Reddit Ads. This can be compared with Northbeam Visits to help identify tracking coverage issues.
### 6. How far does Reddit Ads spend backfill?
The integration can backfill up to one year of historical spend when the account is first connected.
### 7. Why might Reddit Ads reporting differ from Northbeam?
Differences are expected for several reasons:
* **Attribution method:** Reddit uses a Reddit-only last-touch methodology, while Northbeam considers touchpoints across channels.
* **View-through attribution:** Reddit can count conversions after an impression without a click. Northbeam's current Reddit attribution is click based.
* **Attribution windows:** Reddit's account-level click and view windows can be configured to 1, 7, or 28 days. Reddit's default is 28-day click and 1-day view attribution.
* **Historical recalculation:** Reddit recalculates historical platform conversions using the account's current attribution window settings. If those settings change, historical numbers in Reddit Ads Manager may change retroactively.
* **Timezone:** Reddit reports using the ad account's timezone, while Northbeam uses the timezone configured for the client dashboard.
### 8. Why is Reddit Ads data missing or incomplete?
Check the following:
* Confirm that the Reddit Ads connection is active and the correct account is linked.
* Reconnect the account if the Connections page displays an authorization error.
* Confirm that every active ad contains the exact Northbeam tracking parameter.
* Confirm that the parameter is added at the ad level.
* Check that the landing page and any redirects preserve the `nbt` parameter.
* Confirm that the landing page loads correctly after the parameter is added.
### 9. Will editing an existing Reddit ad affect its engagement?
It may. Reddit Ads Manager warns that editing an ad's creative can reset its votes, comments, and awards. Review Reddit's warning before saving changes to a live ad.
# Reddit Ads Setup
Source: https://docs.northbeam.io/docs/channels/reddit/overview
Connect your Reddit Ads account and add the Northbeam parameter to each ad for click-based attribution.
When you're done, Northbeam shows your Reddit Ads spend, platform-reported clicks, and click-based attribution on the same campaigns, ad groups, and ads.
**Before you start**, make sure you have:
* Access to the correct Reddit Ads account
* Permission to authorize the Reddit Ads connection in Northbeam
* Permission to edit ads and destination URLs in **Reddit Ads Manager**
* Access to the correct Northbeam dashboard
Sync spend and platform-reported clicks from Reddit Ads.
Add `nbt` to the Destination URL of every ad.
Check the connection, the parameter, and incoming data.
1. Open [Connections](https://dashboard.northbeam.io/settings/connections) and find **Reddit Ads**. If you're still in onboarding, go to [**Integrations and UTMs > Reddit Ads**](https://dashboard.northbeam.io/onboarding?step=configure-platforms) instead.
2. Click **Connect** on the Reddit Ads card.
3. Sign in to Reddit Ads if prompted, approve the requested permissions, and select the correct ad account if asked.
4. Back in Northbeam, confirm the correct account is linked.
The connection pulls Reddit Ads spend, platform-reported clicks, and the campaign, ad group, and ad identifiers Northbeam uses for reconciliation and attribution.
**If you skip this step:** Reddit Ads data doesn't appear in Northbeam.
Add this parameter to the **Destination URL** of every Reddit ad:
```text theme={null}
?nbt=nb:reddit_ads:reddit_ads:{{CAMPAIGN_ID}}:{{ADGROUP_ID}}:{{AD_ID}}
```
Reddit fills in the campaign, ad group, and ad IDs when the ad is served.
1. Sign in to [Reddit Ads Manager](https://ads.reddit.com/).
2. Open the campaign, then the ad group, then the individual ad.
3. Find the **Destination URL** field and add the parameter.
4. Review the destination URL and click **Save**.
**Add it to every individual ad.** Adding it only at the campaign or ad group level isn't enough for Reddit Ads tracking.
**Use the right separator.** If the destination URL has no query parameters yet, start with `?`:
```text theme={null}
https://www.example.com/product?nbt=nb:reddit_ads:reddit_ads:{{CAMPAIGN_ID}}:{{ADGROUP_ID}}:{{AD_ID}}
```
If it already has a `?` and other parameters, join with `&`:
```text theme={null}
https://www.example.com/product?utm_source=reddit&utm_medium=paid&nbt=nb:reddit_ads:reddit_ads:{{CAMPAIGN_ID}}:{{ADGROUP_ID}}:{{AD_ID}}
```
**Copy the parameter exactly.** A missing colon, underscore, brace, or ID can stop Northbeam from matching visits correctly.
Reddit warns that editing a live ad's creative may reset its votes, comments, and awards. Review the warning in Reddit Ads Manager before you save changes to a live ad. When you can, add the parameter before the ad launches.
**If you skip this step:** visits and attributed results may be missing or assigned to the wrong campaign, ad group, or ad.
Check these in order:
1. In **Settings > Connections**, the Reddit Ads connection shows no authorization error, and the correct account is linked.
2. Every active Reddit ad has the exact Northbeam parameter.
3. Opening an ad's preview or destination URL loads the landing page, and the final URL still has `nbt` after any redirects.
4. Reddit Ads spend and platform-reported clicks start showing up in Northbeam.
5. Reddit visits land on the expected campaign, ad group, and ad.
When you first connect, Northbeam can backfill up to one year of Reddit Ads spend. Attribution for that history still depends on whether the ads had valid tracking parameters at the time.
For a full check:
* **Parameters captured:** follow [Checking UTM tracking](/docs/checking-utm-tracking) to confirm the Northbeam parameter reaches your landing pages.
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## Supported attribution models
Reddit Ads supports these Northbeam attribution models:
* Clicks Only
* Last Click
* First Click
* Linear
Clicks + Modeled Views and Clicks + Deterministic Views aren't currently supported for Reddit Ads.
## Need help?
Attribution, backfill, reporting differences, and missing data.
Start here if a check above fails.
# ROKT Setup
Source: https://docs.northbeam.io/docs/channels/rokt/overview
Connect ROKT with an App ID and App Secret, and have your ROKT account lead add Northbeam UTMs.
When you're done, Northbeam shows your ROKT spend and uses ROKT impressions for **Clicks + Modeled Views (C+MV)**.
**Before you start**, make sure you have:
* A login to ROKT **One Platform** (`my.rokt.com`) so you can generate API credentials
* A **ROKT account lead** you can contact to add the Northbeam UTMs
Generate an App ID and App Secret in ROKT and add them in Northbeam.
Ask your ROKT account lead to add the Northbeam UTMs.
Check that UTMs and the connection are working.
**Generate your API credentials in ROKT**
1. Sign in to **One Platform** at `my.rokt.com`.
2. Open **Profile Settings** (under your account icon at the bottom left).
3. Scroll to **Generate Personal API Credentials**.
4. Enter a name for your app and click **Generate**. ROKT creates an **App ID** and **App Secret**.
The app name can be anything, like `Northbeam`. It's only for your own reference. See [ROKT's guide to generating an App ID and App Secret](https://docs.rokt.com/developers/api-reference/reporting/query-api/#generating-a-rokt-app-id-and-app-secret).
Save the **App Secret** somewhere secure. You can't see it again after you leave the page.
**Enter the credentials in Northbeam**
1. Open [Connections](https://dashboard.northbeam.io/settings/connections) and select **ROKT**.
2. Paste your **App ID** and **App Secret**.
3. Click **Connect**.
**If you skip this step:** Northbeam doesn't get your ROKT spend or the impressions used for C+MV modeling.
You don't add these yourself. Contact your **ROKT account lead**, and they'll add the Northbeam UTM parameters for you.
Once the connection is live and the UTMs are on your ads:
* **Parameters captured:** follow [Checking UTM tracking](/docs/checking-utm-tracking) to confirm the Northbeam parameters reach your landing pages.
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## Supported attribution models
The ROKT integration supports these Northbeam attribution models:
* First Touch
* Last Touch
* Last Non-Direct Touch
* Clicks-Only
* Clicks + Modeled Views (C+MV)
## Need help?
Start here if a check above fails.
# Meta & TikTok Shops FAQ
Source: https://docs.northbeam.io/docs/channels/shops/faq
## Meta Shops FAQ
### 1. How do you track and attribute Meta Shops conversions?
Northbeam identifies individual Meta Shops purchases and fractionalizes purchase credit to all touchpoints in the customer journey that led to that purchase.
The major advantage of using Northbeam for Meta Shops attribution is that, unlike Meta, we can link Meta Shops purchases to even non-Meta campaign touchpoints; this way, customers get a true sense of how all paid touchpoints (including non-Meta campaigns) are driving Meta Shops purchase activity.
Note
**The Northbeam Pixel doesn't fire on Meta Shops storefronts, so we don't track Visits.** Consequently, the Visits count won't be recorded, and CPCs (Cost Per Clicks) may appear inflated for any Campaigns, Ad Sets, or Ads leading to Meta Shops.
### 2. How can I view Meta Shops performance?
Meta Shops purchase credit is seamlessly factored into your Attributed Revenue and Transactions metric columns.
To see the revenue or transaction breakout across Web and Shops orders:
1. Hover over any cell in the **Attributed Rev** or **Transactions** columns:
2. Click **Add as columns** to automatically insert new, sortable metric columns into the Sales Table that display the breakout between Web and Shops orders.
Pro Tip:
You could also break out your Web Shops, Meta Shops, and TikTok Shops revenue as custom columns by clicking **Customize Table**.
### 3. How can I view Meta Shops organic performance?
Sometimes customers visit your Shops platform to make direct purchases without having clicked on an ad - we refer to these as Organic purchases. Northbeam uses a combination of statistics, platform data, and your ad’s performance to produce an estimate of Organic purchases made on your Shops storefront.
You can see Organic Shops data using the **Meta Shops (Organic)** Platform label.
### 4. Can I see platform-reported Meta Shops metrics?
Yes, you can! On the [Sales page](https://dashboard.northbeam.io/sales), under **Customize Table**, find the following metrics under **Facebook Reported**:
* FB Meta Shop Purchases (1D Click)
* FB Meta Shop Purchases (1D View)
* FB Meta Shop Purchases (7D Click)
* FB Meta Shop Purchases (7D Click, 1D View)
* FB Meta Shop Purchase Conversion Value (1D Click)
* FB Meta Shop Purchase Conversion Value (1D View)
* FB Meta Shop Purchase Conversion Value (7D Click)
* FB Meta Shop Purchase Conversion Value (7D Click, 1D View)
***
## TikTok Shops FAQ
### 1. How do you track and attribute TikTok Shops conversions?
Northbeam identifies each individual TikTok Shops purchase and fractionalizes purchase credit across all your TikTok campaigns.
Note:
**The Northbeam Pixel doesn't fire on TikTok Shops storefronts, so we don't track Visits.** Consequently, the Visits count won't be recorded, and CPCs (Cost Per Clicks) may appear inflated for any Campaigns, Ad Sets, or Ads leading to TikTok Shops.
### 2. How can I view TikTok Shops ad performance?
TikTok Shops purchase credit is seamlessly factored into your Attributed Revenue and Transactions metric columns.
To see the revenue or transaction breakout across Web and Shops orders:
1. Hover over any cell in the **Attributed Rev** or **Transactions** columns:
2. Click **Add as columns** to automatically insert new, sortable metric columns into the Sales Table that display the breakout between Web and Shops orders.
Pro Tip:
You could also break out your Web Shops, Meta Shops, and TikTok Shops Revenue as custom columns by clicking **Customize Table** .
### 3. How can I view TikTok Shops organic performance?
Sometimes customers visit your Shops platform to make direct purchases without having clicked on an ad - we refer to these as Organic purchases. Northbeam uses a combination of statistics, platform data, and your ad’s performance to produce an estimate of Organic purchases made on your Shops storefront.
You can see Organic Shops data using the **TikTok Shops (Organic)** Platform label.
# Meta & TikTok Shops Setup
Source: https://docs.northbeam.io/docs/channels/shops/overview
Link your Meta Shop or TikTok Shop to your ad account so Northbeam can attribute Shops orders and revenue.
When you're done, Northbeam attributes your Meta Shops and TikTok Shops orders and revenue alongside your Web Shop orders.
**Before you start**, make sure you have:
* **Meta Shops:** a Meta Business user with **admin access** to both the Meta Shop (in Commerce Manager) and the Meta ad account
* **TikTok Shops:** a TikTok user with **admin access** to both the TikTok Shop and the TikTok ad account
* **Custom (non-Shopify) stores:** a way to send orders with an order tag through the [Northbeam Server API](/reference/post_orders)
Link your shop, connect the ad account, and finish store setup.
Bind your shop in Ads Manager and connect the ad account.
Check that Shops revenue shows up, not just spend.
Only use Meta Shops or TikTok Shops? Do that step and skip the other.
**A. Connect your Meta Shop to Ads Manager**
1. Log in to **Meta Ads Manager** with your advertiser account.
2. Go to **Commerce Manager > Shops**.
3. Confirm your shop is connected directly to the advertiser account.
**B. Connect your Meta ad account to Northbeam and check permissions**
1. Make sure your Meta advertiser account is [connected to Northbeam](/docs/channels/meta/overview#connect-your-meta-ad-account).
2. Make sure the Meta Business user connected to Northbeam is an **admin** on both:
* The Meta Shop (in Commerce Manager)
* The Meta advertiser account (in Business Manager / Ads Manager)
**C. Finish setup for your store type**
**Shopify stores:**
* Connect your Shopify store to [Facebook and Instagram by Meta](https://help.shopify.com/en/manual/online-sales-channels/facebook-instagram-by-meta/setup).
* Make sure your Meta Shop orders sync to your Shopify dashboard.
* Make sure your [Northbeam Pixel](/docs/add-pixel) and [Purchase Events](/docs/purchase-pixel) are set up (this is done during onboarding).
**Custom stores:**
* Use an **order tag** to mark Meta Shop orders.
* Send the tag in the `order_tags` field through the [Northbeam Server API](/reference/post_orders).
* [Tell our team](https://www.northbeam.io/submit-a-support-ticket) the tag name so we can finish setup.
**If you skip this step:** Meta ad spend can still show up, but Meta Shops revenue won't be attributed.
Northbeam needs the right TikTok Shop binding and permissions to attribute GMV and revenue.
**A. Bind your TikTok Shop to Ads Manager**
1. Log in to **TikTok Ads Manager** (not Business Center).
2. Go to **Assets > TikTok Shop**.
3. Confirm the shop is **bound directly under the advertiser account**. Shops bound only through Business Center won't sync.
**B. Connect your TikTok ad account to Northbeam and check permissions**
1. Make sure your TikTok advertiser account is [connected to Northbeam](/docs/channels/tiktok/overview#connect-your-tiktok-ad-account).
2. Make sure the TikTok user connected to Northbeam is an **admin** on both:
* The TikTok Shop
* The TikTok advertiser account
**C. Finish setup for your store type**
**Shopify stores:**
* Connect your Shopify store to [TikTok Shops](https://help.shopify.com/en/manual/online-sales-channels/tiktok/setup).
* Make sure your TikTok Shop orders sync to your Shopify dashboard.
* Make sure your [Northbeam Pixel](/docs/add-pixel) and [Purchase Events](/docs/purchase-pixel) are set up (this is done during onboarding).
**Custom stores:**
* Use an **order tag** to mark TikTok Shop orders.
* Send the tag in the `order_tags` field through the [Northbeam Server API](/reference/post_orders).
* [Tell our team](https://www.northbeam.io/submit-a-support-ticket) the tag name.
**If you skip this step:** TikTok ad spend may still show up, but GMV and revenue won't.
For a full check:
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
**Meta Shops: ad spend shows but no revenue?** Check that:
* The shop is connected directly in **Commerce Manager** and linked to your advertiser account.
* The Meta user is an **admin** on both the shop and the advertiser account.
* The Meta advertiser account is connected to Northbeam.
* **Shopify stores:** your store is connected to your shop through the [Facebook and Instagram by Meta](https://help.shopify.com/en/manual/online-sales-channels/facebook-instagram-by-meta/setup) app.
* **Custom stores:** your Meta Shop orders carry an `order_tag`, and you've told our team the tag name.
**TikTok Shops: ad spend shows but no GMV or revenue?** Check that:
* The shop is **bound in Ads Manager** (not Business Center).
* The TikTok user is an **admin** on both the shop and the advertiser account.
* The TikTok advertiser account is connected to Northbeam.
* **Shopify stores:** your store is connected to your shop through the [TikTok Shops](https://help.shopify.com/en/manual/online-sales-channels/tiktok/setup) app.
* **Custom stores:** your TikTok Shop orders carry an `order_tag`, and you've told our team the tag name.
## What are Web Shops, Meta Shops, and TikTok Shops?
Northbeam reports conversions from three types of shops. Each one is a different checkout, meaning **where** your customer places the order.
| Shop type | Where the order is placed |
| :- | :- |
| Web Shops | Your store's normal checkout, where the Northbeam [Purchase Event](/docs/purchase-pixel) fires. |
| Meta Shops | Facebook's and Instagram's built-in shopping, where customers buy on the platform instead of your online store. [Learn about Meta Shops](https://www.facebook.com/business/shops). |
| TikTok Shops | TikTok's built-in shopping, where customers buy on TikTok instead of your online store. [Learn about TikTok Shops](https://shop.tiktok.com/business/us). |
Meta Shops and TikTok Shops attribution only works with the **Clicks Only** and **Clicks + Modeled Views** attribution models.
With First Touch, Last Touch, Last Non-Direct Touch, or Linear, Meta Shops and TikTok Shops each report as their own line item, showing only total orders and revenue.
## Need help?
Common Shops setup and reporting questions.
Start here if a check above fails.
# Snapchat Ads FAQ
Source: https://docs.northbeam.io/docs/channels/snapchat/faq
## Snapchat Ads FAQ
### 1. How do I connect an extra account or remove an account?
Reference our step-by-step guide below:
### 2. Why do I see a data discrepancy?
**Discrepancies in Revenue and Orders are expected.** The reason for this lies in the differences between Northbeam's attribution model and the corresponding platform's attribution model. Each attribution model has a unique method of allocating credit.
For example, Northbeam's Clicks-Only model divides credit across all touchpoints and tries to push credit to your upper funnel channels. Let's say your in-platform model uses Last Click, which gives credit to the last touchpoint in the journey. This is going to cause a discrepancy.
To take it one step further, let's say both Northbeam and in-platform are using Last Click. Northbeam is unique in that we recognize all touchpoints from every single channel. Whereas most platforms only recognize touchpoints from that same platform.
In addition, there's often a difference in the attribution window. By default, Northbeam leverages a 1-Day window, which is different than many other platforms' default.
To get the most apples to apples comparison, be sure to compare data using same Attribution Model and Attribution Window. But keep in mind, it will never be exact.
#### Attribution Models and Windows
**Snapchat:**
* Attribution Model: Last Click
* Attribution Window: 28-Day Click/1-Day View
* [Source: Snapchat Attribution Settings](https://businesshelp.snapchat.com/s/article/pixel-measurement-faqs?language=en_US)
**Northbeam:**
* Attribution Model: Varies (default is Clicks-Only)
* Attribution Window: 1-Day (default, can extend to an infinite lifetime value)
### 3. Suspect a Tracking Issue?
Please reference our [Troubleshooting Northbeam Data](/docs/troubleshooting-tracking-issues).
* **Connection**: Make sure your Ad Account is still connected. Open [Connections](https://dashboard.northbeam.io/settings/connections) and check for any errors. Connections could break for a variety of reasons, but most commonly, the User losing access to the Ad Account.
* **UTMs**: Ensure all your ads contain Northbeam UTMs, as listed in the UTM step above.
* **Northbeam Pixel**: Ensure the Northbeam Pixel is firing on your landing page. Note that some site themes may not automatically transfer to landing pages on certain third-party apps, necessitating manual pixel placement.
* **Purchase Pixel:** Confirm that the Purchase Pixel is firing on your checkout page.
* **A-Record Setup:** Verify that the A-Record is correctly configured in your DNS Settings.
# Snapchat Ads Setup
Source: https://docs.northbeam.io/docs/channels/snapchat/overview
Connect your Snapchat ad account and add the Northbeam parameter so spend and revenue line up.
When you're done, Northbeam shows your Snapchat spend, impressions, visits, and attributed revenue on the same campaigns, ad sets, and ads.
**Before you start**, make sure you have:
* A Snapchat login with **admin access** to the ad account
* Access to **Snapchat Ads Manager** to edit your ads
Sync spend, impressions, and campaign structure from Snapchat.
Add `nbt` so visits and orders tie back to your ads.
Check that the parameter and the connection are working.
1. Open [Connections](https://dashboard.northbeam.io/settings/connections). If you're still in onboarding, go to **Integrations** instead.
2. Find **Snapchat Ads** and click **Connect**.
3. Sign in with a Snapchat login that has **admin access** to the ad account.
The connection pulls your current and historical campaigns, ad sets, and ads from the Snapchat Ads API, along with spend, impressions, and Snapchat-reported conversion and creative metrics. Impressions also power the **Clicks + Modeled Views** attribution model.
**If you skip this step:** campaign, ad set, and ad names are missing, along with spend, impressions, and Snapchat-reported metrics.
Add the `nbt` parameter to every ad. There are two ways to do it, and either one works.
### Method 1: Appending in the URL
Add this to the end of your ad's URL:
```
?nbt=nb:snapchat:{{site_source_name}}:{{campaign.id}}:{{adSet.id}}:{{ad.id}}
```
**Have existing UTM parameters?** Add ours to the end and join them with an ampersand (`&`). For example:
```
utm_source=paid&utm_medium=snapchat&nbt=nb:snapchat:{{site_source_name}}:{{campaign.id}}:{{adSet.id}}:{{ad.id}}
```
### Method 2: Using the Custom Parameter field
Create a **custom parameter** with this name and value:
| Parameter name | Parameter value |
| :- | :- |
| `nbt` | `nb:snapchat:{{site_source_name}}:{{campaign.id}}:{{adSet.id}}:{{ad.id}}` |
To have Northbeam add the parameter to new Snapchat ads automatically, [ask Support](https://www.northbeam.io/submit-a-support-ticket) to turn on UTM auto-appending.
**If you skip this step:** Northbeam can't tie visits and orders to your Snapchat ads, so spend and revenue show up on separate lines.
* **Parameters captured:** follow [Checking UTM tracking](/docs/checking-utm-tracking) to confirm the Northbeam parameter reaches your landing pages.
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## Need help?
Extra accounts, data discrepancies, and other common questions.
Start here if a check above fails.
# Tatari FAQ
Source: https://docs.northbeam.io/docs/channels/tatari/faq
## Tatari FAQs
1. [Where Can I Find My Tatari Data in Northbeam?](#1-where-can-i-find-my-tatari-data-in-northbeam)
2. [How Often Is Tatari Data Updated in Northbeam?](#2-how-often-is-tatari-data-updated-in-northbeam)
3. [I See Clicks and Matchbacks, but No Revenue or Transactions. What Should I Check?](#3-i-see-clicks-and-matchbacks-but-no-revenue-or-transactions-what-should-i-check)
***
## Tatari FAQ
### 1. Where Can I Find My Tatari Data in Northbeam?
After completing the integration, your Tatari data will appear under the **Clicks & Matchbacks** attribution model in Northbeam. "Matchbacks" represent data provided by Tatari for attributed orders.
Data Notice
It may take up to **7 days** for your Tatari data to fully populate in Northbeam. Data is processed from oldest to newest upon initial integration.
### 2. How Often Is Tatari Data Updated in Northbeam?
Tatari provides data reports once daily, typically with about a \~23-hour delay. Northbeam processes the file in the next scheduled run after it arrives. Because of that timing, Tatari data can sometimes appear 1–2 days behind in the dashboard depending on when the report was made available.
**Example:**
A report delivered by Tatari on May 13 may only contain data through May 12. If you check Northbeam on the morning of May 14 before the next processing run completes, the latest Tatari data available may still only reflect data through May 12.
This is expected behavior and does not necessarily indicate an issue with the integration.
### 3. I See Clicks and Matchbacks, but No Revenue or Transactions. What Should I Check?
If you see clicks and matchbacks but no attributed orders, verify the following:
* **Ensure all integration steps are completed:**
* User tracking is set up correctly.
* AWS credentials are configured properly.
* Tatari ID is accurate.
* **Check that the customer IDs in your Tatari user tracking match the customer IDs in your Northbeam orders:**
* For Shopify users, this is typically a match since Shopify has a direct integration.
* For custom implementations, mismatches are more common and can result in missing data.
If everything appears correct but data is still missing, please contact Northbeam support for further assistance.
# Tatari Setup
Source: https://docs.northbeam.io/docs/channels/tatari/overview
Set up Tatari user tracking and AWS data sharing so Northbeam can attribute your Tatari TV orders.
When you're done, Northbeam shows your Tatari clicks, matchbacks, and attributed orders under the **Clicks & Matchbacks** attribution model.
**Before you start**, make sure you have:
* A login to your [Tatari Dashboard](https://www.tatari.tv/) with access to **Account Settings → Integrations**
* **Shopify stores:** permission to install apps from the Shopify App Store
* **Custom platforms:** access to your site's `` code and the token Tatari gives you
* Access to [Connections](https://dashboard.northbeam.io/settings/connections) in Northbeam
This integration supports only **Streaming** inventory by default. **Linear** inventory isn't turned on automatically. If you need Linear, [contact Northbeam Support](https://www.northbeam.io/submit-a-support-ticket) to turn it on for your account.
Add Tatari's tracking to your site.
Turn on AWS Data Sharing and enter your Tatari ID.
After 24 hours, paste Northbeam's AWS credentials into Tatari.
Check that Tatari data is arriving.
Northbeam needs Tatari user tracking to attribute Tatari-driven orders correctly. The setup depends on your store platform. For more detail, see Tatari's [User Tracking Guide](https://drive.google.com/file/d/1U-ETZyVeEMclKiCY63falhOSN4EtbIAq/view?usp=sharing).
**Shopify**
1. Open the [Tatari Tag Manager](https://apps.shopify.com/tatari-tv) app on the Shopify App Store.
2. Click **Add app** and follow the prompts.
Once it's installed, the app manages the pixels that track funnel events from your TV campaigns.
**Non-Shopify (custom platform)**
1. Add this script to your site's ``. Replace `YOUR_TOKEN` (in two places) with the token Tatari gives you.
2. When a user logs in, call `tatari.identify({user_id})`, replacing `{user_id}` with your internal user ID.
```html theme={null}
```
**Use the same customer IDs in Tatari and Northbeam.** The user IDs you send to `tatari.identify` must match the customer IDs on your Northbeam orders. Custom setups vary, so check that yours lines up with Northbeam's requirements.
Need help with user tracking? Contact your Tatari representative. Northbeam can't help with this part.
**If you skip this step:** Northbeam can't accurately attribute Tatari-driven orders. If customer IDs don't match, you may see clicks and matchbacks but no revenue or transactions.
AWS Data Sharing lets Northbeam access your Tatari-attributed order data.
1. Log in to your [Tatari Dashboard](https://www.tatari.tv/).
2. Go to **Account Settings → Integrations** and make sure **AWS Data Sharing** is turned on.
Next, give Northbeam your Tatari ID and pick your source of truth so the two stay in sync:
1. Find your **Tatari ID** in your Tatari account URL.
2. In Northbeam, open [Connections](https://dashboard.northbeam.io/settings/connections) and find **Tatari**.
3. Enter your **Tatari ID**, select your **Orders Source of Truth**, and click **Connect**.
Northbeam then creates the AWS credentials you'll use in the next step.
**If you skip this step:** Northbeam can't access your Tatari-attributed order data.
**Wait 24 hours first.** After you enter your Tatari ID and source of truth, allow up to 24 hours for the connection to finish processing.
If you add the AWS credentials too early, Tatari shows **"API Error 400: Invalid ARNs"**. That's expected. Wait until the 24 hours are up and try again.
Then add the credentials:
1. Copy the AWS credentials Northbeam created when you connected your Tatari ID.
2. In Tatari, go to **Account Settings → Integrations** and select **AWS Data Sharing**.
3. Enter the AWS credentials from Northbeam and click **Add**.
**If you skip this step:** the integration isn't complete, so Tatari data doesn't reach Northbeam.
**Quick check:** your Tatari data shows up under the **Clicks & Matchbacks** attribution model. "Matchbacks" are the attributed orders Tatari reports. On a new integration, it can take up to **7 days** for all your data to fill in, oldest first.
For a full check:
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## Need help?
Where Tatari data shows up, how often it updates, and missing revenue.
Start here if a check above fails.
# TikTok Ads FAQ
Source: https://docs.northbeam.io/docs/channels/tiktok/faq
## TikTok Ads FAQ
### 1. How do I connect an extra account or remove an account?
Reference our step-by-step guide below:
### 2. Can you track conversions from TikTok Shops?
Yes! Learn how we track orders from TikTok Shop [here](/docs/tracking-for-shops).
### 3. Why do I see a data discrepancy?
**Discrepancies in Revenue and Orders are expected.** The reason for this lies in the differences between Northbeam's attribution model and the corresponding platform's attribution model. Each attribution model has a unique method of allocating credit.
For example, Northbeam's Clicks-Only model divides credit across all touchpoints and tries to push credit to your upper funnel channels. Let's say your in-platform model uses Last Click, which gives credit to the last touchpoint in the journey. This is going to cause a discrepancy.
To take it one step further, let's say both Northbeam and in-platform are using Last Click. Northbeam is unique in that we recognize all touchpoints from every single channel. Whereas most platforms only recognize touchpoints from that same platform.
In addition, there's often a difference in the attribution window. By default, Northbeam leverages a 1-Day window, which is different than many other platforms' default.
To get the most apples to apples comparison, be sure to compare data using same Attribution Model and Attribution Window. But keep in mind, it will never be exact.
#### Attribution Models and Windows
**TikTok:**
* Attribution Model: Last Click
* Attribution Window: 7-Day Click/1-Day View
* [Source: TikTok Attribution Settings](https://ads.tiktok.com/help/article/attribution-overview?lang=en)
**Northbeam:**
* Attribution Model: Varies (default is Clicks-Only)
* Attribution Window: 1-Day (default, can extend to an infinite lifetime value)
### 4. I think there's an issue with tracking. Please help!
Please reference our [Troubleshooting Northbeam Data](/docs/troubleshooting-tracking-issues).
* **Connection**: Make sure your Ad Account is still connected. Open [Connections](https://dashboard.northbeam.io/settings/connections) and check for any errors. Connections could break for a variety of reasons, but most commonly, the User losing access to the Ad Account.
* **UTMs**: Ensure all your ads contain Northbeam UTMs, as listed in the UTM step above.
* **Northbeam Pixel**: Ensure the Northbeam Pixel is firing on your landing page. Note that some site themes may not automatically transfer to landing pages on certain third-party apps, necessitating manual pixel placement.
* **Purchase Pixel:** Confirm that the Purchase Pixel is firing on your checkout page.
* **A-Record Setup:** Verify that the A-Record is correctly configured in your DNS Settings.
# TikTok Ads Setup
Source: https://docs.northbeam.io/docs/channels/tiktok/overview
Connect your TikTok ad account and add Northbeam parameters so spend and revenue line up.
When you're done, Northbeam shows your TikTok spend, impressions, visits, and attributed revenue on the same campaigns, ad groups, and ads.
**Before you start**, make sure you have:
* A TikTok login with **admin access** to the ad account
* Access to **TikTok Ads Manager** to edit your ads
Sync spend, impressions, and campaign structure from TikTok.
Add `nbt` and `nb_platform` so visits and orders tie back to your ads.
Click a live ad and check the landing page URL.
1. Open [Connections](https://dashboard.northbeam.io/settings/connections). If you're still in onboarding, go to **Integrations** instead.
2. Find **TikTok Ads** and click **Connect**.
3. Sign in with a TikTok login that has **admin access** to the ad account.
The connection pulls your current and historical campaigns, ad groups, and ads from the TikTok Ads API, along with spend, impressions, and TikTok-reported conversion and creative metrics. Impressions also power the **Clicks + Modeled Views** attribution model.
**If you skip this step:** campaign, ad group, and ad names are missing, along with spend, impressions, and TikTok-reported metrics.
Add these two custom parameters to every new and existing ad:
| Parameter | Value |
| :- | :- |
| `nbt` | `nb:tiktok::__CAMPAIGN_ID__:__AID__:__CID__` |
| `nb_platform` | `tiktok` |
1. In your ad settings, click **Build URL parameters**.
2. Click **Add parameter** twice and enter both parameters above.
3. Click **Apply**.
To have Northbeam add the parameters to new TikTok ads automatically, [ask Support](https://www.northbeam.io/submit-a-support-ticket) to turn on UTM auto-appending.
**If you skip this step:** Northbeam can't tie visits and orders to your TikTok ads, so spend and revenue show up on separate lines.
**Quick check:** click one of your live TikTok ads and look at the landing page URL. `nbt` should show real numbers where `__CAMPAIGN_ID__`, `__AID__`, and `__CID__` are. If you see that placeholder text, check the parameters against the table above.
For a full check:
* **Parameters captured:** follow [Checking UTM tracking](/docs/checking-utm-tracking) to confirm the Northbeam parameters reach your landing pages.
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
**Advertise on TikTok Shop?** Shopify stores should connect [TikTok Shops](https://help.shopify.com/en/manual/online-sales-channels/tiktok/setup). Custom stores should tag TikTok Shop orders with an `order_tag` through the [Server API](https://northbeam-orders-api.readme.io/reference/post_orders), then [tell our team](https://www.northbeam.io/submit-a-support-ticket) the tag name. See [TikTok Shops and Meta Shops](/docs/tracking-for-shops).
## GMV Max Campaigns
GMV Max is TikTok's automated campaign type for TikTok Shop. It handles targeting, bidding, and creative to hit a target ROI on total shop sales.
Northbeam attributes GMV Max automatically once these are in place:
* Your TikTok Shop is connected to a TikTok ad account
* That ad account is connected to Northbeam
* The connected user is an admin on both the ad account and the TikTok Shop
You'll find the results on the [Sales page](https://dashboard.northbeam.io/sales) under a platform called **GMV Max**.
Usually your TikTok Shop isn't connected to an ad account, or it's connected to one that isn't linked to Northbeam. To check in **TikTok Business Center**:
1. Select the right Business Center.
2. Go to **Assets → Ad Accounts** and select the ad account.
3. Go to **Assets → TikTok Shop**. If your shop isn't listed, it isn't linked to that ad account.
## TikTok Smart+ 2.0 (Smart Performance Campaigns)
Smart+ 2.0 adds **Asset Groups** between ad groups and creatives. Northbeam shows the asset group at the start of the ad name, so there's nothing to set up:
`Asset Group Name |:| Creative Name`
For example: `Prospecting - UGC |:| spark-echo_V3_QRT472_LD-20251112.mp4`
To see performance for one asset group, open the [Sales page](https://dashboard.northbeam.io/sales), filter Platform to **TikTok**, and at the **Ad level** search for the asset group name.
## Need help?
Common TikTok setup and reporting questions.
Start here if a check above fails.
# TradeDesk: Enable Clicks + Deterministic Views
Source: https://docs.northbeam.io/docs/channels/tradedesk/clicks-deterministic-views
[Clicks + Deterministic Views](/docs/clicks-deterministic-views) layers verified impression
data on top of your click tracking. Every view tied to a conversion is proven using an exact
identifier — not modeled or inferred — so you can see where TradeDesk's impression-heavy
placements are actually influencing purchases.
**REDS is required for C+DV.** If you set up TradeDesk using the scheduled report path, you'll
need to upgrade before you can enable C+DV. Ask your TradeDesk account manager for
**Northbeam Curated REDS**, then follow
[Path 1](/docs/channels/tradedesk/overview#path-1-with-reds).
## Before you enable
**Your `order_id` must match across both platforms.** The `order_id` your site sends to
TradeDesk via their pixel must be an **exact string match** for the `order_id` sent to
Northbeam. If the values differ, Northbeam can't link TradeDesk impressions to conversions
and C+DV will report no view credit.
Spot-check a few recent orders before you turn C+DV on.
Also confirm that your standard integration is complete on the REDS path, and that TradeDesk
spend and click data are already visible in your dashboard.
## Turn on C+DV
Go to **Account Settings → Model Settings → Attribution Models**, then find the
**Clicks + Deterministic Views** section.
Check the box for **TradeDesk** in the list of available platforms and save your changes.
Selecting a platform consents to sharing that platform's impression data with Northbeam,
so only account admins can change this setting.
Allow **24–48 hours** for Northbeam to ingest your impression data, match it to your orders,
and publish the results. Once C+DV is active, the data refreshes **3× per day**.
* Switch your attribution model to **Clicks + Deterministic Views**
* Confirm TradeDesk campaigns show view-attributed conversions alongside click-attributed ones
* Compare C+DV against Clicks-Only to see where view credit is unlocking value
* Check that there's no data-quality banner at the top of your dashboard
C+DV adds view credit on the same click-supported channels — Display, Video, Native Display,
and Native Video.
For how credit is divided between clicks and views, see
[Clicks + Deterministic Views](/docs/clicks-deterministic-views#how-does-clicks--deterministic-views-attribute-credit).
***
# TradeDesk FAQ
Source: https://docs.northbeam.io/docs/channels/tradedesk/faq
## Setup and REDS
### Do I need REDS to use TradeDesk with Northbeam?
No. The standard integration works two ways: REDS (event-level data) or a scheduled report
(daily email export). Both give you spend reporting and click attribution. REDS is only
required if you want [Clicks + Deterministic Views](/docs/channels/tradedesk/clicks-deterministic-views),
because C+DV needs event-level impression data to match views to individual orders.
### What is REDS?
Raw Event Data Stream is TradeDesk's event-level data export. Instead of aggregated daily
totals, it delivers individual impression, click, and conversion events. It's a paid add-on
through TradeDesk.
### How do I get REDS access?
Contact your TradeDesk account manager and request **Northbeam Curated REDS**. You'll sign an
access letter authorizing TradeDesk to share your data with Northbeam — there's a
[sample letter](/docs/channels/tradedesk/overview#path-1-with-reds) in the setup guide.
### Can I switch from the scheduled report to REDS later?
Yes. Request REDS access from your TradeDesk account manager at any time. Once the feed is
provisioned, Northbeam begins ingesting event-level data and you can enable C+DV.
### Which TradeDesk channels support click attribution?
Display, Video, Native Display, and Native Video. Channels that don't typically generate
clicks — TV, Digital Out of Home, and Audio — will see minimal click-based tracking data,
though spend still reports normally.
### I'm not seeing spend data.
**REDS path:** confirm TradeDesk has provisioned your feed and that the integration is enabled
on your Northbeam Connections page.
**Scheduled report path:** confirm the report is configured with the correct Northbeam email
address and a daily cadence, and that the integration is enabled on your Connections page.
Either way, allow one full data refresh cycle after initial setup.
***
## Clicks + Deterministic Views
### I opted in but I'm not seeing C+DV data after 48 hours.
First confirm your `order_id` values match between TradeDesk and Northbeam. If they do, reach
out to your Media Strategist, Customer Success Manager, or
[contact Support](https://www.northbeam.io/submit-a-support-ticket). Advertisers in restricted
or sensitive categories may have limited eligibility.
### Why do I see "withheld" in C+DV reporting?
Northbeam hides low-volume C+DV rows for privacy reasons. A row that doesn't meet the minimum
impression threshold at that level of reporting shows as "withheld." Aggregate totals can still
include those values once there's enough volume to show them safely.
### How often is C+DV data refreshed?
3× per day.
### Does C+DV support custom conversion events?
No. C+DV requires the standard purchase event with an `order_id` that matches the order ID in
Northbeam. If the values don't match, C+DV can't link impressions to conversions.
### How should I compare C+DV to Clicks-Only?
Look for directional differences. Where C+DV shows more credit than Clicks-Only, your
impression-driven TradeDesk campaigns are influencing conversions beyond what click tracking
captures — useful for cross-channel budget decisions.
### Does C+DV support international traffic?
Yes, across all participating platforms. For eligible customers this is enabled automatically.
### Are views from different platforms weighted differently?
No. Views are grouped by platform and credit is divided within each platform's pool. How much
credit a platform receives depends on how many views are in its pool, not on which platform it is.
See [how C+DV attributes credit](/docs/clicks-deterministic-views#how-does-clicks--deterministic-views-attribute-credit).
***
# TradeDesk Setup
Source: https://docs.northbeam.io/docs/channels/tradedesk/overview
Connect TradeDesk with or without REDS and add Northbeam UTMs so spend and click revenue line up.
When you're done, Northbeam shows your TradeDesk spend next to the visits and revenue from TradeDesk clicks, on the same campaigns, ad groups, and creatives.
**Before you start**, make sure you have:
* An active Northbeam account
* A TradeDesk advertiser account with **campaign manager access**
* Active TradeDesk campaigns on a [supported channel](#supported-channels-and-attribution-models)
* The Northbeam pixel installed and firing on your site
* **For the REDS path and C+DV:** REDS access with TradeDesk (a paid add-on)
* **For C+DV:** the same `order_id` sent to both TradeDesk and Northbeam. See [Enable C+DV](/docs/channels/tradedesk/clicks-deterministic-views).
Pick REDS or a scheduled report, then link TradeDesk to Northbeam.
Add the click UTMs to your ads, then turn on the integration.
Check that spend and clicks show up after the first data refresh.
TradeDesk can send data to Northbeam two ways. Both give you spend reporting and click attribution. Only REDS also supports [Clicks + Deterministic Views (C+DV)](#clicks-+-deterministic-views).
| | With REDS | Without REDS (scheduled report) |
| :- | :- | :- |
| **How data arrives** | Event-level impression, click, and conversion data via TradeDesk's Raw Event Data Stream | Aggregated daily spend sent to Northbeam as a scheduled email report |
| **Setup time** | About 1–2 weeks, including REDS provisioning | About 1–3 days |
| **Requires** | A signed REDS access letter with TradeDesk (a paid TradeDesk add-on) | A scheduled report set up in TradeDesk |
| **Supports C+DV** | Yes | No |
**C+DV requires REDS.** The scheduled report sends daily totals, not the event-level impression data needed to match views to individual orders. You can start with the scheduled report and switch to REDS later. Just ask your TradeDesk account manager for REDS access when you're ready.
### Path 1: With REDS
REDS (Raw Event Data Stream) is TradeDesk's event-level data export. Instead of daily totals, it sends individual impression, click, and conversion events. That's the detail Northbeam needs to match views to orders for C+DV. REDS is a paid add-on through TradeDesk.
1. **Request REDS access.** Ask your TradeDesk account manager for access to **Northbeam Curated REDS**. CC [the-trade-desk-reds-integration@northbeam.io](mailto:the-trade-desk-reds-integration@northbeam.io) so we can track the request.
2. **Sign the access letter.** TradeDesk will ask you to sign an access letter that lets them share your advertiser data with Northbeam. A sample is below.
3. **Wait for TradeDesk to set up the feed.** Once the signed letter is in, TradeDesk configures the REDS feed to send your data to Northbeam. This usually takes a few business days. You don't need to do anything.
4. **Connect in Northbeam.** Go to **Settings → Connections**, scroll down to **TradeDesk**, enter your TradeDesk account ID, and confirm.
Then [add your UTMs](#add-northbeam-parameters-to-your-ads) and turn on the integration. With REDS live, you also have what you need to [enable C+DV](/docs/channels/tradedesk/clicks-deterministic-views).
Customize this letter and send it to your TradeDesk account manager. If your account manager has their own version, use theirs.
> **To:** The Trade Desk Account Team
>
> **From:** \[Your Name], \[Your Company]
>
> **Date:** \[Date]
>
> **Re:** Authorization for Northbeam Curated REDS Access
>
> I, \[Your Name], authorized representative of \[Your Company], hereby authorize The Trade Desk to share our advertiser data with Northbeam, Inc. via the Raw Event Data Stream (REDS) for the purpose of attribution reporting and analytics.
>
> **Advertiser Name:** \[Your Company]
>
> **TTD Advertiser ID:** \[Your TTD Advertiser ID]
>
> **REDS Type:** Northbeam Curated REDS
>
> This authorization covers event-level impression, click, and conversion data associated with the above advertiser account. This data will be delivered to Northbeam's ingestion pipeline for use in spend reporting, click attribution, and Clicks + Deterministic Views (C+DV) attribution.
>
> **Signature:** \[Signature]
>
> **Name:** \[Your Name]
>
> **Title:** \[Your Title]
>
> **Company:** \[Your Company]
### Path 2: Without REDS (scheduled report)
This path uses TradeDesk's scheduled report feature to email daily spend totals to Northbeam. It covers spend reporting and click attribution, but **not** C+DV.
Open [Connections](https://dashboard.northbeam.io/settings/connections) and scroll down to **TradeDesk**. You'll find:
* **TradeDesk Channels:** the TradeDesk channels you can select. View-only channels (Audio, Digital Out of Home, TV) can't be measured for click attribution.
* **Click UTMs:** the UTM parameters to add to your ad click-through URLs
* **Email for Scheduled Report:** the Northbeam address your TradeDesk report should be sent to
Then set up the scheduled report in TradeDesk:
1. Go to the reporting section in TradeDesk.
2. Create a scheduled report that includes **spend, impressions, and clicks**.
3. Set the delivery email to the address on your Northbeam Connections page.
4. Set the cadence to **daily**.
Northbeam reads these reports automatically to fill in your spend data. Next, [add your UTMs](#add-northbeam-parameters-to-your-ads) and turn on the integration.
**Want C+DV later?** You can switch to REDS at any time. Ask your TradeDesk account manager for **Northbeam Curated REDS** and follow [Path 1](#path-1-with-reds). Your existing spend and click history stays in place.
**If you skip this step:** TradeDesk spend won't appear in Northbeam.
The Northbeam click UTMs let the Northbeam pixel tie a click back to a specific TradeDesk campaign, ad group, and creative.
1. Copy your UTM string from Northbeam under **Settings → Connections → TradeDesk**.
2. In TradeDesk, add it to the click-through URL of **every** active campaign.
**Your UTM must start with `&` or `?`.**
* If the URL already has parameters, use `&`: `yoursite.com?existing=param&nb_platform=tradedesk…`
* If the URL has no parameters, use `?`: `yoursite.com?nb_platform=tradedesk…`
**Then turn on the integration.** Go back to **Settings → Connections → TradeDesk** and:
1. Select the **TradeDesk Channels** you're actively advertising on.
2. Check the confirmation box for **Click UTMs**. On the scheduled report path, also check **Scheduled Reports**.
3. Click **Connect**.
Northbeam starts reporting spend and click performance on the next data refresh.
**If you skip this step:** campaigns without UTMs get no click attribution, so spend and revenue show up on separate lines and performance is hard to read.
Allow one full data refresh first. That's usually within 24 hours of turning on the integration.
* **Parameters captured:** follow [Checking UTM tracking](/docs/checking-utm-tracking) to confirm the Northbeam parameters reach your landing pages.
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
Then check the data in Northbeam:
* TradeDesk spend appears on the **Attribution** page.
* Click-through events appear for campaigns that have UTMs.
* First Touch, Last Touch, Last Non-Direct Touch, Linear, and Clicks-Only all show TradeDesk data.
* A sample campaign's UTM parameters resolve correctly.
**On the REDS path?** You should also see TradeDesk impressions. If spend shows up but impressions don't, the REDS feed may not be fully set up yet. Check with your TradeDesk account manager.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## Supported channels and attribution models
TradeDesk click tracking works on these [channels](https://partner.thetradedesk.com/v3/portal/api/doc/Channel): **Display**, **Video**, **Native Display**, and **Native Video**.
They support every Northbeam attribution model: First Touch, Last Touch, Last Non-Direct Touch, Linear, Clicks-Only, and Clicks + Deterministic Views (C+DV, REDS path only).
**Some channels have limited attribution.** TV, Digital Out of Home, and Audio rarely drive a direct website click, so you'll see very little tracking and performance data for them. Spend still reports as normal.
## Clicks + Deterministic Views
C+DV adds verified view credit on top of click tracking, for TradeDesk's impression-heavy placements. It needs the REDS path and a matching `order_id` in TradeDesk and Northbeam.
Turn on C+DV for TradeDesk once REDS is live.
## Need help?
Common TradeDesk setup, REDS, and C+DV questions.
Start here if a check above fails.
# Universal Ads FAQ
Source: https://docs.northbeam.io/docs/channels/universal/faq
## Universal Ads FAQ
### 1. Does the Universal Ads integration support attribution or revenue tracking?
No. Universal Ads is currently a spend-only integration.
Because Universal Ads is a CTV platform, the integration currently imports spend and campaign reporting data only, and does not support:
* UTMs or NBT parameters
* Revenue attribution
* Conversion attribution
* Click-based attribution
* Clicks + Deterministic Views (C+DV)
### 2. Is CDV supported for Universal Ads?
Not yet. CDV support for Universal Ads is currently not available, but may be added in a future release.
### 3. Can I connect multiple Universal Ads accounts?
At this time, Northbeam supports connecting one Universal Ads account per dashboard.
If you manage multiple Universal Ads accounts, you can still track the others by:
* Connecting one account through the native Universal Ads integration
* Sending spend for additional accounts via a Spend Sheet or Spend API
Any non-connected Universal Ads accounts will work similarly to other [non-integrated channels](/docs/tracking-for-other-platforms).
### 4. Why don't I see revenue or ROAS metrics tied to Universal Ads?
The Universal Ads integration currently imports spend data only.
Because there are no UTMs, click identifiers, or deterministic conversion signals passed from Universal Ads into Northbeam, revenue and conversion metrics cannot currently be attributed directly to Universal Ads campaigns.
### 5. Why might Universal Ads reporting differ from Northbeam?
Universal Ads may use view-through attribution windows within their platform reporting.
Universal Ads currently supports the following attribution windows:
* 7-day
* 14-day
* 30-day
Northbeam uses its own attribution methodology and reporting logic, so discrepancies between Northbeam and in-platform Universal Ads reporting are expected.
### 6. I think there's an issue with my Universal Ads integration. Please help!
Please reference our [Troubleshooting Northbeam Data](/docs/troubleshooting-tracking-issues).
* **Connection**: Open [Connections](https://dashboard.northbeam.io/settings/connections) and check for any errors on the Universal Ads connection.
* **Authentication**: Reconnect the integration if authorization has expired
* **Data Sync Timing**: Spend data may take some time to appear after connecting, depending on Universal Ads data sync timing
# Universal Ads Setup
Source: https://docs.northbeam.io/docs/channels/universal/overview
Connect your Universal Ads account so Northbeam pulls in your Universal Ads spend and campaign reporting.
When you're done, Northbeam automatically pulls in your Universal Ads spend and campaign-level reporting data.
**Before you start**, make sure you have:
* A Universal Ads login that can authorize the connection
* Access to [Connections](https://dashboard.northbeam.io/settings/connections) in Northbeam
**This is a spend-only integration.** Universal Ads is a CTV platform, so the integration doesn't support:
* UTMs or NBT parameters
* Revenue attribution
* Conversion attribution
* Click-based attribution
* Clicks + Deterministic Views (C+DV)
Sync spend and campaign reporting from Universal Ads.
Check that the connection is syncing.
1. Open [Connections](https://dashboard.northbeam.io/settings/connections). If you're still in onboarding, go to **Integrations** instead.
2. Find **Universal Ads** and click **Connect**.
3. Follow the Universal Ads sign-in flow to authorize your account.
Once it connects, your Universal Ads account shows up on the Connections page.
**If you skip this step:** Universal Ads spend and campaign reporting data won't appear in Northbeam.
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
Universal Ads doesn't use UTMs, so you can skip the UTM check. Spend can take a while to appear after you connect, depending on Universal Ads' sync timing.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## Need help?
Attribution limits, multiple accounts, and reporting differences.
Start here if a check above fails.
# Vibe.co Setup
Source: https://docs.northbeam.io/docs/channels/vibe/overview
Sign in to Vibe.co from Northbeam and turn on Clicks + Deterministic Views so Northbeam can credit your Vibe.co impressions.
When you're done, Northbeam shows your Vibe.co spend and uses Vibe.co impressions to give view credit under **Clicks + Deterministic Views (C+DV)**.
**Before you start**, make sure you have:
* A **Vibe.co login** with access to the advertisers you want to connect
* At least one **live Vibe.co campaign** on those advertisers
* Access to [Connections](https://dashboard.northbeam.io/settings/connections) and **Model Settings** in Northbeam
Sign in to Vibe.co from Northbeam and pick your advertisers.
Select Vibe.co as a C+DV platform in Model Settings.
Check that the connection is syncing.
1. Open [Connections](https://dashboard.northbeam.io/settings/connections). If you're still in onboarding, go to **Integrations** instead.
2. Find **Vibe** and click **Connect**.
3. Sign in to Vibe.co in the pop-up window.
4. Choose which advertisers to share and approve. **All advertisers, including future ones** means new advertisers sync without reconnecting.
5. Confirm your advertisers show on the Vibe card.
To change advertisers later, click **Manage Advertisers** on the Vibe card.
**Using an API key?** Vibe.co turns off API keys on **January 1, 2027**. Reconnect with the steps above before then.
**If you skip this step:** Northbeam doesn't get your Vibe.co spend or the impressions it needs for C+DV matching.
Once your Vibe.co connection is active in Northbeam:
1. Go to **Settings → Model Settings → Attribution Models**.
2. Select **Clicks + Deterministic Views (C+DV)**.
3. Under **Available Platforms**, check the box for **Vibe.co**.
4. Click **Save Changes**.
5. Allow up to 48 hours for Vibe.co impression data to show up in your dashboard.
Once the connection is live:
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
If a check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
## Supported attribution models
The Vibe.co integration supports these Northbeam attribution models:
* First Touch
* Last Touch
* Last Non-Direct Touch
* Clicks-Only
* Clicks + Deterministic Views (C+DV)
## Need help?
Start here if a check above fails.
# X Ads FAQ
Source: https://docs.northbeam.io/docs/channels/x/faq
## X Ads FAQ
### 1. How do I connect an extra account or remove an account?
Reference our step-by-step guide below:
### 2. Why do I see a data discrepancy?
**Discrepancies in Revenue and Orders are expected.** This is due to differences between Northbeam's attribution models and X's attribution model. Each attribution model has its own method for assigning conversion credit.
For example, Northbeam's Clicks-Only model considers touchpoints across channels. X uses its own platform attribution logic and mainly sees activity associated with X.
To take it one step further, let's say both Northbeam and in-platform are using Last Click. Northbeam is unique in that we recognize all touchpoints from every single channel. Whereas most platforms only recognize touchpoints from that same platform.
In addition, there's often a difference in the attribution window. By default, Northbeam leverages a 1-Day window, which is different than many other platforms' default.
To get the most apples to apples comparison, be sure to compare data using same Attribution Model and Attribution Window. But keep in mind, it will never be exact.
#### Attribution Models and Windows
**X:**
* Attribution Model: Platform-defined
* Attribution Window: Based on your X Ads attribution settings
**Northbeam:**
* Attribution Model: Varies by selected model
* Attribution Window: 1-Day by default, with additional configurable options
### 3. Suspect a Tracking Issue?
Please reference our [Troubleshooting Northbeam Data](/docs/troubleshooting-tracking-issues).
* **Connection**: Make sure your Ad Account is still connected. Open [Connections](https://dashboard.northbeam.io/settings/connections) and check for any errors. Connections could break for a variety of reasons, but most commonly, the User losing access to the Ad Account.
* **UTMs**: Ensure all your ads contain Northbeam UTMs, as listed in the UTM step above.
* **Northbeam Pixel**: Ensure the Northbeam Pixel is firing on your landing page. Note that some site themes may not automatically transfer to landing pages on certain third-party apps, necessitating manual pixel placement.
* **Purchase Pixel:** Confirm that the Purchase Pixel is firing on your checkout page.
* **A-Record Setup:** Verify that the A-Record is correctly configured in your DNS Settings.
# X Ads Setup
Source: https://docs.northbeam.io/docs/channels/x/overview
Connect your X ad account and add Northbeam parameters so spend and revenue line up.
When you're done, Northbeam shows your X spend, impressions, visits, and attributed revenue on the same campaigns, ad groups, and ads.
**Before you start**, make sure you have:
* An X login with **admin access** to the ad account
* Access to **X Ads Manager** to edit your ads
Sync spend, impressions, and campaign structure from X.
Add nine values in Add URL tracking so visits and orders tie back to your ads.
Click a live ad and check the landing page URL.
1. Open [Connections](https://dashboard.northbeam.io/settings/connections). If you're still in onboarding, go to **Integrations** instead.
2. Find **X Ads** and click **Connect**.
3. Sign in to X with the admin login.
The connection pulls your current and historical campaigns, ad groups, and ads from the X Ads API, along with spend, impressions, and X-reported conversion and creative metrics. Impressions power the **Clicks + Modeled Views** attribution model.
**If you skip this step:** campaign, ad group, and ad names are missing, along with spend and impressions.
In X Ads Manager, open **Add URL tracking** on every ad and fill in all nine values below. Northbeam needs all of them to match your X traffic to spend. You can also copy each one from your [UTM Guide](https://dashboard.northbeam.io/settings/utm-guide) in Northbeam.
| Field | Value |
| :- | :- |
| **Source** | `twitter` |
| **Medium** | `paid` |
| **Name** | `{{campaign_name}}` |
| **Term** | `{{adgroup_name}}` |
| **Content** | `{{ad_name}}` |
| `x_campaign_id` | `{{campaign_id}}` |
| `x_adgroup_id` | `{{adgroup_id}}` |
| `x_ad_id` | `{{ad_id}}` |
| `nb_platform` | `x` |
The first five are the standard fields at the top of the panel. Add the last four under **Custom parameters** by clicking **Add custom parameter** for each.
Your final URL looks like:
```text theme={null}
https://www.yoursite.com/?utm_source=twitter&utm_medium=paid&utm_campaign={{campaign_name}}&utm_term={{adgroup_name}}&utm_content={{ad_name}}&x_campaign_id={{campaign_id}}&x_adgroup_id={{adgroup_id}}&x_ad_id={{ad_id}}&nb_platform=x
```
Published ads can't be edited. To add the parameters to an existing ad, duplicate it and add them to the new copy.
**If you skip this step:** Northbeam can't tie visits and orders to your X ads, so spend and revenue show up on separate lines.
**Quick check:** click one of your live X ads and look at the landing page URL. You should see real IDs, like `x_campaign_id=1234567890`.
If the URL shows the literal text `{{campaign_id}}`, or the parameters are missing, check the values in **Add URL tracking** against the table above.
For a full check:
* **Parameters captured:** follow [Checking UTM tracking](/docs/checking-utm-tracking) to confirm the Northbeam parameters reach your landing pages.
* **Connection syncing:** follow [Checking platform connections](/docs/checking-api-connections) to confirm the account shows as connected and data is arriving.
## Need help?
Adding accounts, and why X and Northbeam numbers differ.
Start here if a check above fails.
# Checking Ad Platform Connections
Source: https://docs.northbeam.io/docs/checking-api-connections
Before using the dashboard, it's important to make sure that we're receiving data from our integrated ad platforms.
## How to check your connections
1. Go to **Settings › Connections**.
2. Review each connected platform. A healthy connection shows a **Connected** status; a broken one shows an error or a **Reconnect** prompt.
3. For any platform showing an error, select it and follow the **Reconnect** flow to re-authorize.
4. Confirm each platform you advertise on is listed and connected. If a platform is missing, add it from this same page.
The video below walks through the same check in the product.
# Need additional help?
If you need further assistance, reach out to [Support](https://www.northbeam.io/submit-a-support-ticket)!
# Checking UTM Tracking
Source: https://docs.northbeam.io/docs/checking-utm-tracking
Before using the dashboard, it's important to ensure UTMs are inserted on your ads and that the UTMs are getting tracked by our pixel.
Checking UTMs is a two-part check: first confirm the UTM parameters are actually on your ad links in each ad platform, then confirm Northbeam's pixel is capturing them in your data.
## Part 1: Check that UTMs are on your ads (Google, Facebook, TikTok)
1. Open the ad platform's manager (Google Ads, Meta Ads Manager, or TikTok Ads Manager).
2. Navigate to the final URL / tracking template for a live ad.
3. Confirm the Northbeam UTM parameters are present and correctly formed (for example `utm_source`, `utm_medium`, `utm_campaign`).
4. Repeat for at least one ad per platform you run.
Walkthrough for this part:
## Part 2: Check that Northbeam is tracking the UTMs
1. In Northbeam, open a view that breaks down traffic by campaign or source.
2. Confirm your UTM-tagged campaigns are appearing with recognizable names (not lumped under "unattributed" or "unknown").
3. If tagged traffic is missing, the UTMs may not be firing on click or the pixel may not be capturing them — see [Troubleshooting Northbeam Data](/docs/troubleshooting-tracking-issues).
Walkthrough for this part:
# Need additional help?
If you need further assistance, reach out to [Support](https://www.northbeam.io/submit-a-support-ticket)!
# 🧬 Clicks + Deterministic Views (C+DV)
Source: https://docs.northbeam.io/docs/clicks-deterministic-views
Understanding Northbeam's most innovative attribution model.
## What is Clicks + Deterministic Views?
### Northbeam’s C+DV model is a transformative shift in attribution.
With C+DV, you can see the true, proven impact of your ads—even on platforms that are more impression-focused. This helps you capture the real value of awareness-driven ads and **move beyond the limitations of last-click attribution.**
**Watch this video for the full tour and explanation!**
Today’s marketing landscape is more fragmented than ever, and we know that different ad platforms drive different user behavior. On view-heavy platforms, users often don’t click directly through an ad to purchase.
However, research shows that users have high brand recall from ads they’ve seen on these platforms—and we know that brand recall ultimately helps drive conversions. So how do we connect the two?
### The solution: Clicks + Deterministic Views
Clicks + Deterministic Views is Northbeam’s next-generation multi-touch attribution (MTA) model. It builds on our Clicks-Only model by layering in verified impression & view data directly from participating ad platforms.
These platform events are combined with Northbeam’s industry-leading, first-party pixel and order data to provide a **complete and accurate view** of how marketing actually drives conversions. Unlike traditional “view-through” attribution, Northbeam links views deterministically, meaning every impression tied to a conversion is **verified, not inferred.**
### Deterministic? What's that?
Attribution models differ in how they connect ads to conversions:
* **Deterministic attribution:** Matches conversions to ads using exact identifiers (like order ID, hashed email, or phone). Every link is **verified** and **certain.**
* **Probabilistic attribution:** Uses models and assumptions (like device type, IP, or behavior patterns) to **guess** which ad drove a conversion.
## How does Clicks + Deterministic Views work?
Northbeam integrates directly with each participating ad platform to match verified impression and view events to real orders. This is not modeled or inferred — every view tied to a conversion is proven via exact identifiers like order ID or hashed email.
* **Clicks and views share credit.** First-party click data from Northbeam's pixel is combined with verified view data from participating platforms. Both contribute to the final attribution.
* **Credit is assigned at the event level.** Each touchpoint — whether a click or a view — is evaluated individually and assigned credit based on the platform pooling logic below.
* **Safeguards are built in.** Data quality checks prevent credit dilution, unfair shifts between platforms, and attribution based on bad or unverified signals.
[Jump to the "How CDV Attributes Credit" section to see the logic. ](/docs/clicks-deterministic-views#how-does-clicks--deterministic-views-attribute-credit)
## Why is Clicks + Deterministic Views useful?
* **See beyond clicks.** Capture both verified views and clicks to understand the full impact of your ads.
* **True upper-funnel visibility.** Quantify how awareness and prospecting campaigns actually influence downstream purchases.
* **Deterministic accuracy.** Every impression tied to a conversion is **proven**—not modeled—so attribution is grounded in reality.
* **Smarter budget allocation.** Know which campaigns drive downstream revenue and confidently scale what works.
* **Cross-platform clarity.** Combine verified impression data with Northbeam’s pixel + order data for a single source of truth.
* **Privacy-preserving measurement.** Data is processed in Northbeam’s clean room, ensuring compliance and security.
* **Reduce wasted spend.** Eliminate over-crediting of last clicks and avoid underspending on top-of-funnel channels.
## How does Clicks + Deterministic Views attribute credit?
C+DV unifies click and view data across platforms to give the most complete measurement of marketing performance.
* **How we divide credit for a single purchase**
* Paid clicks and paid views take full precedence over touchpoints with the following `Category (Northbeam)` labels:
* `Direct`
* `Organic`
* `Organic Search`
* `Paid - Branded Search`
* `Email`
* `SMS`
* Credit between paid clicks and paid views is split as follows:
* Each first-party (i.e. Northbeam observed) paid click touchpoint receives a share of credit.
* For each participating C+DV partner platform, the remaining share of credit is distributed equally across all view touchpoints from that platform using the following methodology:
* Views are grouped by platform and credit is divided within each platform “pool.” For example, if there is 1 view on Platform A and 10 views on Platform B, Platform B will receive more total credit, but each individual view will have less weight than the 1 view on Platform A.
* We do not weight views from different platforms differently; the amount of credit assigned to each platform is dependent on how many views are in that platform’s “pool.”
* Credit is not assigned based on where each touchpoint falls in the funnel; for example, if a customer views an ad on Snap, and later views an ad on Pinterest, the Pinterest ad does not earn less credit.
### Worked Examples
#### Example 1: Clicks and Views Across Two Publishers
**Journey:** A customer is exposed to ads across two platforms before making a \$100 purchase.
1. T1 — Publisher 1 (P1) View
2. T2 — Publisher 2 (P2) View
3. T3 — Publisher 2 (P2) View
4. T4 — Publisher 1 (P1) Click
5. T5 — Direct Click
| Touchpoint | Type | Platform | Credit Earned |
| - | - | - | - |
| T1 | View | Publisher 1 | \$27 |
| T2 | View | Publisher 2 | \$23 |
| T3 | View | Publisher 2 | \$23 |
| T4 | Click | Publisher 1 | \$27 |
| T5 | Direct Click | Direct | \$0 |
| **Total** | | | **\$100** |
**Why does credit split this way?**
Clicks and views both earn credit. Direct is excluded as a lower funnel touchpoint when upper funnel touchpoints exist in the journey.
The \$100 is divided between the two publisher pools — Publisher 1 (1 view + 1 click) and Publisher 2 (2 views). Within each publisher, credit is shared equally across that publisher's touchpoints. Publisher 1 has 2 touchpoints so each earns \$27. Publisher 2 has 2 views so each earns \$23.
***
#### Example 2: View-Only Journey Across Three Platforms
**Journey:** A customer sees ads on three platforms but never clicks before making a \$100 purchase. No paid clicks exist in the journey.
* 1 Snap view
* 2 Meta views
* 3 TikTok views
| Platform | Views | Each View Earns | Total Platform Credit |
| - | - | - | - |
| Snap | 1 | 21% (\$21) | 21% (\$21) |
| Meta | 2 | 17.5% (\$17.50) | 35% (\$35) |
| TikTok | 3 | 14.6% (\$14.60) | 44% (\$44) |
| **Total** | **6** | | **100% (\$100)** |
**Why does credit split this way?**
Each platform starts with an equal share of total credit regardless of how many views it has. Snap, Meta, and TikTok each begin with a 1/3 pool. Within each platform, that pool is divided equally across all views from that platform.
* Snap has 1 view so it earns the full pool = 21% per view
* Meta has 2 views so each earns half of its pool = 17.5% per view
* TikTok has 3 views so each earns a third of its pool = 14.6% per view
This protects against one platform dominating credit simply by serving more impressions.
**Note:** These percentages are rounded for illustration. Actual credit values in your dashboard may vary slightly based on the number of participating platforms and touchpoints in each journey.
***
## C+DV Demo
Watch below for a full demo of Clicks + Deterministic Views, including how to enable it and how to interpret the data.
## Enabling Clicks + Deterministic Views in your account
1. Go to Account settings > Model settings > Attribution models.
2. Select Clicks + Deterministic Views, checking each platform you want to track.
1. *Note: By selecting a platform, you are consenting to share impression data from the platform to Northbeam. For this reason, only admins are able to change these settings.*
3. Wait 24-48 hours until we have processed your data. It could be shorter, so stay tuned to your dashboard.
#### ⚠️ Pinterest opt-in instructions
**Step 1:**
* The account owner will need to log into Northbeam’s dashboard
* Open [Apex](https://dashboard.northbeam.io/settings/apex).
* Select **Pinterest** from the list of platforms
* *Note: Enabling APEX for Pinterest is necessary for optimal data quality–it does NOT affect your Pinterest campaigns.*
**Step 2:**
* Head to the **Model Settings** page
* Select **Pinterest** under the Clicks + Deterministic Views section
**Step 3 (Important):**
* Please disconnect and reconnect your Pinterest account in Northbeam.
#### ⚠️ MNTN opt-in instructions
* MNTN customers will need to follow additional steps to properly opt in to C+DV.
* [Instructions here](https://help.mountain.com/en/articles/11644276-integrate-northbeam)
***
## FAQs
### 1. Why does Clicks + Deterministic Views data not match up to my Clicks + Modeled Views data?
C+MV is probabilistic and does not observe the ad platform events directly. C+DV is deterministic the same way that CO is deterministic. It is a model based on events that we or the ad platform KNOWS have happened.
### 2. Why are certain ad channels not getting C+DV credit for conversions?
Clicks + Deterministic Views is deterministic, so if an ad platform is not participating in the program they will not receive any additional view credit.
### 3. Are all views weighted equally?
Views are grouped by platform and credit is divided within each platform "pool." We do not weight views from different platforms differently; the amount of credit assigned to each platform is dependent on how many views are in that platform's pool. Currently, we do not specifically use the platform of the view, or the type of ad that displayed the view, as factors in determining credit. This is consistent with the behavior of our current Clicks-Only attribution model.
### 4. Why can't I see in-app views on the order details page?
This level of tracking is not permitted under privacy law.
### 5. How often is C+DV data refreshed?
Currently, 3x per day.
### 6. How should I compare C+DV performance to Clicks + Modeled Views or Clicks-Only?
Look for directional differences between C+DV vs. Platform reporting, C+DV vs. Clicks-Only data. These differences will show you where C+DV is unlocking value, and new insights.
### 7. How should I use C+DV?
Use it to make better optimization decisions within each channel. For example, when gauging "what campaigns/audience/ads are impactful?" it should give you a more precise signal than Modeled Views or Clicks-Only. You can also use it to get directional data points for cross-channel investment — for example, is this channel having an impact beyond what we see on a last-click basis?
### 8. Since clicks are always preceded by views, how do you de-dupe between clicks and views?
Views + click pairs that happen within 30 seconds of each other are deduplicated.
### 9. Why don't I have access to C+DV?
Most likely, we do not have enough order IDs to match with impression data. This is often the case for advertisers who fall into 'sensitive' categories, such as health & wellness. For questions around this, please reach out to your Media Strategist, Customer Success Manager, or contact [Support](https://www.northbeam.io/submit-a-support-ticket).
### 10. Does C+DV support international traffic?
Yes. C+DV supports international traffic across all participating integrated partners. For eligible customers, this is enabled automatically and no additional setup is required.
Northbeam has backfilled available historical data where applicable, but C+DV models are incremental and will apply moving forward once data is available in the model.
### 11. I've turned on C+DV, but I'm not seeing any data. Why?
It can take up to 48 hours after providing consent to see C+DV data in the dashboard. If you are still not seeing data after 48 hours, reach out to your Northbeam rep or contact [Support](https://www.northbeam.io/submit-a-support-ticket).
### 12. Why do I see “withheld” in C+DV reporting?
“Withheld” means Northbeam is hiding certain low-volume C+DV rows for privacy reasons.
For Meta C+DV, this typically happens when the slice you’re looking at does not meet the minimum threshold of 1,000 impressions at that level of reporting.
In practice, that means an ad, ad set, campaign, or daily row can be withheld if that specific row has fewer than 1,000 impressions. Because the threshold is applied at the level of the report, detailed rows may appear lower than aggregate totals, even though the aggregate can still include that underlying value once there is enough volume to safely show it.
### 13. Does C+DV support custom events?
No. C+DV does not support custom events or custom conversion events as a replacement for the standard Meta `Purchase` event.
Meta C+DV requires the standard `Purchase` event to fire with an `order_id` that matches the corresponding order ID in Northbeam. If purchases are tracked through a custom event instead of the standard `Purchase` event, C+DV may not work as expected, even if that custom event is visible in Meta Events Manager.
### 14. I'm not seeing C+DV data for Meta specifically.
Meta CDV works by matching the `order_id` in your Meta Purchase events to the `order_id` tied to orders in Northbeam.
**We look for at least an 80% match rate** — meaning if Meta records 100 purchases, at least 80 of those `order_id`s must exist in Northbeam.
If you fall below this 80% threshold, you'll see a red banner at the top of your dashboard:
**If your dashboard has this banner, follow the steps below to find and fix the mismatch.**
Low or missing Meta C+DV data is almost always caused by **one** of three things:
1. Meta isn't receiving an `order_id` at all
2. Meta is receiving a *different* `order_id` than what Northbeam has on file
3. Your store is in a restricted category where Meta limits order-level identifiers regardless of your setup.
***
#### Step 1 — Check what `order_id` Meta is actually receiving
Before changing anything, confirm what Meta is getting today. There are two ways to check.
##### Option A: Test Events
*Place a test purchase on your store and inspect the order\_id coming through.*
1. Go to **Meta Events Manager → your pixel or CAPI data source**
2. Click the **Test Events** tab
3. Trigger a test purchase on your site
4. Find the `Purchase` event and expand it
5. Look for the `order_id` field in the event parameters
***
##### Option B: Sampled Activities
*Inspect the order\_id of your past Purchase Events.*
1. Go to **Meta Events Manager → your Purchase event → Sampled Activities**
2. This shows raw parameters from real purchases in the last 24 hours
3. Hover over any Purchase event and look for `order_id` or `orderId` in the parameter list
Once you know what Meta is receiving, compare it to a recent order on the Northbeam [Orders page](https://dashboard.northbeam.io/orders). The two values must be an **exact string match** for CDV to work.
✅ `order_id` is present and matches the order number in Northbeam (e.g. `10045`)
❌ `order_id` is blank, missing, or shows a cart/checkout token instead of a final order number
***
#### Step 2A — Fix: `order_id` missing or wrong in Meta CAPI (server-side or GTM Server)
> **This step is for CAPI only** — the server-side connection between your store and Meta. If you're only using the Meta Pixel (browser-side tracking), skip to Step 2B or 2C.
This is the most common source of low Meta CDV coverage. The fix depends on how your CAPI is set up — find your setup below. If you're not sure which applies to you, check with your developer or agency.
In all cases, your final CAPI Purchase payload must include `order_id` at the top level like this:
```json theme={null}
{
"event_name": "Purchase",
"order_id": "10045",
"custom_data": {
"value": 99.00,
"currency": "USD"
}
}
```
***
**Setup 1: Shopify Native Integration**
If you enabled CAPI directly in Shopify via [Facebook & Instagram by Meta](https://help.shopify.com/en/manual/online-sales-channels/facebook-instagram-by-meta/setup) sales channel, the`order_id` is passed automatically — you likely don't need to change anything here.
If you're still seeing mismatches, the most likely cause is a custom script overriding the native event. Check with your developer to confirm nothing is conflicting with Shopify's native CAPI integration.
> **Not sure if CAPI is enabled?** Go to **Meta Events Manager → your Pixel → Settings** and check whether Conversions API is listed as Active.
***
**Setup 2: Third-party app (Blotout, Elevar, Littledata, Analyzify, Fueled, or similar)**
These apps handle the server-side CAPI connection and manage field mapping on your behalf. To fix `order_id`:
1. Log into your app's dashboard
2. Find the Meta CAPI or Meta destination settings
3. Locate the Purchase event configuration
4. Confirm `order_id` is mapped to your Shopify order number — not a checkout token, cart ID, or session ID
5. Save and trigger a test purchase to confirm
If you don't see a field mapping UI, or your app is fully managed (e.g. Blotout, Elevar's managed tier), please contact the app's support team.
***
**Setup 3: GTM Server-Side container**
1. Open your **GTM Server container**
2. Find the **Meta CAPI tag**
3. Look for the `order_id` field — it may be blank, missing, or pointing to the wrong variable
4. Map it to the data layer variable that holds the final confirmed order number (e.g. `order_id`, `transaction_id`, or `order.name` — check with your developer if unsure)
5. Use **GTM Preview mode** to trigger a test purchase and confirm the correct value is being sent
6. Publish the container
***
**Setup 4: Custom server-side code**
Your developer needs to update the Purchase event payload in your backend code to explicitly include `order_id`, set to the final confirmed order number — the same ID that appears in Northbeam's Orders page.
***
#### Step 2B — Fix: `order_id` missing in Meta Pixel (Shopify)
> **This step is for the browser-side Meta Pixel only** — not CAPI. If you're also running CAPI alongside your pixel, make sure you've completed Step 2A first.
For Shopify stores using the [Facebook & Instagram by Meta](https://help.shopify.com/en/manual/online-sales-channels/facebook-instagram-by-meta/setup) sales channel, `order_id` is captured automatically on the purchase confirmation page — you likely don't need to change anything here.
The exception is if you've added custom Purchase tracking scripts that fire their own pixel event and override the native one. In that case, please do one of the following:
* Remove the custom script if it isn't also passing `order_id`
* Update it to explicitly include the Shopify order number and ensure it doesn't fire alongside the native event
***
#### Step 2C — Fix: `order_id` missing in Meta Pixel (non-Shopify custom pixel)
> **This step is for non-Shopify stores manually firing the browser-side Meta Pixel** — not CAPI. If you're running CAPI, see Step 2A instead.
If you're manually firing the Meta pixel, your Purchase event must include `order_id`. Update your snippet to:
```javascript theme={null}
fbq('track', 'Purchase', {
value: 99.00,
currency: 'USD',
order_id: '10045' // must match the order_id Northbeam receives
});
```
The `order_id` value must come from the same source your backend uses for the final confirmed order number.
***
#### Step 3 — Confirm the fix worked
After making changes, trigger a test purchase and check **Events Manager → Test Events** to confirm `event_name = Purchase` and `order_id` exactly matches the corresponding order in Northbeam. Over the next 24–48 hours, Meta CDV order coverage should improve in your Northbeam dashboard.
Once you've waited 24–48 hours, check your Northbeam dashboard to confirm the red banner is no longer showing. If the banner is gone, your order ID coverage has met the 80% threshold and CDV is working correctly. If you'd like us to double-check your coverage rate, reach out to your Media Strategist, Customer Success Manager, or contact [Support](https://www.northbeam.io/submit-a-support-ticket).
***
### Still seeing low coverage after fixing?
If your setup looks correct, `order_id` values are matching, and the banner is still showing, your store may be in a restricted or sensitive category where Meta limits the order-level identifiers they expose. In those cases, CDV coverage may remain limited even with a correct implementation — this is a Meta policy constraint, not a fixable configuration issue.
#### Restricted health category in Meta
If your store falls into a restricted health or wellness category, Meta may limit the impression-level data they share with third parties, including Northbeam. When this restriction is active, Meta cannot send Northbeam the view data required for C+DV, so Meta will not receive view credit regardless of your pixel or CAPI setup.
This is a Meta policy constraint, not a configuration issue.
To request access, submit an appeal directly to Meta: [Appeal a restricted category decision](https://www.facebook.com/business/help/422289316306981)
The most effective path is to contact your Meta rep directly — they can confirm whether a restriction applies to your account, advise on appeal eligibility, and escalate internally if needed.
**Best practice:** Use CAPI or Shopify's native pixel integration for the most reliable `order_id` coverage and highest C+DV eligibility.
# Confirm Setup Requirements
Source: https://docs.northbeam.io/docs/confirm-setup-requirements
## Overview
Regardless of your eCommerce platform (Shopify, WooCommerce, Magento, Custom, etc), all customers 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.
If we discover any additional setup needed along the way, we can always schedule a call to evaluate.
## Considerations
### 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. Learn more about **[multi-dashboard configurations](#multi-dashboard-configurations) below.**
If you have a single site, you are good to proceed
### Checkout Flow(s)
**If you use any other checkout flows or sales channels** (ex. ClickFunnels), we need to determine if it’s trackable by our system and if so, the appropriate scripts to use., so **please[submit a support ticket](https://info.northbeam.io/knowledge/help) with our Customer Success Team**.
If you use Shopify for your checkout, you are good to proceed
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.
## Multi-dashboard configurations
### What is a multi-dashboard configuration?
A multi-dashboard configuration in Northbeam consists of a several dashboards each created for a part of a business.
In addition to individual dashboards, some companies also implement a rollup dashboard that encompasses all the data from other dashboards.
If you proceed with a multi-dashboard configuration, you can easily switch between different dashboards with the same login.
### When to use a multi-dashboard configuration
If you sell products in multiple regions, have multiple businesses, or use multiple domains, you may wish to analyze the performance of each individually rather than as a single blended entity.
* **Do you operate in multiple countries?**
* If you operate internationally, you may wish to create individual dashboards for each country or region if you plan to analyze the performance of your marketing in those markets. Learn more about [**multi-region configurations**](/docs/adding-a-store-or-dashboard).
* **Do you have multiple businesses?**
* If you have multiple businesses that operate under a parent company, you may wish to create dashboards specific to each business. Learn more about [**multi-business configurations**](/docs/adding-a-store-or-dashboard).
* **Do you have storefronts on multiple domains?**
* A common example is for international stores—in some cases it makes sense to create separate Northbeam accounts for each one. Often the checkout flow of each store (i.e. whether it’s shared or separate) will determine whether reporting should be split into separate accounts. Learn more about [**multi-domain configurations**](/docs/adding-a-store-or-dashboard).
# Connect Northbeam to Another AI Tool
Source: https://docs.northbeam.io/docs/connect-northbeam-to-ai-agent
Connect Northbeam to any AI assistant that supports custom connectors, using the Northbeam MCP server URL.
[← Connect Northbeam to Your AI Assistant](/docs/northbeam-mcp)
Northbeam MCP is available on every Northbeam plan.
## Before you start
You will need:
1. A Northbeam account you can sign in to.
2. A subscription to the AI agent of your choice
3. The Northbeam MCP server URL: `https://mcp.northbeam.io`.
***
## General setup
Northbeam MCP can be used with any AI tool that supports custom connectors. Follow the instructions from your tool's' help center to add a custom connector.
Use the Northbeam server URL: `https://mcp.northbeam.io`
Follow the instructions to authenticate your Northbeam account.
***
## What you can ask
Once connected, your agent can pull live data from your Northbeam dashboards. Example prompts:
1. `List my Northbeam dashboards.`
2. `What was my Meta ROAS last week vs the prior week?`
3. `Show me my top 10 orders by revenue this month.`
4. `Break down spend and revenue by platform for the last 30 days.`
If you have access to more than one dashboard, tell the agent which one to use so it queries the right account.
# Connect Northbeam to ChatGPT
Source: https://docs.northbeam.io/docs/connect-northbeam-to-chatgpt
Connect Northbeam to ChatGPT so it can read your dashboards. Requires a paid ChatGPT plan.
[← Connect Northbeam to Your AI Assistant](/docs/northbeam-mcp)
Northbeam MCP is available on every Northbeam plan.
## Before you start
You will need:
1. A Northbeam account you can sign in to.
2. A ChatGPT paid subscription (\*\*Pro, Team, Enterprise \*\*or **EDU**).
3. The Northbeam MCP server URL: `https://mcp.northbeam.io`.
## If you’re on Team or Enterprise
If your ChatGPT access is managed by your organization, an Owner or Primary Owner may need to add the Northbeam connector first. After that, each user enables the connector and signs in individually.
If you’re on an individual plan, you can set up Northbeam yourself.
***
## Individual setup
Use these steps if you are on an individual ChatGPT plan and can add your own custom connectors.
1. Open \*\*ChatGPT \*\*and go to [`Settings>Plugins`](https://chatgpt.com/plugins#settings/Plugins).
2. Click on \*\*Developer Mode \*\*and **Enable Developer Mode.**
3. Go back to your home page and in the left hand nav, select **Plugins.**
4. In the top right hand corner, click the \*\*+ \*\*button to add a new plugin.
5. Enter:
1. **Name:** `Northbeam`
2. **URL:** `https://mcp.northbeam.io`
3. **Advanced settings**: leave blank
4. Check "**I understand and want to continue"**
6. Click **Create**.
7. When prompted, sign in with your normal Northbeam login.
8. Finish the connection flow. Once complete, the connector should show as connected.
9. (Optional) Choose your permissions to **Always ask, Allow read-only actions, Allow low-risk actions**, or \*\*Allow all actions \*\*.
## Verify the connection
Start a new chat and ask ChatGPT:
> Use Northbeam to list my dashboards.
If ChatGPT returns your dashboards, the connection is working.
***
## Team / Enterprise setup
If you are on a ChatGPT Team or Enterprise plan, setup happens in **two parts**:
1. A plan **Owner/Admin** adds the connector for the organization.
2. Each user enables the connector and signs in with their own Northbeam account.
## Part 1: Admin setup
Before any team member can use a custom MCP connector, the **workspace administrator** must authorize it:
1. Admin Controls: The workspace Owner or Admin must navigate to `Workspace Settings` > `Plugins`
2. Developer Mode Permissions: Admins can use Role-Based Access Control (RBAC) to enable `Developer Mode` for specific team members, or open it up workspace-wide.
3. Creating the Shared App: The admin (or authorized developer) clicks Create from the Workspace settings to build the app layout.
4. Enter:
* **Name:** `Northbeam`
* **URL:** `https://mcp.northbeam.io`
* Your organization's **OAuth** credentials
5. Save the connector.
After that, the connector becomes available to members of the organization, but it is **not connected for them automatically**.
## Part 2: Individual user setup
Once your admin has added Northbeam for the organization, you can connect your Northbeam login to ChatGPT.
1. Go to [`Settings>Plugins`](https://chatgpt.com/plugins#settings/Plugins).
2. Find **Northbeam** in the available connectors list.
3. Click on the app and authenticate using your enterprise credentials (typically via OAuth or an internal single sign-on token)
Each user must authenticate individually. Adding the connector at the org level only makes it available; it does not grant access by itself.
## Activating inside Workspace Features
On Team and Enterprise plans, you can utilize the connected MCP server beyond a standard chat window:
* [Shared Projects](https://openai.com/index/more-ways-to-work-with-your-team/): You can pin an MCP connector to a specific team Project workspace so all invited participants automatically query that data stream.
***
## What you can ask ChatGPT
Once connected, ChatGPT can pull live data from your Northbeam dashboards. Example prompts:
1. `List my Northbeam dashboards.`
2. `What was my Meta ROAS last week vs the prior week?`
3. `Show me my top 10 orders by revenue this month.`
4. `Break down spend and revenue by platform for the last 30 days.`
If you have access to more than one dashboard, tell ChatGPT which one to use so it queries the right account.
You can also click the \*\*+ \*\*on a new chat and select \*\*Northbeam \*\*to specifically query Northbeam.
# Connect Northbeam to Claude
Source: https://docs.northbeam.io/docs/connect-northbeam-to-claude
Use this guide to connect Northbeam to Claude on the web (claude.ai), Claude Desktop, or Claude Code.
Northbeam MCP is available on every Northbeam plan.
Once connected, Claude can use your Northbeam access to answer questions about performance, attribution, spend, orders, and dashboards. The connection is read-only. Claude can query and summarize your Northbeam data, but it cannot make changes in Northbeam.
The setup steps differ between Claude connectors and Claude Code, but the overall flow is the same:
1. Connect Northbeam to Claude.
2. Sign in with your Northbeam account.
3. Verify that Claude can access your dashboards.
## Before you start
You will need:
1. A Northbeam account you can sign in to.
2. Access to Claude custom connectors or Claude Code. Custom connectors using remote MCP are available in **Claude** and **Claude Desktop** across **Free, Pro, Max, Team, and Enterprise** plans.
3. The Northbeam MCP server URL: `https://mcp.northbeam.io`.
## If you’re on Team or Enterprise
If your Claude access is managed by your organization, an Owner or Primary Owner may need to add the Northbeam connector first. After that, each user enables the connector and signs in individually.
If you’re on an individual plan, you can set up Northbeam yourself.
***
## Individual setup
Use these steps if you are on an individual Claude plan and can add your own custom connectors.
#### Claude on the web (`claude.ai`) or Claude Desktop
1. Open **Claude** and go to **Customize → Connectors**.
2. Click the **+** button next to **Connectors**.
3. Enter:
* **Name:** `Northbeam`
* **URL:** `https://mcp.northbeam.io`
* **Advanced settings**: leave blank
4. Click **Add**.
5. When prompted, sign in with your normal Northbeam login.
6. Finish the connection flow. Once complete, the connector should show as connected.
7. (Optional) Choose **Always allow** for read-only tools.
#### Claude Code
1. Run this command in your terminal:
```text theme={null}
claude mcp add --scope user --transport http Northbeam https://mcp.northbeam.io
```
2. Open Claude Code.
3. Run `/mcp`.
4. Select Northbeam.
5. Choose Authenticate.
6. Complete the browser sign-in flow with your normal Northbeam login.
If you see `Failed to connect` immediately after adding the server, that is expected. The connection becomes active after you complete authentication.
### Verify the connection
Start a new chat and ask Claude:
> Use Northbeam to list my dashboards.
If Claude returns your dashboards, the connection is working.
***
## Team / Enterprise setup
If you are on a Claude Team or Enterprise plan, setup happens in **two parts**:
1. A plan **Owner/Admin** adds the connector for the organization.
2. Each user enables the connector and signs in with their own Northbeam account.
### Part 1: Admin setup
An organization **Owner** or **Admin** should:
1. Open Claude organization settings.
2. Go to **Organization settings → Connectors**.
3. Add a custom connector.
4. Enter:
* **Name:** `Northbeam`
* **URL:** `https://mcp.northbeam.io`
5. Save the connector.
After that, the connector becomes available to members of the organization, but it is **not connected for them automatically**.
### Part 2: Individual user setup
Once your admin has added Northbeam for the organization, you can connect your Northbeam login to Claude.
#### Claude on the web (`claude.ai`) or Claude Desktop
1. Open **Claude** or **Claude Desktop**.
2. Go to your **Connectors** settings.
3. Find **Northbeam** in the available connectors list and click **Connect**.
4. Sign in with **your own** Northbeam login.
5. Finish authentication.
Each user must authenticate individually. Adding the connector at the org level only makes it available; it does not grant access by itself.
#### Claude Code
1. Open Claude Code.
2. Run `/mcp`.
3. Select `claude.ai Northbeam` from the list. You may need to scroll down to see it.
4. Choose Authenticate.
5. Complete the browser sign-in flow with your normal Northbeam login.
### Verify the connection
Start a new chat and ask Claude:
> Use Northbeam to list my dashboards.
If Claude returns your dashboards, you are connected.
***
## What you can ask Claude
Once connected, Claude can pull live data from your Northbeam dashboards. Example prompts:
1. `List my Northbeam dashboards.`
2. `What was my Meta ROAS last week vs the prior week?`
3. `Show me my top 10 orders by revenue this month.`
4. `Break down spend and revenue by platform for the last 30 days.`
If you have access to more than one dashboard, tell Claude which one to use so it queries the right account.
# Creative Analytics
Source: https://docs.northbeam.io/docs/creative-analytics
An overview of creative ads.
## What is Creative Analytics?
Our Creative Analytics feature provides granular insights into creative performance, helping you manage, iterate, and scale your highest-performing campaigns.
This page offers a streamlined, cross-platform view of ad creative performance, making it easy to understand what is working and what is not.
By default, everything on the Creative Analytics page is based on **Accrual Performance** (Cash Snapshot is not supported), with:
* **Date range**: Last 7 Days
* **Attribution Mode**: Clicks + Modeled Views
* **Attribution Window**: 1-day click / 1-day view
***
## Creative Analytics Walkthrough Video
Below you will find a walkthrough of our Creative Analytics Page that dives into many areas, including:
* Saved Views/States
* Choosing Your Metrics
* Metrics are displayed on a sliding scale from Red (negative) to Green (positive)
* Analyzing Creative Cards
* Search for Specific Ads
* Hide Inactive Ads
Recommended settings for your view:
* Sort by *Spend* (top-down), which will show:
* Which ads are consuming the majority of the media budget?
* Which ads are driving the most impact?
* Key Metrics: CTR, CPM, ECR (1-day), CAC (1-day) or ROAS (This is the # Northbeam pull based on your data)
* ECR (e-commerce conversion rate): What is my conversion rate on this ad?
***
### Creative Analytics: Visual Coverage Notes
Creative Analytics is designed to help you understand **which creatives are driving performance**, across platforms and formats. In most cases, you will see both the creative card and its associated performance metrics.
Some ad formats, however, are **dynamically created at the time of delivery**. This means the exact creative a user sees can vary based on placement, audience, or product availability. Because there is no single “source of truth” creative in these cases, ad platforms may not provide a static preview that can be displayed.
When this happens, Northbeam will still show the **creative card and complete performance data**, even if a visual preview is unavailable.
#### Dynamic Creative
Creative previews are not supported for ad types where assets are **dynamically assembled at serve time**, rather than existing as a single, static creative. This includes any ads that mix, rotate, or generate creatives based on factors like placement, audience, product availability, or feed-based inputs.
Common examples include:
* **Meta Dynamic Product Ads (DPAs) and Dynamic Creative**
* **Ads using multiple headlines, descriptions, or images**
* **Feed-based or product-driven campaigns** (e.g., Google Demand Gen with product feeds)
* **Programmatic and fully dynamic formats**, such as AppLovin ads
Because these creatives are generated uniquely per impression, a single preview would not accurately represent what was shown to users. As a result, platforms may not expose static creative assets or may return incomplete or non-representative previews.
When this occurs, Northbeam will still display the **creative card and full performance data**, even if a visual preview is unavailable.
#### What to Keep in Mind
* **Performance data is always accurate and complete**, even when a visual preview is unavailable
* You will still see the creative card, spend, and downstream impact
* These behaviors are driven by **ad platform delivery models and API constraints**, not tracking gaps
* Creative Analytics uses **accrual performance by design** to ensure consistency across reporting
> **Bottom line:**\
> Creative Analytics is optimized to help you understand **what drives results**, not just how a single creative appears. When visuals are unavailable, the performance insights remain fully intact and actionable.
***
## Creative Analytics FAQ
**Which platform are available to view in Northbeam?**
* Northbeam's Creative Analytics tool is available for Facebook, Instagram, Snapchat, TikTok, Google, Pinterest, and YouTube.
**How do I use the Charts in Creative Analytics?**
* Charts allows you to compare the performance of multiple multiple ads as either a line graph or bar graph.
* All you have to do is:
1. Select up to 6 ads by clicking the checkbox labeled Show in charts
2. Pull up or double click the Charts at the bottom of the page, and you should be able to compare the selected ads with the key metric and additional metrics selected
**How do I share the Creative Analytics dashboard?**
* Open [Creative Analytics](https://dashboard.northbeam.io/creative-analytics), or click **Creative Analytics** in the left panel.
* On the top right of the page and click **Share** , which will copy a link of the exact dashboard view to your clipboard
Please Note
To open the copied dashboard link, the receiver will need to be a registered Northbeam user. Please follow [these steps](/docs/adding-or-removing-users-copy#adding-users) to add additional account managers.
## ✅ Onward
Northbeam's Creative Analytics feature gives you a focused, cross-platform view of how your creative ads are performing.
Now that you know what's capturing attention, it's time to dive into our Orders feature and understand the path to purchase.
# How Credit Is Assigned in Northbeam
Source: https://docs.northbeam.io/docs/credit-allocation-examples
## Overview
Every number you see in Northbeam is shaped by three levers working together:
| Lever | What it controls |
| - | - |
| **Accounting Mode** | *When* credit is assigned (e.g. at the time of touchpoint vs. time of order) |
| **Attribution Model** | *How* credit is split across touchpoints in a customer journey |
| **Attribution Window** | *How long* after a touchpoint a conversion can still earn credit |
Changing any one of these will change the numbers you see. The examples below walk through common scenarios to show how they interact.
***
## Quick Reference Glossary
| Term | Definition |
| - | - |
| **Attributed Revenue** | Revenue tied to a specific marketing touchpoint (used in Accrual mode) |
| **LTV** | Infinite attribution window — credit given for any purchase made after the touchpoint, regardless of time |
| **Transactions** | Purchases attributed to a touchpoint; can be fractional when credit is split across multiple touchpoints |
| **ROAS** | Return on Ad Spend = Attributed Revenue ÷ Spend |
| **CAC** | Customer Acquisition Cost = Spend ÷ Transactions |
| **Clicks-Only** | Attribution model that prioritizes credit to click-based upper funnel touchpoints |
| **Accrual** | Accounting mode that assigns credit at the time the touchpoint occurred |
| **Cash Snapshot** | Accounting mode that assigns credit at the time the purchase occurred |
| **First Touch** | All credit goes to the first touchpoint in the journey |
| **Last Touch** | All credit goes to the last touchpoint in the journey |
| **Linear** | Credit is split equally across all touchpoints |
| **Upper Funnel** | Paid Social, Paid Search (non-branded), Organic Social, Influencer, Display, etc. |
| **Lower Funnel** | Direct, Organic Search, Branded Search, Email, SMS |
| **Model Comparison Tool** | A Northbeam feature (Menu in top-right corner → Model Comparison) that displays multiple attribution models side by side for the same time period |
***
## Example 1: Revenue & ROAS
**Settings:**
* Time Period: Jan 1–31, 2024
* Attribution Model: Clicks-Only
* Attribution Window: 1 Day
* Accounting Mode: Accrual
| Platform | Spend | Attributed Rev (1d) | LTV Attributed Rev | ROAS (1d) | LTV ROAS |
| - | - | - | - | - | - |
| Facebook Ads | \$50 | \$75 | \$150 | 1.5 | 3.0 |
| Google Ads | \$50 | \$125 | \$175 | 2.5 | 3.5 |
| Email | \$0 | \$50 | \$75 | — | — |
### Spend
Spend is pulled directly from each ad platform via API. \$50 went to Facebook, \$50 to Google, and \$0 to Email (Email has no paid spend).
### Attributed Revenue (1d) vs. LTV Attributed Revenue
These two columns show the same revenue metric under two different attribution windows:
* **Attributed Rev (1d)** — only counts purchases made within **1 day** of the click
* **LTV Attributed Rev** — counts purchases made **at any point** after the click (infinite window)
Because this is a **Clicks-Only** model, credit flows only to click-based upper funnel touchpoints. Email retains a small amount of credit only when there was no other upper funnel touchpoint in the journey.
### ROAS (1d) vs. LTV ROAS
Both are calculated the same way — Revenue ÷ Spend — just using different attribution windows:
* **ROAS (1d)** = Attributed Rev (1d) ÷ Spend → Google: \$125 ÷ \$50 = **2.5**
* **LTV ROAS** = LTV Attributed Rev ÷ Spend → Google: \$175 ÷ \$50 = **3.5**
Use the 1d window for short-term optimization. Use LTV ROAS when evaluating channels that influence long-term buying behavior.
***
## Example 2: Transactions & CAC
**Settings:**
* Time Period: Jan 1–31, 2024
* Attribution Model: Clicks-Only
* Attribution Window: 3 Day
* Accounting Mode: Accrual
| Platform | Spend | Transactions (3d) | LTV Transactions | CAC (3d) | LTV CAC |
| - | - | - | - | - | - |
| Facebook Ads | \$50 | 2.20 | 5.67 | \$22.73 | \$8.82 |
| Google Ads | \$50 | 6.25 | 10.81 | \$8.00 | \$4.63 |
| Email | \$0 | 2.02 | 3.59 | — | — |
### Why Are Transactions Fractional?
In Accrual mode, credit is divided between all touchpoints in a customer journey — so a single purchase might give 0.6 credit to Facebook and 0.4 to Google. This is why you see decimals like 2.20 instead of whole numbers.
### Transactions (3d) vs. LTV Transactions
* **Transactions (3d)** — counts purchases made within **3 days** of the click
* **LTV Transactions** — counts purchases made **at any point** after the click
Example: A click on Jan 1 that converts on Jan 31 (30 days later) would appear in LTV Transactions but not in Transactions (3d).
### CAC (3d) vs. LTV CAC
CAC = Spend ÷ Transactions. Lower is better.
* **CAC (3d)** = Spend ÷ Transactions (3d) → Facebook: \$50 ÷ 2.20 = **\$22.73**
* **LTV CAC** = Spend ÷ LTV Transactions → Facebook: \$50 ÷ 5.67 = **\$8.82**
LTV CAC will almost always be lower because more purchases are counted in the denominator. Use LTV CAC when evaluating channels that influence repeat purchases or have longer consideration cycles.
***
## Example 3: How Attribution Models Affect Credit
This example shows how choosing a different Attribution Model changes who gets credit — even when everything else stays the same.
**Settings:**
* Time Period: Jan 1–31, 2024
* Attribution Window: 7 Day
* Accounting Mode: Accrual
**Journey:** A customer sees and clicks three ads before making a \$90 purchase.
1. Jan 1 — Facebook Ad click
2. Jan 3 — TikTok Ad click
3. Jan 5 — Google Branded Search click → \$90 purchase
| Platform | First Touch | Last Touch | Linear | Clicks-Only |
| - | - | - | - | - |
| Facebook Ads | \$90 | \$0 | \$30 | \$45 |
| TikTok Ads | \$0 | \$0 | \$30 | \$45 |
| Google Branded Search | \$0 | \$90 | \$30 | \$0 |
**Note:** The Sales page only displays one Attribution Model at a time, so you cannot replicate this table directly in your dashboard.
To compare models against each other, open [Model Comparison](https://dashboard.northbeam.io/model-comparison). This tool is purpose-built for seeing how different models interpret the same data without having to toggle back and forth manually.
### What is happening here?
* **First Touch** gives all \$90 to Facebook — the first touchpoint in the journey
* **Last Touch** gives all \$90 to Google Branded Search — the final touchpoint before purchase
* **Linear** splits credit equally: \$30 to each of the three touchpoints
* **Clicks-Only** gives \$45 each to Facebook and TikTok, and \$0 to Google Branded Search — because Branded Search is a lower funnel channel and receives no credit when upper funnel touchpoints exist in the journey
### Why does this matter?
If you were optimizing off Last Touch, you would conclude Google Branded Search is your best performer and potentially over-invest there. But Branded Search is largely capturing intent that was created upstream by Facebook and TikTok. Clicks-Only surfaces where that intent actually came from.
This is also why the Model Comparison Tool is useful in practice — rather than switching models manually and trying to remember the numbers, you can see the delta across models in one view and make more informed budget decisions.
**Recommended model for day-to-day decisions:** Clicks-Only. It is conservative, upper-funnel focused, and directionally accurate for media buying decisions. Use the Model Comparison Tool to sanity check your Clicks-Only numbers against other models when needed.
**Want to understand how C+DV assigns credit across clicks and views?**
See [Clicks + Deterministic Views](/docs/clicks-deterministic-views) for a full breakdown including worked examples.
***
## Example 4: How Accounting Mode Affects Credit (Accrual vs. Cash)
This example shows how switching Accounting Mode changes *when* credit is assigned — which can significantly affect how a given day or week looks in your dashboard.
**Settings:**
* Attribution Model: Clicks-Only
* Attribution Window: 7 Day
**Journey:**
1. Jan 1 — Facebook Ad click
2. Jan 5 — Purchase for \$90
### Accrual Mode
In Accrual, credit is assigned to the date the **touchpoint occurred**.
| Date | Platform | Attributed Rev (7d) |
| - | - | - |
| Jan 1 | Facebook Ads | \$90 |
| Jan 5 | Purchase date — no new touchpoint | \$0 |
Facebook receives \$90 on Jan 1 — the day the click happened — because the purchase occurred within the 7-day window.
### Cash Snapshot Mode
In Cash Snapshot, credit is assigned to the date the **purchase occurred**, regardless of when the touchpoint happened.
| Date | Platform | Revenue |
| - | - | - |
| Jan 1 | Facebook Ads | \$0 |
| Jan 5 | Facebook Ads | \$90 |
Facebook receives \$90 on Jan 5 — the day of the purchase — not the day of the click.
### What is the practical difference?
| | Accrual | Cash Snapshot |
| - | - | - |
| Credit assigned on | Touchpoint date | Purchase date |
| Attribution windows available? | Yes | No |
| Best for | Day-to-day media buying, channel optimization | Reconciling against Shopify revenue, finance reporting |
| Matches Shopify closely? | Not directly | Yes |
**Important:** Attribution Windows are only available in Accrual mode. If you switch to Cash Snapshot, all window options are removed and revenue is reported on the day it was collected regardless of when the touchpoint occurred.
**When to use each:** Use Accrual for media buying decisions. Use Cash Snapshot when you need your numbers to tie back to actual revenue collected — for example, when reconciling with your finance team or Shopify dashboard.
***
## Key Takeaways
1. **Three levers, one number** — Accounting Mode, Attribution Model, and Attribution Window all affect your metrics simultaneously. Always check which settings are active before drawing conclusions.
2. **Fractional transactions are normal** — they reflect credit being shared across touchpoints, not a data error.
3. **Short window vs. LTV** — short windows (1d, 3d) are better for optimizing recent performance; LTV is better for understanding full customer value.
4. **Email deprioritization is intentional** — in Clicks-Only mode, Northbeam pulls credit away from Email to surface the true impact of paid upper funnel channels.
5. **Accrual vs. Cash Snapshot** — use Accrual for media buying decisions and Cash Snapshot when reconciling with Shopify or finance reporting.
6. **No single model tells the whole story** — use the Model Comparison Tool (Menu in top-right corner → Model Comparison) to see how different models interpret the same data before making budget decisions.
***
*For deeper dives, see:*
* [Attribution Models](/docs/attribution-models)
* [Attribution Windows](/docs/attribution-windows)
* [Accounting Modes](/docs/accounting-modes)
# Currency
Source: https://docs.northbeam.io/docs/currency
Select reporting currency
* The default reporting currency is USD(\$)
* The spend data is normalized into a single currency even if you use different currencies in your ad accounts.
Reporting in USD?
You're all set.
Reporting in a foreign currency?
This requires an additional step for our team to configure. Please [submit a support ticket](https://www.northbeam.io/submit-a-support-ticket) for assistance.
# Dashboard and Export Data Don't Match
Source: https://docs.northbeam.io/docs/dashboard-and-export-data-dont-match
Reconcile CSV, scheduled, GCS, and Data Export API results with the Northbeam dashboard.
An export only matches the dashboard when both requests use the same settings and data state.
## 1. Identify the export
Record whether you are comparing a:
* One-time CSV export
* Scheduled export
* Google Cloud Storage export
* Data Export API response
Also record when the export was generated.
## 2. Match every setting
Confirm that the export and dashboard use the same:
* Account
* Date range and timezone
* Metrics
* Attribution model and window
* Accounting mode
* Filters and breakdown level
* Granularity, such as daily, weekly, or monthly
For the Data Export API, compare the request parameters directly with the dashboard settings.
## 3. Compare the same data state
Recent data can change as new orders, spend, and attribution inputs are processed. Regenerate the export before comparing it with the current dashboard.
## 4. Check export-specific options
Options such as aggregated data, zero-value row removal, chart values versus table values, and included breakdowns can change the result.
Review [Exporting Data](/docs/exporting-data) for the available export methods and settings. You can also open [Sales](https://dashboard.northbeam.io/sales), [Documents](https://dashboard.northbeam.io/customers/documents), or [Manage Exports](https://dashboard.northbeam.io/settings/manage-exports).
If the discrepancy remains, provide Support with the export file, generation time, request parameters, dashboard URL, and screenshots of both totals.
# What’s the difference between Blotout and Northbeam—and do I need both?
Source: https://docs.northbeam.io/docs/difference-between-blotout-and-northbeam-do-i-need-both
Understanding How Northbeam and Blotout Work Together.
## TL;DR
* Blotout focuses on event enrichment, like only sending more events/signals back to platforms like Meta.
* Northbeam captures, attributes, and ties conversions to actual revenue as well as feeds attributed back into platforms for real-time optimization.
* **Northbeam includes all the event tracking capabilities that Blotout offers**, including first-party pixel tracking, server-side data capture.
We’ve recently received a few questions about how Blotout compares to Northbeam. We wanted to provide clarity to help you better understand the differences and how these tools can complement each other.
## Here are the Key Differences
| Blotout | Northbeam |
| :- | :- |
| Focused on **capturing event data** (like page views, clicks, and purchases). | Focused on **attributing revenue back to ad spend**. |
| Increases **signal on platform-reported data only**. | Captures event data and sends enriched **attributed data back to Meta via Apex**, combining both signal enhancement and holistic performance modeling. |
| Put event data into systems like **GA4 or data warehouses**. | Matches marketing touchpoints to **actual revenue (e.g., Shopify, Amazon, ERP)**. |
## Event Capture vs. Attribution
Blotout helps businesses capture more events, especially in cases where:
* First-party pixel tracking is not set up
* Server-side tracking is needed to improve the event
However, **capturing events alone doesn’t equal better attribution**.
**Blotout does not:**
* Have first-party pixel tracking
* Perform multi-touch or view-through attribution modeling
* Use probabilistic models to fill in gaps
* Reconcile conversions back to actual revenue sources
* Provide campaign, ad set, or creative-level insights
* Support Shopify S2S or Custom API Integrations
In conclusion, **Northbeam can perform all of the above, capture the data to model it accurately**, helping you make smarter, more profitable marketing decisions.
## Why does this matter?
If you're already using Northbeam's first-party pixel tracking and server-side integrations, you are capturing reliable event data.
Northbeam’s attribution models (Clicks-Only, Clicks + Modeled Views, Clicks + Deterministic Views) go much further by distributing revenue credit fairly across all touchpoints and campaigns, not just reporting raw clicks or events.
Tools like Blotout or Elevar can enhance your event capture stack, but they don't replace what Northbeam does for attribution and business insights.
## Other Questions
**We’re using Northbeam—would adding Blotout help with tracking things that Northbeam might miss?**
* All event enrichment tracking that Blotout covers, Northbeam also covers in its tracking by default.
**Is there tracking data that Blotout captures but Northbeam doesn't?**
* No. Northbeam supports first-party pixel tracking, server-side tracking (like Shopify S2S), and custom API integrations, all of which ensure reliable data capture.
* Northbeam also performs full attribution modeling, ties conversions to actual revenue, and can feed clean, attributed conversion data back into platforms like Meta via our Apex integration. This means that we are not only capturing data, but also optimizing your campaigns in real-time.
**Have Other Questions?** If you have more specific questions about your tracking setup, you can reach out to your Media Strategist, Customer Success Manager, or submit a [Support](https://www.northbeam.io/submit-a-support-ticket) ticket. We’re happy to walk you through it!
# Differences in Ad Performance
Source: https://docs.northbeam.io/docs/differences-ad-performance
It's very common to see a difference in ad performance within Northbeam. In fact, this is 100% expected and happens more often than not. Read this article to learn why.
**This guide will answer the following question:**
* Why is my \[platform] \[metric] in Northbeam much lower/higher than in-platform?
**Examples:** “My Facebook ROAS in Northbeam is 0.8, but Facebook Ads Manager is reporting a 2.1" “My Google CAC in Northbeam is \$60, but Google Ads Manager is reporting \$25" “My Pinterest ROAS in Northbeam is 0.5, but Pinterest Ads Manager is reporting a 1.7"
**Ad performance discrepancies are expected. This boils down to 3 core principles:**
1. [**Attribution Model**](/docs/attribution-models)
2. [**Attribution Window**](/docs/attribution-windows)
3. **Customer Journey**
## Key Takeaways
* Northbeam’s **attribution model** and **attribution window** are different from legacy models that platforms use. This creates a difference in credit allocation and performance across your campaigns.
* Northbeam recognizes touchpoints from all channels within the **customer journey,** whereas in-platform does not. That said, even if you're using the same attribution model and window, a difference in credit allocation and performance is expected.
If there are discrepancies between in-platform and Northbeam in regards to a specific campaign or channel, this is **expected**.
Our approach to weighting credit is different from how in-platform metrics traditionally weigh credit. In short, this boils down to differences between our Multi-Touch Attribution (MTA) model and in-platform traditional models. Our MTA divides credit between touchpoints, whereas in-platform models tend to give full credit to a single touchpoint (usually on a last-touch basis).
## Example
Let's say somebody placed an order for \$100. Below is their customer journey:
* User clicks on FB Campaign called "Prospecting"
* User clicks on FB Campaign called "Retargeting"
* User clicks on Klaviyo Email
* User clicks on Branded Search ad and purchases
See the credit allocation for each touchpoint across a few different attribution models.
| | Clicks-Only (Northbeam's model) | Last Touch (Northbeam's model) | Last Touch (Facebook's model) |
| :- | :- | :- | :- |
| FB "Prospecting" | \$50 | \$0 | \$0 |
| FB "Retargeting" | \$50 | \$0 | \$100 |
| Klaviyo Email | \$0 | \$0 | \$0 |
| Branded Search | \$0 | \$100 | \$0 |
Here are the biggest differences:
* Our MTA models (Clicks-Only and Clicks + Modeled Views) divide credit among all touchpoints
* The Northbeam Pixel recognizes touchpoints across the full journey (from all channels) - hence the difference in Last Touch
Other differences that aren't depicted above are:
* Attribution Windows
* Accounting Modes
All of these create differences in performance when comparing Northbeam to legacy platform reporting. We believe this is a more accurate way to make media buying decisions.
**See the article below for more information and scenarios. The article speaks specifically to Facebook, but the concept can be applied to all platforms.**
[“What are the differences between Northbeam and in-platform reporting”](/docs/what-is-northbeam#why-do-my-in-platform-metrics-look-different-from-northbeam)
## Need additional help?
If you need further assistance, reach out to [Support](https://www.northbeam.io/submit-a-support-ticket)!
# Spend or Impressions Are Missing
Source: https://docs.northbeam.io/docs/differences-in-ad-data
Diagnose missing or incorrect ad-platform and custom spend data.
First identify how Northbeam receives data for the affected platform: an API connection, a scheduled report, or custom spend.
## API-connected platforms
Open [Connections](https://dashboard.northbeam.io/settings/connections), then confirm:
1. The connection has no errors.
2. The correct ad account is selected.
3. The connected user still has permission to access that account.
4. The affected campaign exists in the selected account and date range.
If spend is present but visits or revenue are missing, the connection may be working. Troubleshoot the ad URL and tracking separately using [Data Appears as Organic, Other, or Unattributed](/docs/differences-in-unattributed-data).
## Scheduled reports
Confirm that the report:
* Is still running on schedule
* Contains the required fields
* Covers the affected dates and accounts
* Is being delivered to the configured destination
Then follow the setup guide for that platform.
## Custom spend
Open [Data Spreadsheets](https://dashboard.northbeam.io/settings/data-spreadsheets), then confirm:
* The correct spreadsheet is connected.
* The affected dates contain valid rows.
* Platform and ad-key values match the intended campaigns.
* The same spend was not submitted through another source.
## If totals differ slightly
Compare the Northbeam account timezone in [Profile](https://dashboard.northbeam.io/settings/profile) with the ad platform's timezone. Spend near midnight can fall on different dates.
When contacting Support, provide the platform, account ID, campaign ID, affected dates, and a screenshot of the platform total.
# Data Appears as Organic, Other, or Unattributed
Source: https://docs.northbeam.io/docs/differences-in-unattributed-data
Understand why Northbeam cannot assign traffic or revenue to the expected paid source.
These labels describe different problems. Identify the label first, then follow the matching checks.
| Label | What it usually means |
| :- | :- |
| **Organic** | Northbeam did not detect a paid-media signal for the visit. |
| **Other** | Northbeam detected source information but could not map it to the expected channel or campaign. |
| **Unattributed** | Northbeam received the server-side conversion but could not match it to the required pixel data. |
## Traffic appears as Organic or Other
1. Open the [UTM Guide](https://dashboard.northbeam.io/settings/utm-guide) and compare its parameters with the affected ad's final URL.
2. Follow the URL through every redirect and confirm that its UTMs and click IDs remain present.
3. Open [Connections](https://dashboard.northbeam.io/settings/connections) and confirm that the correct ad account is connected without errors.
4. Check whether the issue affects one campaign naming pattern, ad platform, domain, or redirect flow.
For platforms not listed in the UTM Guide, follow [Tracking for Other Platforms](/docs/tracking-for-other-platforms).
## Orders appear as Unattributed
Open [Orders](https://dashboard.northbeam.io/orders) and inspect an example order.
* If **Attributed** is no, check `firePurchaseEvent` and the order ID.
* If the order was placed through an offline, recurring, marketplace, or other non-web flow, missing pixel data may be expected.
* If an online checkout order should be pixel-tracked, continue to [Troubleshooting Pixel Tracking](/docs/guide-to-troubleshooting-pixel-tracking).
Do not exclude unexpected unattributed orders. First confirm why the pixel data is missing.
# Visits Are Missing or Lower Than Expected
Source: https://docs.northbeam.io/docs/differences-in-visits
Diagnose missing visits, page views, and sudden changes in tracking coverage.
Use this guide when visits or page views are missing, lower than expected, or dropped after a website change.
## 1. Identify the scope
Determine whether the issue affects:
* Every page or only specific landing pages
* Every visitor or a particular browser, device, or region
* All traffic or one campaign or channel
* A specific date when a site, domain, checkout, or consent change occurred
## 2. Check the affected pages
Confirm that the [Northbeam Pixel](/docs/add-pixel) loads on every affected page, including:
* Alternate landing pages
* A/B test variants
* Subdomains and newly launched domains
* Product and checkout pages
Open [Pixel and Event Tracking](https://dashboard.northbeam.io/settings/tracking-script-tags) to review your setup.
## 3. Test the complete landing URL
Open an affected ad's final URL and confirm that:
* It lands on the expected tracked domain.
* Northbeam and UTM parameters remain after every redirect.
* The parameters are not removed when the visitor moves to another required domain.
Use the account-specific parameters shown in the [UTM Guide](https://dashboard.northbeam.io/settings/utm-guide).
## 4. Review recent changes
Check whether the drop began after changes to your:
* Website theme or tag manager
* Cookie-consent flow
* Domain, subdomain, or DNS
* Landing-page builder
* Checkout or payment flow
## Understand the comparison
A Northbeam **Visit** is not the same as an ad-platform click or an individual page view. A visit generally represents a session, which ends after 30 minutes of inactivity. Northbeam also filters bots and may load at a different point than another analytics tool.
If the pixel works on some pages but not others, fix page coverage before comparing totals. For order-level tracking, continue to [Troubleshooting Pixel Tracking](/docs/guide-to-troubleshooting-pixel-tracking).
# Email/SMS/Retention Team
Source: https://docs.northbeam.io/docs/email-sms-retention
Below is a video walkthrough that details how Email, SMS, and Retention Teams can effectively use Northbeam to evaluate their impact and make decisions around lifecycle marketing.
Please note:
* It is important for Retention Teams to understand this logic as it is materially different than the rest (Email/SMS).
* Clicks-Only & Clicks + Modeled Views may discredit Email/SMS.
# Walkthrough Video
Recommended Dashboard Settings:
* **Attribution Model**:
* Last Non-Direct Touch, *if you are comparing performance (also for decision-making as it gives the most credit to decision-making*, OR
* Clicks-Only, *if you are trying to see an email's independent impact when it is not tied to Paid Campaigns*
* **Attribution Window**: 1 Day
* **Accounting Mode**: Accrual Accounting
* **Filter by**: Email, SMS
* **Granularity**: Daily
* **Time Period**: 7 Days
* **Time Comparison**: Previous Period
* **Breakdown By**: Category and your designated [Labels](/docs/manage-breakdowns), specifically for Email & SMS.
You can use the [Model Comparison feature](https://dashboard.northbeam.io/model-comparison) to compare 2 Attribution Models: Last Non-Direct Touch and Clicks-Only.
* **Granularity**: Campaign
* **Breakdown By**: Email, SMS
**Northbeam's** models are designed to **de-weight lower-funnel channels** (like Email and SMS) in favor of top-funnel touchpoints when appropriate.
By comparing these two models, you can see how much credit stays with Email/SMS and how much is reattributed to Paid Channels.
This information helps Retention Teams understand where their efforts are directly converting versus assisting Paid.
You can learn more about [Northbeam's Model Comparison here](/docs/what-is-northbeam-model-comparison-tool).
### TL;DR
**Here are a few key metrics you can use to identify which flows or campaigns are working better so you can lean into those**:
* Revenue Per Visit
* New Customer vs. Returning Customer Traffic
* New Order vs. Returning Order/ Revenue
* E-commerce Conversion Rate (ECR)
**Which Dashboard is the best suited to look at this data:**
* Most Retention Teams will spend time on the All Sales page to monitor campaign-level performance.
* For deeper questions (Ex: Paid vs. Lifecycle relationships), explore features like Customer Paths or Customer LTV to conduct your analysis.
**When to use Custom Labels to Distinguish Campaigns from Flows:**
* For cleaner reporting, set up UTM rules to segment Email/SMS traffic into Campaigns vs. Flows
* Review and refine this [Label](/docs/manage-breakdowns) by regularly ensuring accurate grouping.
We recommend that you create and save a custom "Email/SMS View" for yourself so you can always refer back to this data. **While you won't have Spend data, tracking Clicks and Revenue from Flows and Campaigns is insightful to understanding lifecycle performance**.
Please reach out to your Media Strategist, Customer Success Manager, or contact [Support](https://www.northbeam.io/submit-a-support-ticket) if you have any questions.
# Environments
Source: https://docs.northbeam.io/docs/environments
Production and UAT base URLs, and what each one is for
Northbeam's APIs are served from two environments:
| Environment | Base URL | Use it for |
| :- | :- | :- |
| Production | `https://api.northbeam.io/v2` | Live data. Orders sent here are used for attribution (MTA) and predictive analytics (MMM). |
| UAT | `https://api-uat.northbeam.io/v2` | Customer testing only. Production-equivalent, but orders submitted here are **not** used in attribution. |
## Start in UAT
Use the UAT environment to test your integration end to end before
pointing it at production — same endpoints, same
[authentication](/docs/authentication), no effect on your live
attribution data.
## Switching to production
When your integration works in UAT, change the base URL to
`https://api.northbeam.io/v2`. Everything else stays the same.
The [API reference](/reference/post_orders-1) lets you call either
environment directly from the docs — insert your API keys and use the
example values to try a request.
# Errors
Source: https://docs.northbeam.io/docs/errors
Northbeam uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with Northbeam’s servers. We suggest gracefully handling errors that may be returned by Northbeam.
## Status codes
| Code | Meaning | What it usually means |
| - | - | - |
| `200` | OK | The request succeeded. |
| `400` | Bad Request | Malformed JSON or an invalid value. Check the payload structure. |
| `401` | Unauthorized | Missing or invalid API key / `Data-Client-ID` header. |
| `403` | Forbidden | The credentials are valid but not permitted for this resource. |
| `404` | Not Found | The endpoint or resource does not exist. Check the URL. |
| `429` | Too Many Requests | You have exceeded the rate limit. Retry after a short backoff. |
| `500` | Server Error | An error on Northbeam’s side. Retry later; contact support if it persists. |
## Attributes
**status**: *string*\
The error code.
**response**: *json-encoded string or string*\
For some known or common errors, we will return a json-encoded string that represents an array of objects with an “order\_id”, human readable “message”, and the “json\_path” of the failing attributes. For other errors, we may simple return an error string in a human readable format.
## Common errors
* A 400 "Bad Request" error with no additional error message is normally due to JSON being malformed. Please ensure that you are sending properly formed JSON blobs.
# Executive Team
Source: https://docs.northbeam.io/docs/executive-team
This guide is especially useful for CMOs, CFOs, and CEOs.
Below is a walkthrough video about our best practices for Executives.
# Walkthrough Video
### TL;DR
1. Use **Cash snapshot accounting mode** for high-level monitoring:
1. Cash snapshot views are most aligned with financial reporting (cash in, cash out), making them ideal for comparing against historical or internal financial reports.
2. Customize your Dashboard tiles with **key metrics to match your business KPIs**:
1. Spend
2. Revenue
3. First-Time Revenue
4. Revenue per Visit
5. New Customer Orders Volume
6. New Customer Order Percentage
7. Average Order Value (AOV)
8. Cost to Acquire a New Customer (CAC)
9. Conversion Rate (CVR)
10. Media Efficiency Ratio (MER)
3. **Mirror Views** across your **Overview Home Page** and your **All Sales Page**
1. The All Sales Page is helpful to view platform, funnel stage, or paid versus owned channels.
4. **Track trends and export data** regularly to share internally
1. Monitor performance daily, weekly, or monthly.
Aim to build and save views that reflect your core company KPIs. Check them regularly and use them to drive decisions without having to dive into every campaign detail.
Please reach out to your Paid Media Strategist, Customer Success Manager, or [support@northbeam.io](mailto:support@northbeam.io) if you have any questions.
# Which export should I use?
Source: https://docs.northbeam.io/docs/exporting-data
Northbeam offers four ways to get your data out: a Sales page export, the Touchpoints Export, the Data Export API, and the Northbeam MCP server.
Northbeam offers several ways to export or access your data. The right option depends on the dataset you need, where you want it delivered, and whether you want a file, an automated pipeline, or an answer from an AI tool.
## Compare your options
| Option | Data | Delivery | Best for | Availability |
| :- | :- | :- | :- | :- |
| **[Sales page export](/docs/sales-page-export)** | Performance data from the chart or table on the Sales page | CSV download or Google Cloud Storage (GCS) | One-time analysis and recurring reports, without code | Available in the dashboard |
| **[Touchpoints Export](/docs/touchpoints-export)** | Row-level marketing touchpoints, attribution credit, order and customer identifiers, campaign metadata | CSV files delivered to GCS or Amazon S3 | Customer journey analysis, warehouse and BI workflows | Select service plans |
| **[Data Export API](/docs/northbeam-api-data-export-1)** | Performance metrics with configurable attribution models, windows, accounting modes, levels, breakdowns | Temporary download link, GCS, or Amazon S3 | Automated data pipelines and custom reporting | Requires an API key |
| **[Northbeam MCP server](/docs/northbeam-mcp)** | Live dashboard metrics, attribution data, spend, orders, and product-level attribution when enabled | Responses inside a connected AI tool | Asking questions without building an export | All plans |
## How to choose
* **You need a spreadsheet.** Use the **Sales page export**. It covers most one-off analysis and can be scheduled daily, weekly, or monthly without any engineering work.
* **You need the individual touchpoints behind each order**, not aggregated performance. Use the **Touchpoints Export**. This is the only option that returns one row per touchpoint with its attribution credit.
* **You are building a pipeline.** Use the **Data Export API**, which lets you set the attribution model, window, accounting mode, level, and breakdowns per request.
* **You want to ask a question rather than move a file.** Use the **Northbeam MCP server**.
**MCP provides data access, not bulk export**
The Northbeam MCP server is read-only and retrieves a limited set of data in response to a specific question. It does not sync or bulk-export your data. Use a Sales page export, the Touchpoints Export, or the Data Export API when you need a file or a data pipeline.
***
## FAQs
### How can I receive CSV file exports attached to emails?
Currently, scheduled exports provide a link to your dashboard for file downloads. Our Product team is aware of the request to attach files directly to emails, but there is no timeline for this feature at the moment.
### How can I get Northbeam data into Google Sheets?
There is no built-in Google Sheets export. If you have development resources available, there are three approaches:
* Use [Google Apps Script](https://developers.google.com/apps-script) with the [Data Export API](/docs/northbeam-api-data-export-1) to write data into Sheets.
* Export to GCS, then use the GCS connector in Sheets ([Google's documentation](https://support.google.com/docs/answer/9702507?hl=en)).
* Export a CSV and import it into Google Sheets.
We cannot provide further guidance on setting this up. Please consult your development team or refer to the documentation linked above.
### How can I get Northbeam data into BigQuery?
Export the data into a custom Google Cloud Storage bucket — from either the Sales page or the API — then load it from GCS into BigQuery ([Google's documentation](https://cloud.google.com/bigquery/docs/loading-data-cloud-storage-csv)).
We cannot provide further guidance on setting this up. Please consult your development team or refer to the documentation linked above.
### How can I get Northbeam data into Snowflake?
Land the files in GCS or Amazon S3 using the [Touchpoints Export](/docs/touchpoints-export) or the [Data Export API](/docs/northbeam-api-data-export-1), then move them through your existing data pipeline.
# UTMs for Legacy Platforms
Source: https://docs.northbeam.io/docs/facebook-utms-for-legacy-platforms
These supported formats are now part of the main Meta setup guide. See [Using Supported Parameters From Another Attribution Platform](/docs/channels/meta/overview#using-supported-parameters-from-another-attribution-platform) for the full Meta tracking setup.
## **Using Legacy Facebook UTMs with Northbeam**
Northbeam can ingest UTMs from other tracking tools like **Triple Whale, Hyros, Rockerbox, and Wicked Reports**. If your ads are already using UTMs from these platforms, you **may not need to implement Northbeam's UTMs**, so you can avoid editing active ads.
### **🚨 Important: UTM Keys & Values Must Match Exactly**
Ensure that the **UTM keys and values** match precisely, including capitalization, for Northbeam to recognize and track them properly.
### **Supported Legacy UTMs by Platform**
Tool
Legacy UTMs
Triple Whale
**One (1) of the following source parameters + values is required:**
tw\_source=\{\{site\_source\_name}}\
tw\_source=facebook\
utm\_source=facebook\
utm\_source=\{\{site\_source\_name}}
**One (1) of the following adid parameters + values is required:**
tw\_adid=\{\{ad.id}}\
fbadid=\{\{ad.id}}
**Examples UTMs that are acceptable:**
* tw\_source=facebook\&tw\_adid=\{\{ad.id}}
* tw\_source=\{\{site\_source\_name}}\&fbadid=\{\{ad.id}}
* utm\_source=\{\{site\_source\_name}}\&tw\_adid=\{\{ad.id}}
* utm\_source=facebook\&fbadid=\{\{ad.id}}
By using these existing UTMs, you can streamline your transition to Northbeam tracking. If your parameters don't match a format above exactly, add the [Northbeam UTM Parameters](/docs/channels/meta/overview#northbeam-utm-parameters) instead.
# ❓Frequently Asked Questions
Source: https://docs.northbeam.io/docs/frequently-asked-questions
Here are quick and clear answers to help you navigate Northbeam.
This FAQ section helps quickly answer the most asked questions that users have when getting started with Northbeam.
## Find where to go when you have specific questions
| Day-to-Day FAQs | Feature to Use/ReadMe Link |
| :- | :- |
| "How can I inspect a single customer's journey?" | [Orders](/docs/orders-tracking) |
| "How do I look at long-term trend lines across a handful of KPIs?" | [Metric Explorer](/docs/metrics-explorer) |
| "We ran a test where we didn't expect to see any direct click performance, how can I analyze that in Northbeam?" | [Metric Explorer](/docs/metrics-explorer) |
| "Where can I create Northbeam channel targets?" | [Profitability Benchmarks](/docs/profitability-benchmarks) |
| "I have naming conventions in my ads - where can I create segments to view those aggregated?" | [Manage Breakdowns](/docs/manage-breakdowns) |
Advanced FAQs
Feature to use/Dashboard
Link
"How do I do a quarterly customer retention analysis?"
## Other questions you may have
##### [What is Northbeam MTA Methodology?](/docs/what-is-northbeam-mta-methodology)
##### [Why is the Northbeam's Methodology better than our internal one?](/docs/what-is-northbeam-mta-methodology)
##### [How does Northbeam track Orders and Ads?](/docs/how-does-northbeam-track-orders-and-ads)
##### [What is a good/bad number in Northbeam?](/docs/what-is-a-good-bad-number-in-northbeam)
##### [What is Northbeam's Model Comparison Tool?](/docs/what-is-northbeam-model-comparison-tool)
##### [Case scenario: Cash snapshot and Accrual performance](/docs/case-scenario-cash-vs-accrual)
* Is there a normal/ standard delta between them?
##### [Case scenario: Clicks+Modeled Views vs Clicks-Only](/docs/case-scenario-clicks-views-vs-clicks-only)
* Why are my numbers good on Clicks + Modeled Views but bad only Clicks-Only?
* Is there a normal/delta between them?
##### [My FB ROAS is 0.7 in Northbeam, is this normal?](/docs/why-is-my-fb-roas-so-much-lower-in-northbeam)
##### [Why is my FB ROAS so much lower in Northbeam?](/docs/why-is-my-fb-roas-so-much-lower-in-northbeam)
##### [How do I correctly and confidently interpret non-click channels?](/docs/how-do-i-correctly-confidently-interpret-non-click-channels)
##### [Why is so much of my revenue "unattributed"?](/docs/differences-in-unattributed-data)
##### [What's the difference between Organic vs Unattributed?](/docs/whats-the-difference-between-organic-vs-unattributed)
## Questions about Other Platforms
##### [What’s the difference between Blotout and Northbeam—and do I need both?](/docs/difference-between-blotout-and-northbeam-do-i-need-both)
## Need Help?
Please reach out to [Support](https://www.northbeam.io/submit-a-support-ticket) if you have any other questions or requests.
# Gclid, Fbclid, and Redirects
Source: https://docs.northbeam.io/docs/gclid-fbclid-redirects
You might see 'gclid' and 'fbclid' in your Northbeam dashboard in the Campaign Level of the Sales Page. This article will answer the following questions:
* What are they?
* What do they represent in Northbeam?
* Are they an issue?
| Query Parameter | What is it? | Where is it inserted? | Example |
| :- | :- | :- | :- |
| fbclid | Facebook's Click Identifier | Facebook's Organic and Ad URLs | `https://example.com?fbclid=IwAR3GH5ksVhoRLwxyz…` |
| gclid | Google's Click Identifier | Google's Ad URLs | `https://example.com?gclid=EAIaIQobChMI3` |
***
## fbclid (Facebook’s Click Identifier)
### What is “fbclid”?
The "fbclid" parameter is added to the URL whenever a user clicks on a link from a **paid ad** or **organic post** from Facebook. This parameter allows Facebook to track ad performance and user behavior after they leave the platform.
Example: `https://example.com?fbclid=IwAR3GH5ksVhoRLwxyz…`
### Why do I see “fbclid” in my Northbeam dashboard?
In Northbeam, **"fbclid" represents users who visited your site with only the "fbclid" parameter and no additional UTM parameters.** By default, this traffic is classified as "Facebook Organic" in your Sales Page. It typically includes visits from organic sources such as links shared in posts by users, pages, groups, or reposted ads. It could also represent visits from ads missing tracking parameters.
### fbclid from Ad Comments and Profile Clicks
fbclid traffic can also appear due to direct links shared in ad comments or users navigating through your Facebook profile. Here’s how:
* **Ad Comments with Store Links**: If your social media team replies to ad comments with direct links to your store, anyone clicking these links will be attributed to fbclid. Since UTMs aren’t applied to links in comments, these clicks appear as organic traffic.
* **Profile-to-Store Clicks:** If someone clicks on your business profile from a comment, then navigates to your store link on the profile, this action also leads to fbclid traffic in Northbeam.\
If you notice a high volume of fbclid traffic and your team frequently shares links in comments, this activity is likely a significant contributor.
### Troubleshooting “fbclid”
Most dashboards will have some visits, transactions, or revenue attributed to “fbclid.” However, a high amount *could* indicate an issue with your ad tracking setup.
For instance, if your dashboard shows fbclid revenue comparable to a Facebook campaign, this could mean UTMs are dropping, leaving fbclid as the only tracked parameter.
Diagnosing fbclid issues can be challenging, especially for businesses with a strong organic presence (e.g., a popular Facebook page or active group), as it’s often hard to pinpoint the exact source.
Tips to minimize "fbclid" in Northbeam
* **Check UTMs:** Ensure that all your Facebook Ads include the correct Northbeam UTM parameters. For proper setup, refer to our [Facebook Ads Tracking Guide](/docs/setting-up-facebook-ads-tracking).
* **Check Northbeam Pixel:** Ensure that our [Northbeam Pixel](/docs/add-pixel) is firing on your ad landing pages.
* **Minimize Comments with Links:** When including store links in comments, use distinct UTM parameters to differentiate organic clicks from paid clicks. This way, not all traffic is grouped under fbclid, giving you clearer visibility into traffic sources. Using a link shortener (e.g., Bitly or TinyURL) can help make UTM-tagged links look clean and avoid displaying long URLs in comments.
* **Check for Redirects:** Check your destination URLs for any instances of URL redirects. Any redirects oftentimes strip UTMs - unless custom code is implemented for UTM preservation.
* Reference: [Common URL Redirects That Strip UTM Parameters](/docs/gclid-fbclid-redirects)
***
## gclid (Google Click Identifier)
### What is “gclid”?
The "gclid" parameter is added to the URL whenever a user clicks on a link from a Google Ad. This parameter allows Google to track ad performance and user behavior after they leave the platform.
Example: `https://example.com?gclid=EAIaIQobChMI3...`
### Why do I see “gclid” in my Northbeam dashboard?
In Northbeam, **"gclid" represents users who visited your site with only the "gclid" parameter and no additional UTM parameters**. By default, this traffic is classified under “Google Ads” in your Sales Page.
### Troubleshooting “gclid”
Most dashboards have some visits, transactions, or revenue attributed to “gclid.” However, a high amount might indicate a potential issue with your ad tracking.
For example, if your dashboard has as much revenue attributed to "gclid" as a normal Google campaign, this could indicate UTM parameters are being dropped, leaving "gclid" as the only recognized parameter.
Diagnosing "gclid" issues can be tricky since it’s difficult to pinpoint the exact source.
Tips to minimize "gclid" in Northbeam
* **Check UTMs:** Ensure that all your Google Ads include the correct Northbeam UTM parameters. For proper setup, refer to our Google Ads Tracking Guide.
* **Check Northbeam Pixel:** Ensure that our [Northbeam Pixel](/docs/add-pixel) is firing on your ad landing pages.
* **Check for redirects:** Check your destination URLs for any instances of URL redirects. Any redirects oftentimes strip UTMs - unless custom code is implemented for UTM preservation.
* Reference: [Common URL Redirects That Strip UTM Parameters](/docs/gclid-fbclid-redirects#common-url-redirects-that-strip-utm-parameters)
***
## Common URL Redirects That Strip UTM Parameters
### 1. Regional Domain Redirects
**What Happens:** Some websites redirect users to regional versions of the domain based on their location (e.g., from example.com to example.co.uk for UK users).
**Impact:** If the redirection doesn't preserve UTM parameters, they can be stripped during the transition. This is often seen with brands that automatically send users to country-specific domains without preserving query parameters.
**Example:**
* Original URL: [https://example.com?utm\_source=google\&utm\_campaign=spring\_sale](https://example.com?utm_source=google\&utm_campaign=spring_sale)
* Redirected URL: [https://example.co.uk](https://example.co.uk) (UTM parameters are lost)
**How to Mitigate**
* **Minimize Redirects:** Where possible, send country-specific traffic directly to the relevant regional domains. For example, ensure UK traffic is directed to your UK-specific domain to reduce unnecessary redirection. This is most applicable to paid traffic.
* **Implement UTM Preservation on Redirects:** This may require assistance from your development team, as custom JavaScript is often needed to retain UTM parameters during URL updates or redirects.
### 2. URLs to Shopify Product Pages
**What happens:** Shopify product pages with variants often append a query string for the selected variant to the URL.
**Impact:** If you direct traffic to a URL without the variant query string, Shopify may update the URL to include the variant query. This process can result in UTM parameters being removed, causing a loss of tracking and attribution.
**Example:**
* Original URL: [https://example.com/products/product?nbt=test](https://example.com/products/product?nbt=test)
* Redirected URL: [https://example.com/products/product?variant=123456789](https://example.com/products/product?variant=123456789) (UTM parameters are lost)
**How to Mitigate**
* **Minimize Redirects:** Ensure that your ad links include the variant query string to avoid unnecessary redirects. For example, use “[https://example.com/products/product?variant=123456789”](https://example.com/products/product?variant=123456789”) instead of “[https://example.com/products/product”](https://example.com/products/product”).
* **Implement UTM Preservation:** In rare cases, even with the variant query string included, redirects may still occur. If this happens, engage your development team to troubleshoot. Custom JavaScript or third-party Shopify apps can help ensure UTM parameters are preserved during redirects.
### 3. HTTP to HTTPS
**What happens:** When a site redirects from an unsecured http\:// to a secured https\:// URL.
**Impact:** The redirect will result in UTMs being removed, causing a loss of tracking and attribution.
**Example:**
* Original URL: [http://example.com/products/product?nbt=test](http://example.com/products/product?nbt=test)
* Redirected URL: [https://example.com/products/product](https://example.com/products/product) (utms are lost)
**How to Mitigate**
* **Minimize Redirects:** Send traffic to “https” instead of “http”.
* **Implement UTM Preservation:** If using HTTP is unavoidable and a redirect must occur, ensure that your site is properly set up to preserve query strings during HTTP to HTTPS transitions.
***
## Tips to identify Google or Facebook Ad URLs That May Be Resulting in gclid or fbclid
**Google Ads:**
* **Redirect Links:** Use the [Expanded Landing Page](https://support.google.com/google-ads/answer/7543502?hl=en) report to identify potential redirects. Test ad links in your browser to check if UTMs are being stripped on page load.
**Facebook Ads:**
* **Redirect Links:** Create a [custom report](https://www.facebook.com/business/help/924647297736315) to pull full destination URLs (including UTMs) for testing. Open these links in your browser to verify that UTMs remain intact on page load.
* **Facebook Organic Links:** If your team frequently replies to comments with links, check if these links include specific UTMs. Without UTMs, "fbclid" will likely be the only parameter, meaning all visits and purchases from those links will be attributed solely to "fbclid" in Northbeam (and Google Analytics).
## Need additional help?
If you need further assistance, reach out to [Support](https://www.northbeam.io/submit-a-support-ticket)!
# Capabilities
Source: https://docs.northbeam.io/docs/get-started/capabilities
What you can do with Northbeam
Northbeam measures your marketing, tests what's causal, and gives you the tools to act on it.
## Measure
* [**Multi-Touch Attribution**](/docs/what-is-northbeam-mta-methodology) — daily attribution across channels, campaigns, ads, and creatives
* [**Clicks + Deterministic Views**](/docs/clicks-deterministic-views) — verified views joined to the click path
## Test & plan
* [**Incrementality**](/docs/incrementality) — controlled experiments that measure causal lift
* [**Mixed Media Modeling**](/docs/mixed-media-modeling) — long-run channel contribution to revenue
## Act
* [**Apex**](/docs/northbeam-apex) — send Northbeam attribution to Meta
* [**Model Comparison**](/docs/what-is-northbeam-model-comparison-tool) — every attribution model, side by side
* [**Breakdowns & saved views**](/docs/manage-breakdowns) — shape the dashboard around how your team works
## Ask & export
* [**Northbeam AI**](/docs/northbeam-ai) — ask about Northbeam and your data inside the dashboard
* [**Northbeam MCP**](/docs/northbeam-mcp) — connect an external AI assistant and query your data in plain English
* [**APIs**](/docs/using-the-api) — orders in, spend in, everything out
* [**Data exports**](/docs/exporting-data) — tables out of the dashboard, or [straight to your warehouse](/docs/northbeam-api-data-export-1)
# Use cases
Source: https://docs.northbeam.io/docs/get-started/use-cases
Outcome-first guides — start from what you're trying to do
Every use case follows the same shape — **Best for → Before you start →
The steps → What to expect → Related** — and links into the full guides.
## Diagnose & reconcile
Six checks, in order of likelihood.The apples-to-apples comparison.Catch problems before the traffic.
## Decide & optimize
Match the model to the question.Click and non-click, on equal footing.Measure causal lift.Find the ads that convert.
## Operate & report
A repeatable reporting frame.Multi-store, coherent numbers.GCS or S3, on a schedule.Set up Apex.Plain-English answers over MCP.
# Troubleshooting Pixel Tracking
Source: https://docs.northbeam.io/docs/guide-to-troubleshooting-pixel-tracking
Diagnose online orders that appear as Not Attributed.
Northbeam uses two sources to attribute an online order:
* **Server data** comes from Shopify, another commerce integration, or the Orders API.
* **Pixel data** comes from the Northbeam Pixel and `firePurchaseEvent`.
## 1. Find an example order
Open [Orders](https://dashboard.northbeam.io/orders) and search for the exact order ID.
| What you find | What it means | Next check |
| :- | :- | :- |
| Order is absent | Northbeam may not have received the backend order. | Check the commerce connection or Orders API response. |
| Attributed: **No** | Northbeam received the order but could not connect it to a customer journey. | Check `firePurchaseEvent` and the order ID. |
| Attributed: **Yes** | The order is attributed. | Check report settings if the order still appears incorrect. |
## 2. Troubleshoot an order that is Not Attributed
Confirm that:
1. `firePurchaseEvent` fires after a successful checkout.
2. `firePurchaseEvent` and the backend order use the exact same order ID.
3. The order ID matches character for character, including capitalization, prefixes, spaces, and punctuation.
4. The checkout domain and payment flow support the expected pixel tracking.
Open [Pixel and Event Tracking](https://dashboard.northbeam.io/settings/tracking-script-tags) and review the [Purchase Events guide](/docs/purchase-pixel).
## 3. Check whether missing pixel tracking is expected
Some orders do not complete through a standard web checkout and may be Not Attributed by design. Examples include:
* Recurring subscriptions
* Draft orders
* Offline or POS orders
* Wholesale orders
* Some marketplace or app purchases
## 4. Check the trend
Compare attributed orders before and after the issue began. A sudden drop that aligns with a site, domain, consent, or checkout change should be investigated using examples from both periods.
If you cannot isolate the cause, [submit a Northbeam Support request](https://www.northbeam.io/submit-a-support-ticket) with example order IDs and their **Attributed** values.
# Hashing Customer Data
Source: https://docs.northbeam.io/docs/hashing-customer-data
Normalization and hashing guidelines for customer email and phone numbers
# NB Orders API Guide: Normalization for Hashed Email & Phone
This document specifies normalization rules for emails and phone numbers prior to hashing for the `hashed_customer_email` and `hashed_customer_phone_number` fields in the NB Orders API. These rules are identical to the normalization used by integrated advertising platforms so that hashes generated by customers match 1:1 with platform-provided hashes.
**Important:**
• If you are sending raw emails/phone you should not send these hashed fields
• The emails and phone numbers should be first normalized and then hashed. The hashed versions should be sent via the NB API.
## Hashing Output Format
* **Algorithm**: SHA-256
* **Input**: Normalized email or phone number
* **Output**: Lowercase hexadecimal (64 characters), no prefix
* **Email**: Hash the normalized email string
* **Phone**: Hash the E.164 string returned by normalization (include the leading `+`)
***
## Email Normalization
### Purpose
Normalize email addresses to a consistent format so that variations of the same email are treated as equivalent. This is useful for deduplication, simplified email handling and creating consistent SHA-256 hashes from emails.
### General Rules
1. **Lowercasing**: Convert the entire email address to lowercase.
2. **Trimming**: Remove any spaces from the beginning or end of the email address.
3. **Validation**:
* The email must contain exactly one `@` symbol.
* If not, use the trimmed and lowercased email as-is.
### Domain-Specific Normalization Rules
Apply the following rules to the local part (the portion before the `@`) based on the email's domain:
#### Gmail (`gmail.com`)
* Remove everything after and including the first `+` character.
* Remove all periods (`.`).
#### Yahoo / Ymail (`yahoo.com`, `ymail.com`)
* Remove everything after and including the first `-` character.
* Remove all periods (`.`).
#### Outlook (`outlook.com`)
* Remove everything after and including the first `+` character.
#### ProtonMail (`protonmail.com`, `protonmail.ch`, `pm.me`)
* Remove everything after and including the first `+` character.
#### Apple Domains (`icloud.com`, `me.com`, `mac.com`)
* Remove everything after and including the first `+` character.
### Final Step
Recombine the cleaned local part with the domain part using `@`. Use the resulting normalized email address.
### Examples
| Input Email | Normalized Email | Hashed Email (SHA-256) |
| - | - | - |
| [John.Doe+newsletters@gmail.com](mailto:John.Doe+newsletters@gmail.com) | [johndoe@gmail.com](mailto:johndoe@gmail.com) | 06a240d11cc201676da976f7b49341181fd180da37cbe40a77432c0a366c80c3 |
| [Jane-Doe+promo@ymail.com](mailto:Jane-Doe+promo@ymail.com) | [jane@ymail.com](mailto:jane@ymail.com) | 4a5206b6c57519e9ad41b5358b80f7e6e33dff21a263914f343454ab0fbbb4cb |
| [User.Name@outlook.com](mailto:User.Name@outlook.com) | [user.name@outlook.com](mailto:user.name@outlook.com) | 121a30e5c931fc09bbfcdbd9586976e764c76ac3687ba9afcde1fb7b92c077ce |
| [User+notes@pm.me](mailto:User+notes@pm.me) | [user@pm.me](mailto:user@pm.me) | d5080076cd5eb196ad2ed4d15dd93113fa810c17b51813d0bb5acc2b3f266ffc |
| [Test+spam@icloud.com](mailto:Test+spam@icloud.com) | [test@icloud.com](mailto:test@icloud.com) | 528dfe1c042ae276513bd1f3b662faaee6ef3ce8b9bea03181aa94ea4592683b |
### Reference Implementation (JavaScript)
```javascript theme={null}
function emailNormalize(email) {
if (!email) {
return null;
}
// Utility functions
const stripPeriods = (value) => value.replace(/\./g, '');
const plusAddressing = (value) => value.split('+')[0];
const dashAddressing = (value) => value.split('-')[0];
// Normalize format
const normalized = email.trim().toLowerCase();
const parts = normalized.split('@');
// Invalid email format, return as-is
if (parts.length !== 2) {
return normalized;
}
let [localPart, domainPart] = parts;
let localPartRules = [];
// Domain-specific rules
switch (domainPart) {
case 'gmail.com':
localPartRules = [plusAddressing, stripPeriods];
break;
case 'yahoo.com':
case 'ymail.com':
localPartRules = [dashAddressing, stripPeriods];
break;
case 'outlook.com':
case 'protonmail.com':
case 'protonmail.ch':
case 'pm.me':
case 'icloud.com':
case 'me.com':
case 'mac.com':
localPartRules = [plusAddressing];
break;
}
// Apply all relevant rules
for (const rule of localPartRules) {
localPart = rule(localPart);
}
return `${localPart}@${domainPart}`;
}
```
***
## Phone Normalization
### Purpose
Format a phone number into a consistent style using the `libphonenumber-js` library. This library:
* Removes any non-digit characters (like spaces, dashes, parentheses).
* Makes sure it starts with a `+` country code. If there's no country code, it adds `+1` (for the US/Canada).
* Returns `null` if the phone number is not valid.
### Reference Implementation (JavaScript)
```javascript theme={null}
// Uses the libphonenumber-js library; import as follows:
// For ES6 modules (Node.js or modern bundlers)
import { parsePhoneNumber } from 'libphonenumber-js';
// OR for CommonJS (Node.js)
// const { parsePhoneNumber } = require('libphonenumber-js');
function normalizePhoneNumber(phone) {
try {
const parsed_phone = parsePhoneNumber(phone, 'US');
if (!parsed_phone || !parsed_phone.isValid()) return null;
return parsed_phone.number;
} catch (e) {
return null;
}
}
```
### Examples
| Raw Phone Number | Normalized Phone (E.164) | Hashed Phone (SHA-256) |
| - | - | - |
| (212) 555-1234 | +12125551234 | b7532e84c87df1f9f6bc4097cea3fa27db1b990bdc8d1211e59586349e5cce82 |
| 415.555.2368 | +14155552368 | 5efe6d2b35a8b1cd9395c2f451ff4d4eb6dd9ddc6761cdefea0653d62ac24011 |
| 3105551234 | +13105551234 | a2f7381cd9b4a70cbbbe1113afa0770eed79adfba525c33b69a11f87790850e1 |
| 1-718-555-7890 | +17185557890 | d7c5b36eb18b782d398fd7e3eec015189c801b2c24d226c3689198bb5ef952d2 |
***
## Using Hashed Emails for Attribution & CDV
Northbeam supports passing hashed emails through both the Pixel `identify` call and the Orders API. This allows hashed emails to be used for attribution and Customer Data Vault (CDV) matching workflows.
### Pixel Identify Call
If you are already using the standard `identify` call, replace `"email"` with `"hashed_email"` and pass the normalized and SHA-256-hashed value instead (apply the same normalization rules above before hashing).
#### Example
```javascript theme={null}
// SHA-256 of the normalized email "johndoe@gmail.com"
window.Northbeam.identify(
"hashed_email",
"06a240d11cc201676da976f7b49341181fd180da37cbe40a77432c0a366c80c3"
);
```
### Orders API
If sending hashed customer data through the Orders API, populate the `hashed_customer_email` field with the same SHA-256 hashed email value.
### Important
To enable hashed email attribution and CDV matching end-to-end:
* Pass the hashed email through the Pixel `identify` call using `hashed_email`
* Pass the same hashed value through the Orders API using `hashed_customer_email`
Both values must:
* Be normalized prior to hashing
* Use SHA-256 hashing
* Match consistently between the Pixel and Orders API
***
## Complete Workflow Example
Here's a complete example showing normalization → hashing for both email and phone:
```javascript theme={null}
import crypto from 'crypto';
import { parsePhoneNumber } from 'libphonenumber-js';
// Hash a normalized string using SHA-256
function sha256Hash(input) {
return crypto.createHash('sha256').update(input, 'utf8').digest('hex');
}
// Example usage
const email = 'John.Doe+newsletters@gmail.com';
const phone = '(555) 123-4567';
const normalizedEmail = emailNormalize(email); // "johndoe@gmail.com"
const hashedEmail = sha256Hash(normalizedEmail);
const normalizedPhone = normalizePhoneNumber(phone); // "+15551234567"
const hashedPhone = sha256Hash(normalizedPhone);
console.log('Hashed Email:', hashedEmail);
console.log('Hashed Phone:', hashedPhone);
```
***
## Important Notes
* Always normalize **before** hashing
* Use SHA-256 with lowercase hexadecimal output
* Phone numbers should include the `+` when hashing
* Invalid phone numbers return `null` - handle these gracefully in your implementation
* These normalization rules match advertising platform standards for consistent matching
# How do I correctly and confidently interpret non-click channels?
Source: https://docs.northbeam.io/docs/how-do-i-correctly-confidently-interpret-non-click-channels
What’s normal and expected?
Attributing performance to **Non-Click Channels** like TV, Podcast, or Influencer campaigns can be difficult, but Northbeam makes it easier.
Our [Metrics Explorer](/docs/metrics-explorer) help you uncover the **indirect impact** of these channels by showing correlation trends between spend and key business outcomes (Revenue or First-Time Purchases). You can explore this data with custom time ranges and attribution models on granular views.
For example, you can use [Metrics Explorer](https://dashboard.northbeam.io/metrics-explorer) to reveal a strong correlation between TV Spend and First-Time Transaction over the last 30 days to see the true value of offline investments:
Even when direct clicks aren't available, Northbeam equips you with tools to make data-informed, strategic decisions across all channels.
# How does Northbeam track Orders and Ads?
Source: https://docs.northbeam.io/docs/how-does-northbeam-track-orders-and-ads
How does Northbeam data work?
Northbeam uses three core data sources to track customer journeys and attribute performance across your marketing efforts:
1. **Journey Tracking via First-Party Pixel**
1. Captures all customer touchpoints across Paid Channels and Brand Interactions.
2. **Order Data via Server-to-Server Integration**
1. Pulls in the order data from platforms like Shopify via direct backend connections.
3. **Platform-Level Data**
1. Ingests Spend and Performance data directly from ad platforms like Meta and Google.
# Overview Video
## TL;DR
**About Unattributed Data**
* Some orders may show up as unattributed, which is normal and expected to a certain extent. This typically occurs when pixel data is missing or incomplete.
**Common causes of Unattributed Orders**:
* Draft or manually created Orders
* Wholesale or Marketplace Orders (eg., Tapcart, ClickFunnels, Walmart)
* Third-Party Checkouts or Apps
* Subscription Renewals from before Northbeam was installed
* Orders from native shopping tools (Meta Shops and TikTok Shops are now supported)
Any Orders that does not trigger the Northbeam Pixel and Purchase Pixel will appear as Unattributed.
Northbeam monitors each dashboards for normal thresholds of unattributed data. While some unattributed data is expected, the **majority of your oder and revenue data will be properly attributed** through our integrated tracking system.
# Northbeam's Integrations
Source: https://docs.northbeam.io/docs/integration-matrix
For any platform where spend is not available via API, you can upload your spend manually via our Custom Spreadsheet [here](https://docs.northbeam.io/v2.2/docs/add-spend#option-2-spend-sheet).
Please reach out to [us here](https://www.northbeam.io/submit-a-support-ticket) or your Customer Success Manager if you have any questions regarding integrations.
# Integrations and UTMs
Source: https://docs.northbeam.io/docs/integrations-and-utms
Connect Integrations and UTMs
Connect your platform accounts to Northbeam, and if you’re prompted, please grant Northbeam the highest level of permissions requested for each platform. These connections are essential to give you a complete view of your advertising performance.
Northbeam has native integrations with:
* [Facebook Ads](/docs/setting-up-facebook-ads-tracking)
* [Google Ads](/docs/setting-up-google-ads-for-northbeam)
* [Amazon Ads](/docs/tracking-for-amazon)
* [Amazon Seller](/docs/tracking-for-amazon)
* [Microsoft Ads](/docs/tracking-for-microsoft)
* [Snapchat Ads](/docs/tracking-for-snapchat-ads)
* [Pinterest Ads](/docs/tracking-for-pinterest-ads)
* [TikTok Ads](/docs/setting-up-tiktok-ads-for-northbeam)
Additional connections include:
* [Attentive](/docs/working-tracking-for-attentive)
* [MNTN](/docs/tracking-for-mntn)
* [Tatari](/docs/tracking-for-tatari)
* [Rakuten](/docs/tracking-for-rakuten)
* [Bliss Point Media](/docs/tracking-for-bliss-point-by-tinuiti)
### Don’t see one of your platforms or services listed here?
Reference our [Tracking for Non-Integrated Channels guide](/docs/tracking-for-other-platforms) to learn more about options and requirements.
[Reach out to our Support Team](https://www.northbeam.io/submit-a-support-ticket) for additional guidance.
## UTMs
UTM stands for "Urchin Tracking Module" — parameters added to a URL to track the source of web traffic (a social ad, email, display ad, and so on). Northbeam uses UTMs to link your metrics to specific ads and build detailed customer journeys.
**Northbeam UTMs are required for active ads on integrated platforms** to ensure accurate spend mapping and attribution. Attribution tracking won't be available until Northbeam UTMs are added to your active ads on these platforms.
### Channel-specific UTMs
Find the required UTM parameters for each channel:
* [Facebook Ads](/docs/setting-up-facebook-ads-tracking)
* [Google + YouTube Ads](/docs/setting-up-google-ads-for-northbeam)
* [TikTok Ads](/docs/setting-up-tiktok-ads-for-northbeam)
* [Snapchat Ads](/docs/tracking-for-snapchat-ads)
* [Klaviyo](/docs/setting-up-klaviyo-for-northbeam)
* [Attentive](/docs/working-tracking-for-attentive)
* [Pinterest Ads](/docs/tracking-for-pinterest-ads)
* [Microsoft Ads](/docs/tracking-for-microsoft)
* [Amazon](/docs/tracking-for-amazon)
* [TradeDesk](/docs/tracking-for-tradedesk)
* [MNTN](/docs/tracking-for-mntn)
* [Tatari](/docs/tracking-for-tatari)
* [Bliss Point Media](/docs/tracking-for-bliss-point-by-tinuiti)
* [All Other Channels](/docs/tracking-for-other-platforms)
# Invite Team
Source: https://docs.northbeam.io/docs/invite-team
Add additional users to your account
## Send the invite
01Add the user's email
02Click SEND INVITE
No limitNorthbeam does not put a limit on the number of users in your account — add as many people as you would like.
## People you'll want to invite
01Ad account ownerse.g. Facebook Ads Manager
02DNS ownere.g. GoDaddy, Google Domains, Cloudflare
03E-commerce ownere.g. Shopify, BigCommerce, Woo
## Frequently asked questions
01Why should I invite account managers?
Account managers are able to assist with onboarding tasks that you may be unable to complete on your own.
02Who should I invite?
Any stakeholders interested in Northbeam data — ad buyers and managers, executives, and agency partners. If external partners run platform-specific advertising, collect login credentials from them or add them as account managers. An engineer can help implement the Northbeam pixel and the Orders API.
03What permissions do account managers have?
They can add other managers, view all data, view and set connections, and perform every action the account owner can. Only the admin account manager can delete other account managers.
04What if the invitee doesn't receive an email?
Check the spam folder. If it's still missing, they can generate a password through the password reset flow on [dashboard.northbeam.io](https://dashboard.northbeam.io).
# Design your dashboard
Source: https://docs.northbeam.io/docs/journey/design-your-dashboard
Shape the views your team reports from
Out of the box, Northbeam shows you everything. Design the views that
match how your team actually talks about the business.
Group channels, campaigns, and ads your way.
[Manage breakdowns and saved views →](/docs/manage-breakdowns)
Pick the attribution model, window, and accounting mode your team
reports on — and keep them stable.
[Accounting modes →](/docs/accounting-modes)
Set up a dashboard per storefront.
[Multi-dashboard setup →](/docs/multi-dashboard-setup-with-configurators)
Next up: [Use Northbeam AI →](/docs/journey/northbeam-ai)
# First steps
Source: https://docs.northbeam.io/docs/journey/get-started
Where the journey begins
Welcome. This journey takes you from a new account to a dashboard your team actually uses — each stage links to the full guides. this is a change
The five setup steps, end to end. [Quickstart →](/docs/quickstart)
Implementation isn't instant — here's the shape of it. [What to expect during implementation →](/docs/what-to-expect-during-implementation)
Account, tracking, orders, and spend — in order. [Onboarding →](/docs/navigating-northbeam)
Next up: [Understand your platform →](/docs/journey/understand-your-platform)
# Integrations
Source: https://docs.northbeam.io/docs/journey/integrations
Connect every channel you spend on
Attribution is only as complete as your connections. Connect each
platform, add Northbeam UTMs, and confirm data is flowing.
How connections and UTMs work across every platform.
[Integrations and UTMs →](/docs/integrations-and-utms)
Every channel guide follows the same shape: connect, add UTMs, confirm.
[Channels & stores →](/docs/setting-up-facebook-ads-tracking)
[Check UTM tracking →](/docs/checking-utm-tracking) · [Check platform connections →](/docs/checking-api-connections)
Next up: [Watch the competition →](/docs/journey/watch-the-competition)
# Northbeam AI
Source: https://docs.northbeam.io/docs/journey/northbeam-ai
Ask your data questions in plain English
Use Northbeam AI inside the dashboard, or connect an external AI assistant to
your Northbeam data with MCP. Both are available on every Northbeam plan.
## Ask in Northbeam
Open **Northbeam AI** from the AI icon in the left-hand menu. Ask how Northbeam
works, query the dashboard you are currently in, or file a support ticket.
[Learn how to use Northbeam AI →](/docs/northbeam-ai)
## Connect another AI assistant
Northbeam MCP gives ChatGPT, Claude, and other compatible tools read-only access
to your Northbeam data.
[ChatGPT →](/docs/connect-northbeam-to-chatgpt) · [Claude →](/docs/connect-northbeam-to-claude) · [Another AI tool →](/docs/connect-northbeam-to-ai-agent)
Add Northbeam as a custom connector using `https://mcp.northbeam.io`, then
sign in with your normal Northbeam login. You don't need a separate account
or API key.
[Setup overview →](/docs/northbeam-mcp)
Ask your assistant to list your Northbeam dashboards. If it returns your
dashboards, you are connected.
Northbeam MCP follows your existing permissions. Your assistant can't see or
change anything that your Northbeam account can't access.
[Security and privacy FAQs →](/docs/northbeam-mcp-server-faqs)
Next up: [Set up and track alerts →](/docs/journey/set-up-and-track-alerts)
# Set up and track alerts
Source: https://docs.northbeam.io/docs/journey/set-up-and-track-alerts
Know when a number moves — without watching for it
This guide is being built out — more here soon.
In the meantime, when a number moves and you want to know why:
* [Diagnose a ROAS drop](/docs/use-cases/diagnose-a-roas-drop) — the six checks, in order of likelihood
Next up: [Utilize advanced features →](/docs/journey/utilize-advanced-features)
# Understand your dashboard
Source: https://docs.northbeam.io/docs/journey/understand-your-platform
Learn the surfaces you'll use every day
Northbeam's dashboard has a few core surfaces. Learn what each one is
for before you start making decisions from it.
* [Navigating Northbeam](/docs/navigating-northbeam) — the guided ramp-up
* [Overview page](/docs/overview-page) — your topline read
* [Attribution page](/docs/attribution-page) — channel and campaign performance
* [Metrics Explorer](/docs/metrics-explorer) — build custom views of any metric
And the language behind the numbers:
* [Attribution models](/docs/attribution-models) · [Attribution windows](/docs/attribution-windows) · [Metrics 101](/docs/northbeam-metrics-101)
Next up: [Integrations →](/docs/journey/integrations)
# Utilize advanced features
Source: https://docs.northbeam.io/docs/journey/utilize-advanced-features
The deeper toolkit, once the basics are humming
When setup is behind you and the dashboard is trusted, these take you
further:
* [Model Comparison tool](/docs/what-is-northbeam-model-comparison-tool) — every attribution model, side by side
* [Exporting data](/docs/exporting-data) and [Touchpoints export](/docs/touchpoints-export)
* [Subscription analytics](/docs/subscription-analytics)
* [Creative Analytics](/docs/creative-analytics)
* [Send attribution to Meta with Apex](/docs/use-cases/send-attribution-to-meta)
* [Pull data into your warehouse](/docs/use-cases/pull-data-into-your-warehouse)
That's the journey. For everything else: [Use cases →](/docs/use-cases/diagnose-a-roas-drop)
# Watch the competition
Source: https://docs.northbeam.io/docs/journey/watch-the-competition
See how your numbers compare
Your ROAS means more in context. Northbeam's profitability benchmarks
show how your performance compares, so you know whether a number is
good — not just whether it moved.
* [Profitability benchmarks](/docs/profitability-benchmarks) — how benchmarks work and how to read them
* [What is a good (or bad) number?](/docs/what-is-a-good-bad-number-in-northbeam) — reading your metrics in context
Next up: [Design your dashboard →](/docs/journey/design-your-dashboard)
# Changelog
Source: https://docs.northbeam.io/docs/landings/changelog
Product and channel updates.
The running log of what changed — product updates and channel-side changes that can affect your data. Check here first when numbers shift unexpectedly.
## What you'll do
* See what changed in the product
* Track channel changes that affect your data
## Release notes
***
**Next section:** [Developers & API](/docs/landings/developers-api)
# Channels
Source: https://docs.northbeam.io/docs/landings/channels
Set up tracking for each platform you spend on. Every guide follows the same steps.
Set up one guide for each platform you spend on. Most guides follow the same steps:
Northbeam pulls in spend, impressions, and campaign structure.
For channels that send clicks to your site, so visits and orders tie back to your ads.
Check that data is flowing before you rely on it.
## Find your channel
### Paid Social & Search
### CTV & Streaming
### Programmatic, Display & Apps
### Commerce & Marketplaces
### Email & SMS
### Affiliate & Partnerships
### Other Setups
Don't see your platform? Any platform can be tracked with [Spend API + UTMs](/docs/non-integrated-channel-setup-spend-api-utms).
## Learn the basics
***
**Next section:** [Data & terminology](/docs/overviews/data-terminology)
# Developers & API
Source: https://docs.northbeam.io/docs/landings/developers-api
Guidance for Using the Northbeam Orders API
Northbeam's APIs for sending data in and getting data out — orders, spend, and exports — plus the MCP server for querying your data in natural language. Start with Using the API for authentication and environments, then jump to the API your task needs.
## What you'll do
* Send orders and spend programmatically
* Export attribution data, metrics, and breakdowns to your own systems
* Authenticate and test in UAT before touching production
## Using the API
***
**Next section:** [Playbooks](/docs/landings/internal)
# Get started
Source: https://docs.northbeam.io/docs/landings/get-started
What Northbeam is, what it can do, and your journey from setup to advanced features.
This section is the front door to Northbeam. It explains what the platform is, what it can do, and how the pieces fit together — before you touch any settings.
## What you'll do
* Understand what Northbeam measures and how
* See the platform's capabilities at a glance
* Follow your journey from first setup to advanced features
## Overview
***
**Next section:** [Onboarding](/docs/overviews/onboarding)
# Playbooks
Source: https://docs.northbeam.io/docs/landings/internal
Playbooks and best practices for teams using Northbeam.
Playbooks and best practices for how each team can use Northbeam day to day.
## What you'll do
* Find guidance for your team
* Apply recommended dashboard settings
## Playbooks by team
***
**Next section:** [Get started](/docs/landings/get-started)
# Link DNS
Source: https://docs.northbeam.io/docs/link-dns
Configure DNS record for Northbeam
## What is DNS Setup?
DNS (Domain Name System) setup involves creating an **A Record** in your domain provider. For Northbeam, this means adding a subdomain—commonly named `i`—that points to an address provided in your dashboard.
This simple step enables **first-party tracking** using your domain, unlocking advanced tracking capabilities while avoiding many of the limitations of third-party tracking.
## Setting up your DNS
Having a dedicated DNS entry for Northbeam improves our ability to track your customers when they return to your website after their first visit.
In your domain provider, you'll need to 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.
Content Security Policy
In order for the pixel to use this subdomain, your Content Security Policy (CSP) must explicitly or implicitly allow traffic to the i subdomain. Please make sure your CSP includes either:
* `*.your-store.com`, or
* `i.your-store.com`
in the connect-src of your CSP.
### Examples
* `www.my-store.com`
* Top-level domain: `my-store.com`
* Create a DNS record for `i.my-store.com`
* `try.my-product.com` and `get.my-product.com`
* Top-level domain: `my-product.com`
* Create a DNS record for `i.my-product.com`
### Instructions are available for multiple Domain providers
* Generic
* GoDaddy
* CloudFlare
* Google Domains
## Following the onboarding flow here will lead you to success\*\*
:tada:
### Instructions
Follow these steps to enable first-party tracking with Northbeam:
1. **Log In to Your Domain Provider**\
Access the DNS settings for the domain you want to use with Northbeam.
2. **Create an A Record**
* **Host Name**: Use `i`
* **Address**: This is provided in your Northbeam dashboard. Copy and paste it exactly as shown.
* **Examples of A-Record Entries**\
Here’s what your DNS setup might look like:
* `i.northbeam.io` -> The top-level domain here is `northbeam.io`.
* `i.company-2.com` -> The top-level domain here is `company-2.com`.
3. **Save Your Changes**\
Once saved, your DNS setup will enable first-party tracking through Northbeam.
***
### ⚠️ Additional Step for Domains Using DNSSEC
If your domain has **DNSSEC (DNS Security Extensions)** enabled, you’ll need to add a **CAA record** to allow certificate issuance by Let's Encrypt. Without this step, your SSL certificate may fail to generate, resulting in issues like `404 not found` or certificate mismatch errors.
#### Add the following CAA record
| Field | Value |
| - | - |
| **Type** | CAA |
| **Name** | `i` (or your assigned subdomain) |
| **TTL** | `3600` |
| **Flag** | `0` |
| **Tag** | `issue` |
| **Value** | `letsencrypt.org` |
### If you're unsure whether DNSSEC is enabled, check with your domain provider or DNS settings panel.
You can also use tools like [https://dnschecker.org](https://dnschecker.org) to verify DNSSEC and CAA status.
# Lookback Windows
Source: https://docs.northbeam.io/docs/lookback-windows
Northbeam now allows you to **set a lookback window** for how far back we consider touchpoints when attributing orders.
## What’s a Lookback Window?
A lookback window defines how far back in time we consider touchpoints (like ad clicks or views) when attributing an order.
For example:
* With an **infinite lookback**, a Facebook ad click from two years ago could still receive credit for a purchase made today.
* With a **90-day lookback**, only touchpoints that occurred within the 90 days before the order are eligible for credit.
By setting a lookback window, you keep journeys realistic and prevent credit from being assigned to interactions that happened too far in the past.
***
## How This Differs From Attribution Windows
It’s easy to confuse lookback windows with attribution windows, but they serve different purposes:
* **Lookback Windows**: Decide *which touchpoints are eligible* to receive credit for an order.
* Example: With a 90-day lookback, a click from 6 months ago is ignored completely — no credit is ever assigned to it, even if it’s the only touchpoint.
* **Attribution Windows**: Act as a *filter on the revenue that’s already been distributed to touchpoints*. Once an order’s value is split across eligible touchpoints (based on the lookback window), the attribution window answers: *“How much of this order’s revenue came from touchpoints within X days of the order?”*
* Example: With a 7-day attribution window, we can say: *"Of this \$300 order, \$225 came from touchpoints in the past 7 days, and \$75 came from older touchpoints."*
In other words:
* **Lookback Window = eligibility** (who can ever get credit).
* **Attribution Window = reporting lens** (of the credit assigned, how much is recent vs. older).
### Learn more about Attribution Windows here: [Attribution Windows Documentation](/docs/attribution-windows)
***
## Why This Matters
Without a lookback window, long-tenured customers can end up with journeys that stretch back years. This can cause:
1. **Unrealistic credit allocation** — credit gets sent to ads long in the past.
2. **Distorted returning customer revenue** — revenue may appear lower in recent periods because it’s being attributed far back in time.
3. **Inflated touchpoint counts** — journeys can include years of activity, making them hard to interpret.
When a lookback window is applied, we typically see the **largest impact on returning customer revenue**, since returning customers are more likely to have older touchpoints. New customer revenue is usually much less affected.
***
## How to Change Your Lookback Window
1. Go to **Settings → Model Settings**.
2. Select your preferred lookback window (90 days, 180 days, 1 year, or 10 years). The default is 180 days.
3. Once updated, your data will automatically restate within 24 hours.
***
## Important Note on Historical Data
Changing your lookback window does more than affect data going forward — it **retroactively restates historical data across your entire Northbeam account**.
This has two important implications:
1. **Historical numbers will update** - When you adjust the lookback window, your past reporting will also shift. This means teammates might notice unexpected changes in dashboards and reports.
2. **You can undo changes** - If you switch your lookback window and later decide to revert, simply reset it to the previous setting. Your historical data will return to its prior state — no harm done.
***
## Key Takeaways
* Lookback windows **set the bounds** on how far back we consider touchpoints for attribution.
* This prevents unrealistic journeys (e.g., giving credit to a two-year-old ad).
* Returning customer revenue is typically most affected — but new customer revenue can shift too.
* Choose the lookback that still reflects your sales cycle.
* **Remember:** changing the lookback window updates historical numbers account-wide, but you can always revert to your prior setting.
# Manage Breakdowns and Saved Views
Source: https://docs.northbeam.io/docs/manage-breakdowns
**Breakdowns** are used to organize your channels, campaigns, adsets, and ads in any way you'd like. They are a handy tool that can be utilized across almost all pages in your dashboard.
In this guide, we'll cover:
* Northbeam's Default Breakdowns
* Making a Custom Breakdown
* Editing a Default Breakdown
## Northbeam's Default Breakdowns
We provide 4 default breakdowns, and many of our customers also choose to create custom breakdowns for specific groupings.
***
### **"Platform (Northbeam)"**
In this breakdown, Channels are grouped by their respective platforms. For example: Facebook Ads, Google Ads, TikTok Ads, Twitter, Organic, Organic Search, etc.
You’ll also see a group named “Other.” We categorize any miscellaneous traffic here, so it’s important to check this and regroup if necessary.
### How the "Platform (Northbeam)" Breakdown Works
The **Platform (Northbeam)** breakdown automatically sorts every visit, click, and conversion into a standardized set of channel names, such as Facebook Ads, Google Ads, TikTok Ads, and Organic Search, so you can compare performance across all of your marketing in one place.
This breakdown is maintained by Northbeam and applied automatically to every account.
#### How a Visit Is Classified
For each visit, Northbeam evaluates a prioritized list of platforms and assigns the **first matching platform**.
Because more specific platforms are evaluated before broader catch-all categories, well-tagged ad traffic is typically classified before falling through to categories such as Organic, Unattributed, or Other.
To classify a visit, Northbeam evaluates four primary signals:
| Signal | Description |
| - | - |
| **Northbeam Tracking (NBT)** | The platform identified by Northbeam's first-party tracking. This is typically the most reliable signal. |
| **Connected Ad Account** | The advertising platform associated with a connected ad account, such as Meta, Google, TikTok, or Pinterest. |
| **UTM Parameters** | Values contained in `utm_source`, `utm_medium`, and `utm_campaign`. |
| **Referring Site** | The website a visitor came from before arriving on your site. |
> **Note:** UTM matching is case-insensitive. "Equals" means the value must match exactly. "Contains" means the value may appear anywhere within the field.
#### Platform Definitions
| Platform | Matching Logic |
| - | - |
| **Facebook Ads** | Classified as Facebook Ads when the visit is not Meta Shops or Facebook Organic and Northbeam identifies Meta through:
• NBT platform = `fb` • `utm_source` or `utm_medium` equals `facebook`, `instagram`, `fb`, `ig`, `an`, or `msg` • `utm_source` contains `fb_ads` • `utm_source` or `utm_medium` contains a Meta placement value such as `Facebook_Mobile_Feed`, `Facebook_Desktop_Feed`, `Facebook_Instant_Articles`, `Facebook_Marketplace`, `Facebook_Right_Column`, `Facebook_Instream_Video`, `Facebook_Stories`, `Instagram_Feed`, `Instagram_Explore`, or `Instagram_Stories` • `utm_source` or `utm_medium` contains `facebook` or `instagram` while the other field contains a paid social value such as `paid`, `paid-social`, `paid_social`, or `p` |
| **Google Ads** | Classified as Google Ads when:
• NBT platform = `adwords` • `utm_source` or `utm_medium` equals `google`, `adwords`, or `youtube` |
| **YouTube Ads** | Classified as YouTube Ads when:
• Connected Google campaign channel type = `Video` • NBT platform = `adwords` and campaign name or `utm_source` contains `video`, `youtube`, or `yt` • `utm_source` equals `google`, `youtube`, or `yt` and `utm_medium = video` (or vice versa) |
| **YouTube Organic** | Classified as YouTube Organic when the referring site is `youtube.com`. |
| **TikTok Ads** | Classified as TikTok Ads when:
• Connected ad account = `tiktok` • `utm_source` contains `tiktok` • `utm_medium` contains `tiktok` • Campaign name contains `tiktok` • `utm_source = tiktok` and `utm_medium = cpc`
Appears as **TikTok** in reports. |
| **Pinterest** | Classified as Pinterest when:
• A connected Pinterest account exists • `utm_source`, `utm_medium`, or campaign name contains `pinterest` • Referring site contains `pinterest` |
| **Snapchat Ads** | Classified as Snapchat Ads when:
• Northbeam Tracking identifies LinkedIn • `utm_source = linkedin` • Referring site = `linkedin.com` |
| **Microsoft Ads (Bing)** | Classified as Microsoft Ads when:
• Northbeam Tracking identifies Microsoft • `utm_source` or `utm_medium` contains `bing` |
| **Reddit** | Classified as Reddit when:
• `utm_source` contains `reddit` • Referring site = `reddit.com` |
| **Twitter** | Classified as Twitter when:
• Referring site is `twitter.com` or `t.co` • `utm_source` contains `twitter` • Connected ad account is Twitter |
| **Klaviyo** | Classified as Klaviyo when:
• Northbeam Tracking identifies Klaviyo • Campaign name contains `klaviyo` • `utm_source` or `utm_medium` contains `klaviyo` |
| **SMS & Email Platforms** | Classified by the specific provider when its name or tagging conventions are detected, including:
• **Attentive** (`utm_source`, `utm_medium`, or campaign name = `attentive`) • **Postscript** (`postscript` in UTMs, or SMS tagging where one of `utm_source` / `utm_medium` is `ps` and the other is `sms`) • **SMSBump** (`smsbump` in UTMs, or `utm_medium = sms` and `utm_source = campaign`) • **Wunderkind**, **ActiveCampaign**, **LiveIntent**, **Recart**, **PushOwl**, and **Retention Science (ReSci)** when their names appear in UTMs or campaign names • **Other Email** when `utm_source` or `utm_medium` equals `email`, or the visit originated from an email application |
| **Affiliate Platforms** | Classified as an affiliate platform when Northbeam identifies affiliate-specific integrations or UTMs, including:
• **Impact** (`utm_source` begins with `impact`, or a connected Impact account) • **ShareASale** (`shareasale` appears in UTMs or referral domains) • **Rakuten** (connected Rakuten account, or `rakuten` in UTMs or campaign names) • **Awin** (`utm_source = aw` or `awin`, or `utm_medium = awin`) • **AvantLink** (`avantlink` appears in UTMs) • **Refersion** (NBT = `refersion` or Refersion UTMs) • **Pepperjam / Partnerize** (NBT = `pepperjam`, or UTMs contain `pepperjam` or `partnerize`) • **Friendbuy**, **Sezzle**, **Grin**, **Yotpo**, and **Loox** when their names appear in UTMs |
| **Native & Content Platforms** | Classified by platform-specific identifiers appearing in `utm_source`, `utm_medium`, or campaign names, including **Taboola**, **Outbrain**, **Revcontent**, and **SourceKnowledge**. |
| **CTV, Audio & Programmatic** | Classified primarily using connected ad accounts (or matching UTMs), including **The Trade Desk** (Display, Video, Audio, and CTV variants), **Bliss Point Media** (Display, Audio, and Linear variants), **Tatari**, **Tatari Linear**, **MNTN**, **Mediamath**, **Adelphic**, **Audacy**, **Vibe**, **Rokt**, **Criteo**, **Amazon DSP**, **Google DV 360**, and **Axon by AppLovin**. |
| **Influencer** | Classified as Influencer when campaign names or UTM parameters contain `influencer` or `partnership` and the visit does not match a supported advertising platform first. |
| **Amazon - Ads and Organic** | Classified as Amazon - Ads and Organic when attributed to a connected Amazon Marketplace integration. |
| **Meta Shops / TikTok Shops** | Classified as Meta Shops or TikTok Shops when orders are attributed to a connected Meta Shop or TikTok Shop storefront. Organic storefront orders are categorized separately as **Meta Shops (Organic)** or **TikTok Shops (Organic)**. |
| **Discount Site** | Classified as Discount Site when the referring site, `utm_source`, or campaign matches a known coupon or deal site such as Honey, RetailMeNot, Rakuten Ebates, Slickdeals, Knoji, and similar services. |
| **Transactional** | Classified as Transactional for visits originating from checkout or post-purchase services such as Afterpay, Klarna, Shop, PayPal, Narvar, and Returnly. |
| **Organic Search** | Classified as Organic Search when the referring site is a recognized search engine, including Google, Bing, Yahoo, DuckDuckGo, Yandex, and similar providers. |
| **Organic Social** | Visits from social referral domains without paid advertising signals. These appear as individual platform values, including **Facebook Organic**, **Instagram Organic**, **TikTok Organic**, and **YouTube Organic**, based on the referring site. |
| **Organic** | Classified as Organic for direct visits with no tracked source. |
| **Unattributed** | Activity Northbeam could not tie to a specific source. |
| **Other** | Anything that does not match a known platform definition. |
> **Note:** Platform definitions are maintained by Northbeam and updated over time as new advertising platforms, integrations, and tagging conventions emerge.
***
### "**Category (Northbeam)" **
Channels are grouped by a higher-level category. For example, Paid Prospecting, Paid Performance Max, Paid branded Search, SMS, Affiliate, etc.
We normally don’t edit the groups of this breakdown since our view-through model uses these pre-set categorizations for the weighting in our Clicks + Modeled Views model.
***
### "**Targeting (Northbeam)"**
Channels are grouped by their targeting. For example, Paid Branded Search, Paid Shopping, Paid Display, Paid NonBrand Search.
***
### "**Revenue Source (Northbeam)"**
Channels are grouped by their source. This breakdown only has two groups:
* **Online Store** - orders from your Shopify Connection or Server API Connection
* **Amazon - Ads and Organic** - orders from your Amazon Integration (if relevant)
***
Want to see the segments of our Default Breakdowns?
At the bottom of this page, see the segments for each of our default breakdowns. Our system categorizes your campaigns based on predefined rules.
## Making a Custom Breakdown
You may have a specific breakdown in mind that doesn't align with our defaults. You can easily create custom breakdowns using our **Breakdown Manager**.
Learn how to use our Breakdown Manager below. Find timestamps within the video as well.
### What the video covers
The video above walks through:
* Creating breakdowns from scratch
* Using campaign names, UTM parameters, platforms, and custom spend sheet values as breakdown logic
* The difference between the Simple Editor and Advanced Editor
* Previewing matched campaigns before saving rules
* Creating manual label overrides
* Duplicating and customizing Northbeam's default breakdowns
* Common breakdown use cases such as funnel stages, regions, products, and high-level marketing buckets
***
## Editing a Default Breakdown
Want to make a slight tweak to a default breakdown? No problem. Instead of creating a new breakdown, here's how to edit an existing one.
### Step 1: Open [Breakdowns](https://dashboard.northbeam.io/breakdowns)
1. In the upper right corner, click **☰**
2. Click **Manage Breakdowns**
You'll be taken to the tab called **Manage Breakdowns**. This is where you can see and manage all of the breakdowns in your account. What you have to do is create a new breakdown and **name it the exact same name** as the default breakdown you want to edit — more on that in Step 2.
As a reminder, here are our default breakdown names:
* **Platform (Northbeam)**
* **Targeting (Northbeam)**
* **Revenue Source (Northbeam)**
* **Category (Northbeam)** - **NOTE: Please do not edit this breakdown**. Our MTA models (Clicks-Only and Clicks + Modeled Views) uses its breakdown assignments to determine how much weight specific channels receive. Editing could result in data inaccuracies.
### Step 2: Click Add Breakdown and name it the same as the default breakdown you'd like to edit.
**For example**, to edit our default Platform breakdown, name your new one **Platform (Northbeam)**.
### Step 3: From here, any edits made will reflect in the default platform breakdown.
## Default Breakdown Segments
### Segments for Platform (Northbeam)
Below is a list of our most commonly-used segments:
* Facebook Ads
* Google Ads
* YouTube Ads
* TikTok Ads
* Pinterest Ads
* Snapchat Ads
* Twitter Ads
* Amazon Ads and Organic
* Organic
* Organic Search
* Facebook Organic
* Klaviyo
* Unattributed
* Excluded
* Other
### Segments for Category (Northbeam)
Below is a list of our most commonly-used segments:
* Paid - Prospecting
* Paid - Performance Max
* Paid - Nonbranded Search
* Paid - Other
* Paid - Branded Search
* Paid - Awareness
* Organic
* Organic Search
* Email
* Unattributed
* Other
* Organic Social
* Affiliate
### Segments for Targeting (Northbeam)
Below is a list of our most commonly-used segments:
* Paid - Prospecting
* Paid - Nonbranded Search
* Paid - Branded Search
* Paid - Smart Shopping
* Paid - Other
* Paid - Video
* Paid - Retargeting
* Paid - Display
Important: Renaming an existing breakdown is treated as creating a completely new breakdown internally.
Renaming or deleting breakdowns that are already being used in saved views, dashboards, MMM models, or other reporting workflows can cause:
* Saved view errors
* Missing or broken dashboard tiles
* MMM/model segmentation issues
* Previously configured reports to stop working correctly
We strongly recommend avoiding renaming or deleting actively-used breakdowns unless absolutely necessary. If you need to make major changes, consider creating a new breakdown instead.
If you're unsure whether a breakdown is being used elsewhere in your account, please contact Support before making changes.
Please reach out to your Media Strategist, Customer Success Manager, or contact [Support](https://www.northbeam.io/submit-a-support-ticket) if you have any questions.
# Metrics Explorer Home Page
Source: https://docs.northbeam.io/docs/metrics-explorer
Understand the power of Northbeam's correlation visualization dashboard.
Want the TL;DR? Read our ["Metrics Explorer Quick Start Guide."](/docs/metrics-explorer-quickstart-guide) 🚀
Ready to master Metrics Explorer? [Read our Best Practices Guide.](/docs/metrics-explorer-best-practices-7-tips) 🤘
## What is Metrics Explorer?
**Watch this video for the full tour and explanation!**
**Metrics Explorer is a dashboard that demonstrates the direction and intensity of relationships between your marketing metrics over time.** It gives you confidence in understanding how specific ad campaigns, spending flights, or performance trends are affecting other parts of your marketing strategy. Metrics Explorer is built on the Pearson Correlation Coefficient, a widely-trusted statistical model (more on this below).
**Metrics Explorer can help you understand how your marketing strategies have affected specific outcomes.** For example, Metrics Explorer could demonstrate that over the last 90 days, there is a moderately strong relationship between your Facebook Spend and your Google Branded Search Revenue.
**You can measure these correlations over unlimited time periods, a variety of attribution models, and lookback windows, daily/weekly/monthly granularity, and even accrual or cash accounting modes.** Metrics Explorer also features customizable views you can save and export, making reporting a breeze. Like all of your Northbeam dashboards, this one is powered by your unique first-party data.
**Metrics Explorer is available to all Northbeam users.** Enterprise-tier Northbeam users have access to multiple correlations at once - contact our sales team if you are interested in upgrading to Enterprise.
## Where is Metrics Explorer?
Open [Metrics Explorer](https://dashboard.northbeam.io/metrics-explorer), or click the telescope icon in the left-hand navigation bar.
## When should you use Metrics Explorer?
**Whether you're analyzing past performance or planning future experiments, Metrics Explorer makes it easy to understand how your different marketing strategies are impacting each other.** For example: it is well-known in digital marketing that advertising spend will increase Amazon revenue, even if those ads don’t run on Amazon. This is because customers will often learn about a product on a different channel (like Facebook) then decide to purchase it on Amazon for faster shipping.
**With Metrics Explorer, you can measure that correlation scientifically and understand exactly how strong the relationship is between your ad spend and Amazon revenue.**
**Knowing the relationships between your metrics can give you confidence in whatever strategic decisions you intend to make.** For example, you may have a suspicion that your Google Ads spend is not improving your revenue, and you might want to cut that spend. Before doing so, you could use Metrics Explorer to evaluate the relationship between your Google Ads spend and other important metrics like transactions, revenue, or even engagement metrics like video views or email signups. You may discover that while your Google Ad spend doesn’t affect your revenue, cutting it would have a strong negative impact on your Google email signups, or other leading indicator.
**This understanding gives you insights into the potential impact of any choice you make.** The most sophisticated users of Metrics Explorer seek to understand how any budget adjustments, media flights, and new channel tests affect other parts of their business – even on metrics that might not seem immediately obvious.
Remember: correlation doesn’t imply causation. Read more on this below.
## How does Metrics Explorer work?
As mentioned above, Metrics Explorer uses the [Pearson Correlation Coefficient (PCC)](https://en.wikipedia.org/wiki/Pearson_correlation_coefficient), a statistical and mathematical model that measures the linear relationship between two sets of data. The Metrics Explorer dashboard makes it easy to apply the PCC to your Northbeam data by making a modular customizable dashboard to run these correlations on any data set you have in Northbeam.
### Understanding Pearson Correlation Coefficient
The [Pearson Correlation Coefficient](https://en.wikipedia.org/wiki/Pearson_correlation_coefficient) is a well-known statistical analysis that marketers have used for generations. What makes Metrics Explorer special is that it allows you to easily compare Northbeam first-party data.
**The PCC will measure two variables and give an output between -1 and +1.**
* Values close to +1 indicate a strong positive correlation
* Values close to -1 indicate a strong negative correlation
* Values close to 0 indicate little to no correlation (neutral)
The sign shows the direction, while the magnitude shows the strength of the relationship. Understanding the “direction” of the relationship can be a little tricky - but Metrics Explorer makes it easy.
## How to interpret Metrics Explorer results
Metrics Explorer uses the PCC to measure and visualize the relationship between two variables.
**Metrics Explorer visualizes this by identifying your “primary metric” (highlighted in purple) and the “target metric” (which features a correlation score.)**
1. Revenue (1st time) - This is the primary metric, highlighted in purple.
2. Spend: Facebook Ads - This is the target metric.
3. +0.53 - This is the correlation score.
4. Strong Positive - This is the relationship tag based on the correlation score.
Metrics Explorer tags each result with a relationship label to make it easier to understand. The labels are:\*\*
| Correlation Type | Definition |
| :- | :- |
| **Very strong negative** | As the primary metric increases, the target metric almost always decreases significantly. |
| **Strong negative** | When the primary metric goes up, the other tends to go down consistently. |
| **Moderate negative** | There’s a noticeable tendency for the target metric to decrease as the primary metric increases. |
| **Weak negative** | There’s a loose pattern where the target metric decreases slightly as the primary metric increases. |
| **No relationship** | Changes in the primary metric don’t predict changes in the target metric. |
| **Weak positive** | There’s a slight tendency for both metrics to increase together. |
| **Moderate positive** | As the primary metric rises, the target metric tends to increase, though not always. |
| **Strong positive** | When the primary metric goes up, the target metric usually increases too. |
| **Very strong positive** | Both metrics almost always rise together in sync. |
### Understanding correlation vs. causation
**"Correlation does not imply causation" is a fundamental principle in statistics and scientific research.** It means that just because two variables are related or appear to change together, it doesn't necessarily mean that one causes the other.
Just because Metrics Explorer is demonstrating a relationship, it doesn't mean that one metric is the reason another metric changed. It also doesn't mean that a future relationship is guaranteed.
**Example: Ice cream sales and drowning rates both increase in summer.** They're correlated, but one doesn't cause the other. The common cause is warmer weather — and trips to the beach!
Understanding that correlation is **not** equal to causation is crucial for critical thinking, scientific research, and avoiding logical fallacies in data interpretation.
Metrics Explorer allows you to have confidence in identifying the relationships between metrics, but there could be any number of factors that actually drive causation. This principle reminds us to be cautious when interpreting data and to look for additional evidence before concluding causal relationships.
### Example interpretation
Let's put this into marketing terms. Below is a set of tiles set over 60 days of data.
**In this example, we've chosen Facebook Spend as our primary metric, identified by it's purple highlight and caption.** This means all other metrics tiles visible are showing their correlations to Facebook Spend, the primary metric.
We can see that Attributed Revenue had a strong positive correlation with Facebook Spend in this time period. That means that during this time period, as Facebook Spend went up, so too did Attributed Revenue.
**We can also see that Customer Acquisition Cost (CAC) has a strong negative relationship over this timeframe.** In the case of CAC, this is a good thing - we want CAC do go down. Negative does not necessarily mean bad - these nuances are important to understand if you want to leverage the full power of Metrics Explorer.
You'll note that we've added some custom metrics to this view. "Lower Funnel Organic Visits" is a custom filtered metric summarizing organic visits across platforms. See the filter below.
As you can see from the yellow "No relationship" tag, Lower Funnel Organic Visits had no relationship over this timeframe, meaning that increases in Facebook Spend did not drive significant changes in this metric. However, "Lower Funnel Revenue," our custom filtered metric tracking revenue on these same channels, showed a strong positive relationship.
**This suggests that increased Facebook Spend drove attributed organic revenue - a big signal in understanding the halo effect of your paid ads on organic results.**
You can use the same tiles but select a different primary metric in order to see how these relationships change against each other. Using the same set of metrics, we've now selected average order value (AOV) as our primary metric.
**Notice how all the tiles change to demonstrate their relationship against AOV.**
**It's critical for marketers to validate every assumption they have with data.** This creates trust in your metrics, making it easier for you to evaluate the right choices for your boss, your stakeholders, your clients, and your own team.
**In this example, it's clear there's a strong positive relationship between AOV and CAC.** This means as AOV goes up, so does CAC. This makes sense - perhaps ads offering higher AOV bundles of products are less likely to draw in customers, meaning acquisition costs rise.
**There's also a weak negative relationship between AOV and Lower Funnel Organic Visits.** This makes sense, too - AOV is more a function of product price, discounting, and bundling than visits.
**For Attributed Revenue, there's a strong negative relationship with AOV.** This probably means the business is running some sort of discount through this time period - how else would the AOV be going up while revenue is going down?
**As you can see, Metrics Explorer can help you understand, discover, and report on hidden relationships throughout all your metrics.**
## Access to Metrics Explorer
**Metrics Explorer is free for all Northbeam users.** However, because significant data processing costs are related to more complex correlations, only Enterprise-level Northbeam users can access multiple correlations at one time (as seen in the example above.)
Want to see multiple correlations at the same time? Talk to our team about upgrading to Enterprise to unlock the full power of Northbeam.
## ✅ What's next?
This Metric Explorer dashboard is a powerful tool in Northbeam, and learning this information will help you understand how different marketing metrics are connected over time.
You can review the [Metric Explorer Quickstart Guide](/docs/metrics-explorer-quickstart-guide) or [Metric Explorer's 7 Best Practices](/docs/metrics-explorer-best-practices-7-tips), or you can head into the next section where we'll cover key strategies and recommendations that will help you get the most out of Northbeam.
# Metrics Explorer Best Practices: 7 Tips
Source: https://docs.northbeam.io/docs/metrics-explorer-best-practices-7-tips
Pro tips for using the Metrics Explorer dashboard in Northbeam.
Looking for pro tips on using Metrics Explorer? Here are some ideas from our Media Strategy team.
**1. Always use at least 30 days of data to ensure statistical significance.** The statistical model powering Metrics Explorer is just that - a model. The more data you feed it, the more effective it will be. If you use less than 30 days of data, you're likely to over-credit correlations that may look weaker over longer time frames. We also know that marketing has a lagging effect on revenue, visits, and other performance. Too short of a time frame can result in confusing or misleading results.
**2. Remember, correlation doesn't imply causation.** What this means is that while you might see strong correlations between your metrics, this isn’t a guarantee that the future behavior of those metrics will be the same. This isn’t a limitation of Metrics Explorer - this is a limitation of all statistical analysis. Tools like the Pearson Correlation Coefficient are designed to give us an idea about what has happened and what could happen. It is impossible to predict the future - we can only make extremely educated guesses. The wisest marketers use a combination of statistics, historical data, and industry knowledge when interpreting results or forecasting the future. Metrics Explorer can be a critical part of that measurement framework.
**3. Use Metrics Explorer to explore channels that feel misunderstood (or under-measured.)** TikTok, YouTube Ads, and CTV - these are all channels that struggle with typical Meta-style direct response measurement. Use Metrics Explorer to evaluate these higher-funnel, impression-based channels. As you spend more on those channels, how does that correlate with metrics like first-time revenue? What about revenue on your lower-funnel channels like Google and Meta?
**4. Prioritize strong positives and strong negatives when interpreting results.** It’s difficult to get strong positive or negative relationships with the PCC model, so strong positive and negative relationships are the most trustworthy and effective for measuring what actually happened. Moderate or weak relationships are more likely to have been influenced by unseen variables - use your own judgment when evaluating those results.
**5. Use Metrics Explorer to evaluate what you think you already know.** This allows you to create a strong foundation of learnings to iterate against. Certain relationships may seem obvious (like ad spend’s impact on transactions). With Metrics Explorer, you can prove those relationships with data instead of anecdotal experience. Whether you’re presenting to your boss or to your clients, establishing trust in your data is paramount. By demonstrating with data what your team already "knows,” you can further validate Northbeam’s data.
**6. Remember that Metrics Explorer demonstrates what has happened, not what will happen.** Past performance is no guarantee of future results. However, it doesn’t mean you can’t make an educated guess based on past variables. If all else holds true, and you don’t change anything else in your strategy, you can have confidence that the relationships in Metrics Explorer can be assumed for future results. On that note:
**7. Use Metrics Explorer alongside a calendar to tighten up your analysis.** Maintain a “changelog” where you write down all big changes you make, experiments you launch, or other variables like product drops or major promo periods. You want to isolate periods of time where the two metrics you’re comparing are mostly untouched by other variables. Measuring a correlation between spend and revenue would be affected by a product drop in the middle of that date range, for example. Working alongside a calendar of important dates can help you identify why relationships are - or aren’t - appearing in the data.
Looking for more hands-on help? [Return to our Metrics Explorer Quick Start Guide.](/docs/metrics-explorer-quickstart-guide) 🚀
# Metrics Explorer Quickstart Guide
Source: https://docs.northbeam.io/docs/metrics-explorer-quickstart-guide
First time using Metrics Explorer? Start here.
Below is a step-by-step guide to help you run your first-ever Metrics Explorer correlation analysis. Follow along with each step and you'll finish this process with a real insight!
### Step 1: Open [Metrics Explorer](https://dashboard.northbeam.io/metrics-explorer) in the Northbeam dashboard.
Click the telescope icon on the navigation bar on the left to find Metrics Explorer.
### Step 2: Select the first "quick start" link at the center, titled "Revenue (1st time) & Spend by Platform."
These quick links are designed to help you get started fast, and contain ideas from our most common correlation analyses. Feel free to start with these and customize them to your specific needs.
### Step 3: Adjust your filters and attribution windows.
For this example, let's select:
* **Accounting mode:** Accrual
* **Attribution model & window:** First Touch, 60 days
* **Granularity:** Daily
* **Time period:** 60d (60 days)
Once you choose these filters, the correlation tiles will update. This selection of filters will help us identify which spend on these channels is driving strong [first-touch](/docs/attribution-models) revenue.
### Step 4: Analyze your results!
Next, let's look at the correlation tiles in this example from a real business.
**In this example, you can see that over the last 60 days, given a large first-touch lookback window, 1st time revenue is very strongly positively related to Amazon Ad spend.**
To a lesser degree, there's a similar relationship with Facebook Ads spend. There's no correlation between revenue and spend on Neon Pixel, Google Ads, Or TikTok for this business over this time period.
Which relationships exist in your dataset?
**But it may feel backwards to see how "spend" changes against revenue.** Let's check this relationship from both angles.
### Step 5: Click a different metric to see the relationships from a different angle.
**Click the correlation tile of the most strongly correlated metric in your dataset.**
In the example, I would click the "Spend: Amazon - Ads and Organic" tile, as seen in this image. This changes "Spend: Amazon - Ads and Organic" into the primary metric, meaning all the other tiles now show their correlations to this metric instead of the original tile (Revenue 1st time.)
**As we can see, there's a very strong positive relationship between Revenue (1st time) and Amazon Ads spend.**
**This analysis suggests that increases in Amazon Ad spend will drive up first-time revenue.** However, it doesn't guarantee that result - remember, correlation does not imply causation.
When interpreting correlations, be sure to examine every relationship from multiple angles, metrics, and perspectives. This helps to prevent you falling into the "correlation does not imply causation" fallacy and strengthens your analysis. It's good statistical practice!
### Step 6: Look at the charts to identify visual trends.
Looking at the chart visuals can assist you in validating the relationship between metrics - and identifying outlier moments you might need to account for.
In this visual, we can see a few strong outliers. The green line, which represents TikTok Spend, dropped to zero for several days in September. This suggests that while there doesn't appear to be any relationship, the TikTok data isn't very consistent either. This is worth deeper analysis to understand how TikTok spend actually affects revenue.
The Amazon spend, however, saw a huge spike around October 9. This could be an early Prime Day sale. The major success on that specific day could be enough to influence the whole analysis.
When using Metrics Explorer, be sure to have access to the wider context of your marketing strategy. Know what product launches, promotional periods, or holidays might exist in your selected time range. This can help you limit [confounding variables](https://en.wikipedia.org/wiki/Confounding).
### Step 7: Save your view for easier access later.
In the top right hand corner of the Metrics Explorer screen, select "Save -> Save as new" to save your existing view for future reference.
### Congratulations! You just made your first analysis on Metrics Explorer!
Let's look at some best practices next.
# Mixed Media Modeling (MMM)
Source: https://docs.northbeam.io/docs/mixed-media-modeling
Measure the long-run contribution of each channel to revenue using time-series regression, independent of pixels and user-level tracking.
## What MMM is
Mixed Media Modeling (MMM) uses time-series data to build a regression model that predicts marketing outputs (sales, revenue) from marketing inputs (spend by channel, over time). Where MTA reads individual user journeys, MMM steps back and looks at the whole business over weeks and months.
At its simplest, MMM predicts a "Sales" time series from the spend time series of each channel:
| Date | Facebook Spend | TikTok Spend | (etc.) | → | Sales |
| - | - | - | - | - | - |
| Jan 1 | \$3,283 | \$570 | … | | 2,381 |
| Jan 2 | \$2,193 | \$112 | … | | 4,291 |
A naive model would assume "correlation implies causation," which isn't generally true. Good MMM reduces that reliance by explicitly modeling confounding variables, for example promotional periods and seasonality, to avoid drawing the wrong conclusion from a coincidental pattern.
## Why MMM matters
* **It doesn't depend on pixels or user-level tracking.** MMM works from aggregate spend and revenue, so it's resilient to iOS privacy changes and cookie deprecation, the same signal loss that gives MTA blind spots.
* **It captures long-run and cross-channel effects.** Brand and upper-funnel channels that MTA under-credits (because their impact shows up later and diffusely) are visible in the time series.
* **It's built for strategic budget planning.** MMM answers "how much does each channel contribute over time," which is the right question for setting a media mix, where MTA answers "what touched this customer" for day-to-day optimization.
## How MMM relates to MTA and Incrementality
Northbeam treats these three as complementary measurement methods, each with different strengths:
* **MTA** — event-log analysis. Best for channel-level optimization and attribution. Correlational.
* **MMM** — time-series regression. Best for strategic budget planning. Correlational, and slower to update.
* **Incrementality** — controlled experiments. The causal ground truth. Best for validating and calibrating the other two.
They disagree by design, because they measure different things. The value comes from reading them together: incrementality results calibrate MMM's estimates, and both inform how much to trust MTA at the channel level.
## Limitations to keep in mind
* MMM is based on historical patterns, so it updates more slowly than attribution and reacts to recent changes with a lag.
* It reports at the channel and business level, not the campaign or ad level. Use MTA for that granularity.
* Model quality depends on having enough history and clean spend/revenue data.
# Multi-Dashboard Setup with Configurators
Source: https://docs.northbeam.io/docs/multi-dashboard-setup-with-configurators
Split your data across multiple Northbeam dashboards — while maintaining first-party tracking on a single domain
## Overview
By default, each Northbeam dashboard is linked to one domain. But there are situations where you want **multiple dashboards tied to a single top-level domain** — for example, if you operate multiple regions or brands all living on one site.
Northbeam supports this through **Configurators**: a setup that captures all events on your single domain, then intelligently routes pixel events and orders to the correct dashboard based on rules you define.
This is how Northbeam handles multi-region setups where all regions share one domain (e.g. `mystore.com/us`, `mystore.com/uk`, `mystore.com/de`). Instead of being forced into a single blended dashboard, you can maintain clean, separate reporting per segment — without sacrificing first-party tracking.
**Configurators are built and managed by the Northbeam team on the backend — but you'll need to provide the logic.**
The fields in this doc are what you'll need to define and share with your CSM before setup can begin. Not available to all customers. Reach out to your CSM to get started.
***
## Setup Process
**Getting the Pixel Configurator right from the start is critical.**
Once data starts flowing into your child dashboards, changing the routing logic mid-stream can create data inconsistencies and require re-validation. We strongly recommend taking the time upfront to define your pixel, orders, and breakdown logic correctly — even if it means a slightly longer implementation timeline.
Before setup begins, you'll need to define and share three things with your CSM:
1. **Pixel config logic** — which fields and values should route front-end events to each child dashboard (e.g. page path `/uk` → UK dashboard)
2. **Orders config logic** — which fields and values should route orders to each child dashboard (e.g. shipping country = `GB` → UK dashboard)
3. **Breakdown label criteria** (if applicable) — the campaign naming conventions used to filter ad spend per segment (e.g. campaigns beginning with `UK_` → UK dashboard)
Once you've provided this, the Northbeam team handles the rest:
1. **Configurator Implementation** - the Pixel Configurator, Orders Configurator, and Breakdown labels on the backend.
2. **Data validation** — the Northbeam team works closely with you to verify data is splitting correctly across all parent and child dashboards before go-live. This is where we ensure data fidelity and catch any routing issues before they impact your reporting. Timeline varies by complexity, but we prioritize getting it right over rushing go-live.
***
## How It Works: Parent and Child Dashboards
When Configurators are enabled, your dashboards are structured as **parent** and **child** dashboards.
* The **parent dashboard** receives all events from your domain — it acts as the blended, top-level view.
* **Child dashboards** each receive a subset of events, split according to the logic you define.
**Examples:**
| Setup | Structure |
| - | - |
| 1 main store + 1 regional store | 1 parent + 1 child |
| 5 regional storefronts on one domain | 1 parent + 5 children |
Every event is captured at the parent level first, then distributed to the appropriate child dashboard based on matching logic. This ensures first-party tracking is maintained across the entire domain while giving you clean, separated data per segment.
***
## The Two Configurators
### 1. Pixel Configurator
The Pixel Configurator routes **front-end events** to the correct child dashboard. This includes:
* Page view events
* Purchase events
* Any custom goal events you have set up
Routing is based on logic rules applied to the following fields. Multiple conditions can be used simultaneously — if an event matches more than one rule, the priority order you define determines which rule takes precedence.
| Field | Description |
| - | - |
| `page_path` | The URL path of the page (e.g. `/us/checkout`) |
| `page_path_regex` | A regex pattern matched against the page path |
| `geo_country_code` | The visitor's country code, resolved by IP |
| `datalayer_region_code` | A region code pushed to the browser's data layer |
| `page_utm_params` | UTM parameters present in the page URL |
| `datalayer_currency_code` | Currency code pushed to the browser's data layer |
| `page_domain` | The domain of the page (useful for subdomain splits) |
***
### Using Local Storage for Region and Currency Codes
Page path-based routing is the most common approach, but it can get complicated — especially when the URL changes between the storefront and checkout. For example, a customer might browse `store.com/uk` but land on a checkout URL that no longer contains `/uk`, causing the pixel to lose track of the segment.
In these cases, the cleaner approach is to use **local storage codes** that persist across the entire session, regardless of URL changes.
Northbeam supports two local storage fields:
* `nb__region_code` — maps to the `datalayer_region_code` pixel config field
* `nb__currency_code` — maps to the `datalayer_currency_code` pixel config field
**For Shopify stores**, Northbeam provides the following script which automatically sets these values using Shopify's built-in localization variables. Add this to your Shopify theme:
```html theme={null}
```
**For non-Shopify stores**, you can use a custom script to set the same local storage items — but you'll need to make sure the correct region or currency values are being passed in. The key names (`nb__region_code` and `nb__currency_code`) must match exactly.
***
### 2. Orders Configurator
The Orders Configurator routes **order data** to the correct child dashboard. The available logic fields differ slightly depending on whether you're using Shopify or the Orders API.
#### Shopify
| Field | Description |
| - | - |
| Shopify URL | The specific Shopify store URL the order came from |
| Country code of shipping address | The destination country of the order |
| Order tag contains | Matches orders with a specific tag |
| Customer email | Routes based on customer email address |
| Order value | Routes based on the order total (greater than / less than) |
| Order date | Routes based on order date (greater than / less than) |
#### Orders API
| Field | Description |
| - | - |
| Country code of shipping address | The destination country of the order |
| Order tag contains | Matches orders with a specific tag |
| Customer email | Routes based on customer email address |
| Order value | Routes based on the order total (greater than / less than) |
Date-based logic (`order date`) is currently only available for Shopify and has not yet been built for the Orders API.
***
## Breakdown Labels
Breakdown labels are only required if you have a **shared ad account** across segments. If each segment has its own dedicated ad account, you can skip this.
When a shared ad account is connected to multiple child dashboards, all campaigns from that account will appear in every dashboard by default. Breakdown labels filter each dashboard's ad view down to only the campaigns relevant to that segment.
**How it works:**
* Each segment dashboard gets a custom Breakdown label based on your campaign naming convention (e.g. the UK dashboard is configured to show only campaigns beginning with `UK_`)
* Northbeam sets up these labels as part of the implementation process
* The requirement is that **all campaigns follow a consistent naming convention** — without it, there is no reliable way to filter spend by segment
**Consolidated campaigns** that aren't segment-specific (e.g. a brand-wide awareness campaign) require a decision: include in all dashboards, one dashboard, or exclude entirely.
**Breakdown labels are based entirely on naming conventions.**
If your campaigns aren't named consistently, spend cannot be cleanly split by segment regardless of how your pixel and orders are configured.
***
## Pixel Config Constraint: Ad Traffic Must Land on a Matching URL
This constraint applies when routing is based on **page path or subdomain**. It does not apply if you're using `geo_country_code` or local storage-based routing (`datalayer_region_code`, `datalayer_currency_code`).
**The constraint:** Each child dashboard only captures traffic from URLs that match its pixel config logic. If an ad sends a visitor to a URL that doesn't match the segment's configured path — such as a shared homepage — that visit and any resulting conversion will **not** be attributed to that segment's dashboard.
**Example:**
* Your UK segment dashboard is configured to capture traffic on `store.com/uk`
* A UK ad sends a visitor to `store.com/` (the homepage) instead
* That visit is not captured by the UK dashboard — the conversion appears unattributed or lands in the parent dashboard only
**How to avoid this:**
* Ensure all ads for a segment point to that segment's configured URL path or subdomain
* Or consider using local storage-based routing (`datalayer_region_code`) or `geo_country_code` — both of which are URL-independent and not affected by this constraint
***
## Is This Right for You?
**Good fit:**
* Segments have distinct page paths, country codes, order tags, or other supported fields that cleanly map to one dashboard
* No ambiguity — an event or order could not reasonably belong to more than one segment
* All ads for each segment send traffic to that segment's configured URL
**Not a good fit:**
* Shared ad accounts with no campaign naming convention (ad data cannot be split)
* Split logic doesn't map to any supported fields
* Events or orders overlap across segments
* Ads send traffic to shared URLs that don't match any segment's configured path
Configurators must use the supported fields listed above — the split cannot be based on arbitrary criteria. If your setup can't be expressed through those fields, a Configurator setup may not be possible.
***
## Setup Process
Before setup begins, you'll need to define and share three things with your CSM:
1. **Pixel config logic** — which fields and values should route front-end events to each child dashboard (e.g. page path `/uk` → UK dashboard)
2. **Orders config logic** — which fields and values should route orders to each child dashboard (e.g. shipping country = `GB` → UK dashboard)
3. **Breakdown label criteria** — the campaign naming conventions used to filter ad spend per segment (e.g. campaigns beginning with `UK_` → UK dashboard)
Once you've provided this, the Northbeam team handles the rest:
1. **The Northbeam team implements** the Pixel Configurator, Orders Configurator, and Breakdown labels on the backend.
2. **Data validation** — the Northbeam team works closely with you to verify data is splitting correctly across all parent and child dashboards before go-live. Timeline varies by complexity.
***
## Frequently Asked Questions
**Can I see a blended view across all my child dashboards?**
Yes — the parent dashboard always shows a blended view. You can also combine dashboards into a rollup for a consolidated view.
**Is there a limit on child dashboards?**
No hard limit, but more child dashboards means a more complex setup and validation process. Your CSM can help you assess what makes sense.
**Can I modify the configurator logic after go-live?**
Changes require involvement from the Northbeam implementation team. Reach out to your CSM if you need to update your routing rules.
**What if an event matches more than one rule?**
The priority order defined during setup determines which rule takes precedence.
***
## What's Next
* **Ready to get started?** Contact your CSM.
* **Not sure if you need this?** See [Setting Up Multiple Stores or Regions](/docs/adding-a-store-or-dashboard).
* **Questions?** [Submit a support ticket](https://www.northbeam.io/submit-a-support-ticket)
# Navigating Northbeam: Your Guided Ramp-Up
Source: https://docs.northbeam.io/docs/navigating-northbeam
Northbeam's step-by-step guided walkthroughs are meant to help you learn how to use Northbeam. We're trying to solve the biggest problem first-time users face: not knowing how to start and where to start.
We've structured this phase to walk you through the key features that you need to know in order to succeed in using our platform.
On Day 1 of your Northbeam usage, you'll be able to access certain attribution models and feature sets. As Northbeam continues to understand and ingest your data, other models and tools will unlock Day 30, Day 60, and Day 90. We call these timesteps "learning periods."
What Northbeam features are available on Day 1?
When you enter your platform, you will see your Default view: the Overview Home Page.
### Your [Overview Home Page](/docs/overview-page) includes:
* [Attribution Models](/docs/attribution-models)
* [Attribution Windows](/docs/attribution-windows)
* [Accounting Modes](/docs/accounting-modes)
### When you're familiar with the Overview Home Page, you can move on to the **[Attribution Page](/docs/attribution-page)** which includes:
* Sales
* Product Analytics
* Creative Analytics
* Orders
### Your third main page will be the **[Metrics Explorer](/docs/metrics-explorer)** Page
The default setting is on **Attribution Model**: Clicks-Only.
This is your go-to for offline channels or TV ads (Tatari or MNTN) since these efforts do not have Clicks data availability or Click-based traffic.
This is where Metrics Explorer comes in, too. Metrics Explorer answers the question: How do we measure the impact that this spend on these channels is having on certain metrics?
***
What feature will be available on Day 30? Day 60? Day 90?
The data in your Northbeam dashboard is ready to use on Day 1. However, certain attribution models and feature sets require a learning period of 30, 60, or 90 days before use.
Outlined below are our different features and their associated learning period.
### Northbeam **[Apex](/docs/northbeam-apex)**
* This is a feature that allows your Meta ads to learn based on the MTA data inside your Northbeam account.
* A **minimum 30 day** learning period is required before using this feature.
### **Clicks + Modeled Views** and **[Clicks + Deterministic Views (CDV)](/docs/clicks-deterministic-views)**
* These are Northbeam's proprietary multi-touch attribution model that processes Click and View data through our machine learning model to analyze top-of-funnel channels.
* These features requires a **minimum 30 day** learning period with **best results seen after 60 days**.
### **[Profitability Benchmarks](/docs/profitability-benchmarks)**
* This feature looks to establish good/bad numbers based on your specific business to help you manage your marketing spend more efficiently.
* A **minimum of 90 days** of data is required to establish reliable benchmarks.
While a large portion of Northbeam's platform is available on Day 1, you'll get the best use out of Northbeam after Day 90 when all of your learning periods have elapsed and Northbeam has a solid grasp on how your data behaves.
**The following guides show you what our platform looks like, what each page/feature is for, and how to use them to full effect.**
***
## Joining an existing account?
If you're stepping into an account your team already set up — with saved views and established workflows — start on the **Sales Page Dashboard**. It's your central hub for monitoring performance and exploring data, and where every function (Paid Social, Paid Search, Email/SMS/Retention, Offline Channel, Influencer, and Leadership) can find the insights they need.
* **Pre-saved views** — custom views for specific campaigns, roles, or reporting needs. Find them in the top-left dropdown of the dashboard.
* **Create custom views** — tailor the dashboard to your role by selecting the metrics that matter most (Spend, CAC, CPM, ROAS) and saving them for quick access.
# First-Time and Returning Data
Source: https://docs.northbeam.io/docs/new-vs-returning-data-1
Understand how Northbeam identifies first-time and returning visitors, customers, and subscriptions.
Northbeam is able to identify New and Returning visitors and orders. We offer three different kinds of New and Returning data:
* First-Time and Returning **Visitors**
* First-Time and Returning **Customers**
* First-Time and Recurring **Subscriptions**
| Type | How we define | Example Associated Metrics |
| :- | :- | :- |
| First-Time and Returning **Visitors** | Northbeam Pixel and Device Graph | New Visits, Visits |
| First-Time and Returning **Customers** | Customer ID | Transactions (1st Time), Transactions (Returning), Attributed Revenue (1st Time), Attributed Revenue (Returning) |
| First-Time and Recurring **Subscriptions** | Order Tags | Subscriptions (1st Time), Subscriptions (Recurring) |
## First-Time vs Returning Visitors
Our **Northbeam Pixel** uses a variety of inputs to create user profiles and track customer journeys across various devices and households. All of this information feeds into our backend device graph.
* **First-Time Visitor** - The Northbeam Pixel did not recognize any previous events from this user
* **Returning Visitor** - The Northbeam Pixel recognized previous event(s) from this user
## First-Time and Returning Customers
New and Returning Customers are based on **Customer IDs** and timestamps associated to each order.
* **First-Time Customer** - When an order has a Customer ID that doesn't exist on a historical order in Northbeam
* **Returning Customer** - When an order has a Customer ID that exists on a historical order in Northbeam
| Order Number | Date of Order | Customer ID | Customer Type | Reasoning for Customer Type |
| :- | :- | :- | :- | :- |
| 01 | Jan 1, 2024 | 1000 | First Time | ID doesn't exist on a previous order. |
| 02 | Jan 1, 2024 | 1001 | First Time | ID doesn't exist on a previous order. |
| 03 | Jan 2, 2024 | 1000 | Returning | ID exists on a previous order (Order 01). |
| 04 | Jan 3, 2024 | 1002 | First Time | ID doesn't exist on a previous order. |
| 05 | Jan 4, 2024 | 1001 | Returning | ID exists on a previous order (Order 02). |
For the most accurate New and Returning data...
1. **Backfill Historical Order Data** - It's important to backfill as much order data as possible so we have your entire customer base, along with their IDs.
2. *Note: This is primarily relevant for customers who are on a Custom setup (Shopify customers should already have historical data pulled in).*
3. **Consistent Customer ID formats** - Ensure that all of your Customer IDs are in a consistent format. This way could properly identify New and Returning Customers, or IDs.
4. *Note: Also primarily relevant for customers on a Custom setup (i.e. Shopify customers have Customer IDs automatically pulled in).*
## First-Time and Recurring Subscriptions
These are based on Order Tags. To learn more, reference [Subscription Analytics](/docs/subscription-analytics).
# Non-Integrated Channel Setup: Spend API + UTMs
Source: https://docs.northbeam.io/docs/non-integrated-channel-setup-spend-api-utms
### Overview
For platforms with native integrations (e.g., Meta, Adwords, TikTok, Pinterest, Snapchat), Northbeam fetches all your Campaign, Adset, and Ad data through our Standard API integration and reports it in your dashboard. We ingest all your metadata (e.g., Campaign, Adset, Ad IDs) to tie those sessions back to the ad that drove it — along with any conversions that occurred in that session.
But if you're using channels without a native integration — like Affiliates, Podcasts, Newsletters, Influencers, or Email — you can still achieve the same accurate, campaign-level reporting in Northbeam. It just takes a little extra setup.
***
### Expectation Setting
* **No view-through conversions** — only click-based models will be available (First Touch, Last Touch, LNDT, Clicks-Only)
***
### This is a 3-Step Process
1. **Send us your spend data** using the **Spend API**
2. **Attach UTM parameters** on your ad links that match the spend data
3. **Create a custom label in Northbeam to align the spend and revenue data**
This guide walks you through each of those steps.
***
## Step 1: Setting Up the Spend API
#### 1A: What is the Spend API?
The **Spend API** is how you **automatically send daily ad spend** to Northbeam from platforms we don’t connect with directly.
It lets you **send your own ad spend data** from your internal database (or your client’s) into Northbeam. It’s most commonly used for:
* Podcasts
* Newsletters
* Influencer campaigns
* Affiliate or email programs
* Any non-integrated channel
### Important Note!
This is *not* a plug-and-play integration. It’s an API endpoint — you’ll need a **developer** to set up automated POST requests that deliver your spend data.
***
#### 1B: How Do I Set Up The Spend API?
**Important Links:**
* [Spend API Docs](/reference/post_spend)
* Endpoint: `https://api.northbeam.io/v1/spend`
**Required Credentials** (find these under [API Keys](https://dashboard.northbeam.io/settings/api-keys) in the Northbeam dashboard):
* API Key
* Client ID
Settings > API keys
***
#### 1C: Required Fields in Your Payload
Each spend record must include the following fields:
* `date`
* `platform_name`
* `campaign_id`
* `campaign_name`
* `spend`
* `spend_currency`
### Impression and Clicks
Do *not* send `impressions` or `clicks`. These fields are reserved for future use and currently ignored.
***
#### 1D: Structuring `campaign_name`
If your goal is to measure performance beyond just the platform level — like **campaign-level**, **influencer-level**, or any custom grouping — then `campaign_name` is essential.
**It’s important to use the same values in `campaign_name` and `utm_campaign` (Step 2).**
This is how Northbeam ties your **spend** (via the Spend API) to your **traffic and conversions** (via UTMs).
The labels (Step 3) will match the spend and revenue by linking…
`campaign_name` from your Spend API payload
to
`utm_campaign` from your UTM parameters
***
#### 1E: What Values Should I Use?
You can technically use any values for `campaign_name`, but we **strongly recommend using a clean numeric ID** like `12345`.
##### Why Numeric Values Are Better Than Names
Using human-readable names like `Spring_Sale_2025` might feel more intuitive, but they often include **special characters** like spaces, `%`, `$`, or `#`.
When used in URLs (UTMs), those characters get **automatically encoded**, which creates mismatches — even if the values look visually similar.
For instance, a campaign named Holiday Sale \$50 CPA might be encoded as:\
utm\_campaign=holiday%20sale%20%2450%20cpa
This leads to:
* Broken label rules
* Unmerged Spend + Revenue rows — making it very challenging to see any metric that includes revenue and spend (ex. CAC, ROAS, etc.) at the campaign-level in the dashboard.
Our priority is clean, reliable data. While numeric IDs might not be the most user-friendly naming convention, they ensure your spend and revenue merge correctly — which is far more valuable than a broken report. That said, it’s ultimately your call.
**Example Payload Schema**
```json theme={null}
[
{
"date": "2025-07-20",
"platform_name": "email_marketing",
"campaign_id": "12345",
"campaign_name": "12345",
"spend": 135.50,
"spend_currency": "USD"
}
]
```
***
### 1F: Spend API Responses
| Status Code | Meaning |
| - | - |
| **201** | ✅ The spend records were successfully upserted. |
| **401** | ❌ Authentication failed (API key or Client ID is missing/incorrect). |
| **422** | ❌ Invalid request body — required fields may be missing or misformatted. |
| **4XX** | ❌ A generic client-side error occurred. |
| **5XX** | ❌ A server-side error occurred — contact Northbeam support. |
### If your request returns a `201` status, your spend data has been received and stored.
It will become visible in your Northbeam dashboard after the next data processing run.
You can always test your payload in a tool like Postman or with `curl` before setting up automated jobs — and confirm that you're receiving a `201` success response.
***
## Step 2: Setting up UTM Parameters
In Northbeam, UTMs are captured in real-time at the moment a visitor lands on your site. This tracking is handled by our pixel and **cannot be changed after the fact**, so it’s important to get your UTM setup right from the start.
#### 2A: **Required UTM Parameters**
* `utm_source`
* `utm_medium`
* `utm_campaign`
As long as `utm_campaign` matches the `campaign_name` from the Spend API, your spend and revenue will align correctly.
You can use any values for `utm_source` and `utm_medium`, but we recommend using the **platform name** for one or both fields to clearly indicate where the traffic came from. While not required, keeping these values consistent makes it easier to group and label performance data in Northbeam.
That said, if you already follow a specific structure for tools like Google Analytics, it’s totally fine to keep using it — as long as **each platform’s traffic can be uniquely identified** (e.g. with a distinct source + medium combo), you’ll be in good shape.
#### 2B: Other Requirements
* Make sure the [Northbeam Pixel](/docs/add-pixel#how-to-test-for-the-northbeam-pixel) is firing on your landing page
* Your landing page must be on the **same top-level domain** as the domain connected to Northbeam (for first-party tracking).
* Subdomains (like `shop.example.com` if `example.com` is connected) are fully supported
* To check your connected domain, open [Profile](https://dashboard.northbeam.io/settings/profile) in the Northbeam dashboard.
***
#### **UTM & Spend Field Mapping Example**
| **Source** | **Field** | **Example Value** | **Required?** | **Notes** |
| - | - | - | - | - |
| **Spend API** | `platform_name` | `influencer` | Yes | No strict match required, but aligning with `utm_source` if possible, is best practice |
| **Spend API** | `campaign_name` | `12345` | Yes, for campaign-level reporting | Must match `utm_campaign` exactly for spend + revenue to merge |
| **UTM** | `utm_source` | `influencer` | Recommended | Use platform name to help identify the traffic source |
| **UTM** | `utm_medium` | `affiliate` | Recommended | Helps distinguish traffic type (e.g. organic, paid, referral) |
| **UTM** | `utm_campaign` | `12345` | Yes, for campaign-level reporting | Must match `campaign_name` exactly for spend + revenue to merge |
***
## Step 3: Creating Custom Labels
Once your spend and UTM data are both flowing into Northbeam, you’ll see them appear in the dashboard — but initially, they will show up as **separate rows** in the Sales table.
This happens because spend data (from the Spend API) and revenue data (from UTMs) come in through different sources and aren't automatically grouped. As a result, performance metrics like ROAS and CAC will be split across rows and calculated incorrectly.
**Example of of Separate Rows:**
| Campaign Name | Spend | Visits | Revenue | Transactions | ROAS | CAC |
| - | - | - | - | - | - | - |
| influencer\_1 | \$100.00 | 0 | \$0.00 | 0 | 0.00 | \$0.00 |
| influencer\_1 | \$0.00 | 100 | \$500.00 | 5 | 0.00 | \$0.00 |
To consolidate spend and revenue into **one row**, you’ll need to create a **custom label** that groups them under a **shared identifier**. Once applied to your view, this label will allow you to see **merged metrics** — like ROAS and CAC — correctly.
***
#### 3A: Creating a New Breakdown Label
Follow these steps to build the label:
1. Open the [Sales page](https://dashboard.northbeam.io/sales) in your Northbeam dashboard.
2. Click the **three dots (…)** next to **Breakdown By**, then click **Manage Breakdowns**. You can also open [Breakdowns](https://dashboard.northbeam.io/breakdowns) directly.
3. Click **Add Breakdown**.
The rule logic depends on your data structure, but in most cases, you can use a single rule to group both spend and revenue sources.
**Here’s an example to show how to set it up:**
#### **📊 Example Data Structure**
| **Source** | **Field** | **Value** | Breakdown Field | Notes |
| - | - | - | - | - |
| **Spend API** | `campaign_name` | `12345` | `name` | Comes through as submitted |
| **UTM** | `utm_campaign` | `12345` | `name` | Comes through as submitted |
| **UTM** | `utm_source` | `influencer` | `utm_source` | Comes through as submitted |
| **UTM** | `utm_medium` | `affiliate` | `utm_medium` | Comes through as submitted |
| **Spend API** | `platform_name` | `influencer` | `adKey.Platform` | Formatted as `custom-spend-influencer` |
| | | | | |
#### 3B: Breakdown Rule Logic
Use **OR logic** to group matching revenue and spend sources:
| Field | Condition | Value | Purpose |
| - | - | - | - |
| `utm_source` | equals | `influencer` | Captures Influencer revenue |
| `adKey.platform` | equals | `custom-spend-influencer` | Captures Influencer spend |
#### 3C: Output Label Logic
The Output Label Rule is **how** the matching criteria will be labeled.
```
{{#functions.lower}}{{data.adKey.campaign}}{{/functions.lower}}
```
| **Part** | **Meaning** |
| - | - |
| `{{#functions.lower}}` | This opens a Handlebars block helper that applies the `lowercase` function |
| `{{data.adKey.campaign}}` | This pulls the value from the `adkey.campaign` field — which is matched from either: • `utm_campaign` (revenue) • `campaign_name` (spend) |
| `{{/functions.lower}}` | Closes the `lowercase` function block |
#### 🧾 Example Output (After Label Applied)
Based on the example logic above, once your label is applied, your data will be grouped like this in the **Sales** page:
| **Label** | **Spend** | **Visits** | **Revenue** | **Transactions** | **ROAS** | **CAC** |
| - | - | - | - | - | - | - |
| `12345` | \$100.00 | 100 | \$500.00 | 5 | 5.00 | \$20.00 |
Spend (from the Spend API) and Revenue (from UTMs) are now merged into a single row using the name value: 12345.
**Example in the UI**
***
### Optional: Make Your Breakdown Rule Logic More Flexible
`equals` requires an exact match — including case and spacing — which can be too strict for UTMs.
Instead, feel free to use use:
* **`contains`** – Matches if the value includes a substring\
*Example:* `utm_campaign contains 12345` matches `nb_12345_email_blast`
* **`matches regex`** – Best for case-insensitive and flexible matching\
*Example:*
```
(?i)influencer
```
This matches any version of `influencer` (e.g., `Influencer`, `influencer_campaign_1`)
Use "(?i)" for case-insensitive matching
***
## Step 4: Viewing Your Merged Data
Once you've created and applied your custom breakdown, you can now view your unified spend and revenue data in the Sales dashboard.
Here’s how to do it using the “Spend + Rev – Influencers” breakdown as an example:
1. Open the [Sales page](https://dashboard.northbeam.io/sales) in your Northbeam dashboard.
2. Click the dropdown next to **Breakdown By**, then **select your breakdown** (ex. "Spend + Rev – Influencers")
3. Click into the Influencer platform (or any relevant platform you're labeling).
4. Toggle the view to **Campaign-level.**
5. You should now see merged rows that align spend (from the Spend API) and revenue (from UTMs) under the same campaign name.
Your performance metrics — like ROAS, CAC, and Revenue — will now reflect accurate, fully merged data at the campaign level.
# Custom
Source: https://docs.northbeam.io/docs/non-shopify-installation
Set up Northbeam tracking on a custom store: any site that doesn't use Shopify's checkout.
Use this guide if your store does **not** use Shopify's checkout. That includes custom-built sites and other e-commerce platforms (for example, WooCommerce, Magento, or Salesforce). If your store uses Shopify's checkout, follow the [Shopify](/docs/shopify-installation) guide instead.
**Shopify checkout with a custom backend?** If your checkout runs on Shopify but your own system sends orders to Northbeam, this isn't the right guide. Follow [Shopify + Custom](/docs/shopify-custom-backend).
## What you'll set up
| Step | What it tracks | Needed? |
| :- | :- | :- |
| [1. Install the Northbeam Pixel](#1-install-the-northbeam-pixel) | Visits and page views on every page | **Required** |
| [2. Add a purchase event](#2-add-a-purchase-event) | Completed purchases | **Required** |
## Before you start
* **Plan:** Custom setup is available on Pro and Enterprise plans.
* **Developer:** You'll need someone who can add scripts to your site, either in its code or through Google Tag Manager.
* **Open your scripts.** Go to [Settings → Northbeam Pixel and Event Tracking](https://dashboard.northbeam.io/settings/tracking-script-tags). Your scripts are there, already filled in with your Client ID.
***
## 1. Install the Northbeam Pixel
The pixel must run on **every page** of your site. It records visits, where visitors came from, and the pages they view.
Copy the **Northbeam Pixel** from [Settings → Northbeam Pixel and Event Tracking](https://dashboard.northbeam.io/settings/tracking-script-tags).
Paste it into the `` section of your site's template, so it loads on every page.
Deploy or publish your site.
In Google Tag Manager, go to **Tags → New** and set **Tag Type** to **Custom HTML**.
Copy the **Northbeam Pixel** from [Settings → Northbeam Pixel and Event Tracking](https://dashboard.northbeam.io/settings/tracking-script-tags) and paste it into the HTML field.
Set the trigger to **All Pages**.
Click **Submit** to publish. Unpublished changes don't track anything.
**Don't change the script.** Paste it exactly as it appears in your dashboard.
If your site uses a CSP, its `connect-src` must allow your `i.` subdomain. Add either:
* `*.your-store.com`, or
* `i.your-store.com`
Use this script and replace `{DATA_CLIENT_ID}` with your Data Client ID, found under [API Keys](https://dashboard.northbeam.io/settings/api-keys).
```html theme={null}
```
***
## 2. Add a purchase event
Add a purchase event to your **Order Confirmation** or **Thank You** page. It tells Northbeam which orders to attribute.
Use `fireSlimPurchaseEvent`. It sends the order ID, which is all Northbeam needs. Order details like revenue come from your backend.
It must:
* Fire **after** the Northbeam Pixel loads
* Fire **once per order**. Refreshing the confirmation page must not fire it again.
* Use the **exact order ID** your backend sends to Northbeam
Full instructions, examples, field reference, and testing steps.
**Using a third-party checkout provider** that can't pass the order ID (for example, CheckoutChamp or CartHook)? Use [Identify Events](/docs/third-party-checkouts) instead.
***
## Test your setup
Check that you have:
* The **Northbeam Pixel** in the `` of every page
* A **purchase event** that fires once per order on your confirmation page
* Your **Google Tag Manager** container published (if you use it)
Then [test that the pixel is firing](/docs/add-pixel#how-to-test-for-the-northbeam-pixel) and [test your purchase event](/docs/purchase-pixel#validation-and-testing).
## Optional tracking
Add these only if they apply to your store.
Track other actions, like sign-ups, add-to-carts, or form submissions.
Only for single-page apps (for example, Next.js or React Router). Most sites don't need this.
## FAQ
Yes. Both the pixel and the purchase event can be added through Google Tag Manager. Make sure the pixel tag fires before the purchase event tag, and publish your container after every change.
Follow the [Shopify](/docs/shopify-installation) guide.
See [All Pixel Functions](/docs/optional-additional-methods).
# Northbeam 3.0
Source: https://docs.northbeam.io/docs/northbeam-30
## Northbeam 3.0: The New Northbeam Experience
Northbeam 3.0 is the next generation of the Northbeam analytics platform. It delivers significantly faster performance, a cleaner interface, and expanded analytical capabilities. Everything you rely on from Northbeam 1.0 is still available, now rebuilt for clarity, depth, and speed.
***
### Key Improvements in Northbeam 3.0
#### Faster Performance
Northbeam 3.0 is roughly twice as fast as 1.0 across dashboards, graphs, filters, and table interactions. The entire experience is more responsive, making daily analysis smoother and more efficient.
#### Easier to Use
Northbeam 3.0 introduces a redesigned interface that improves clarity and reduces interpretation effort.
**Usability upgrades include:**
* Tooltips embedded directly inside tables for Touchpoints, Revenue, ROAS, CAC, Visitors, and Customers
* First and returning customer splits shown consistently for context
* Clearer definitions for accrual vs cash reporting
* One click to switch between Northbeam 1.0 and Northbeam 3.0
* Streamlined table layouts, more intuitive navigation, and cleaner visual hierarchy
#### More Powerful Analysis
Northbeam 3.0 expands the number of metrics you can track and adds new ways to understand customer journeys and channel influence.
**Major upgrades:**
* The Touchpoints column now displays the most common customer journey for any selected breakdown (Clicks Only model)
* The Sales page now includes:
* Customer metrics (All, New, Returning)
* Visitor metrics
* CAC (New), CPV, RPV, AOV
* Upgraded visualizations, including split and stacked line charts
* Full screen mode for tables and graphs
* One click access to Metrics Explorer
* The Orders page now includes:
* Order-level journey details showing how each touchpoint received credit
* Filters to isolate orders where specific platforms receive credit under selected models, modes, or lookback windows
* Quickfilters for common investigative patterns
***
### Metric Definitions
Clear reference definitions for all core and expanded metrics in Northbeam 3.0.
#### New Metrics
**RPV (All)** Revenue per visitor.
**RPV (New)** New revenue per new visitor.
**RPV (Returning)** Returning revenue per returning visitor.
**Customers (All)** Total unique customers in the reporting window.
**Customers (New)** Customers making their first purchase in the reporting window.
**Customers (Returning)** Customers who have purchased before the reporting window.
**Customers (Returning, Active)** Returning customers who purchased within the last 60 days.
**Customers (Returning, Reactivated)** Returning customers who have not purchased in the last 60 days.
**Touchpoints (Attributed, All / New / Returning)** Average number of touchpoints that received attribution credit for all, new, or returning orders.
**Visitors (All / New / Returning)** Unique visitors segmented by new vs returning behavior.
**Applovin conversion metrics** Reported conversion metrics from Applovin.
**Vibe conversion metrics** Reported conversion metrics from Vibe.
#### Updated Metrics (new naming, same definition)
**CAC → CPO** Customer acquisition cost is now cost per order. Previously, CAC was functionally measuring CPO, so the new name aligns with the actual definition.
**eCPNV → CPV** Previously only applied to new visits. CPV now applies to both new and returning visitors.
**Transactions → Orders** Updated to align with standard naming.
***
## Any Feedback?
We’re excited to hear what you think. Your feedback directly shapes the Northbeam experience, and we want to make Northbeam 3.0 the best version yet.
Have ideas, questions, or suggestions? Don't hesitate to [reach out to our team](https://www.northbeam.io/submit-a-support-ticket)!
# Northbeam AI
Source: https://docs.northbeam.io/docs/northbeam-ai
Ask questions about Northbeam and your own data, right inside the dashboard
Northbeam AI is a conversational way to get help and understand your data. Ask it
questions the way you would ask a person — about how Northbeam works, about your
own numbers, or when you need our Support team to take a look.
Northbeam AI is available on every Northbeam plan.
## Where to find it
Open Northbeam AI from the **AI icon in the left-hand menu** of your dashboard.
## Ask a support or how-to question
Ask about setup, troubleshooting, concepts, or where to find something in the
product. Northbeam AI searches our documentation, walks you through the steps,
and links the articles it used.
For example:
* `How do I set up Apex for Meta?`
* `Can you define each attribution model and explain when I should use each one?`
* `How do I troubleshoot a disconnected ad platform?`
* `Where do I change my default attribution model?`
## Ask about your data
Northbeam AI can also query your account and answer directly in the conversation.
For example:
* `What was my Google ROAS over the last 30 days?`
* `Break down spend and revenue by platform for the last 30 days.`
* `Which campaigns dropped the most week over week?`
Northbeam AI queries the dashboard you are currently in. It reads your data — it
does not edit orders, spend, or your platform connections.
It can update **your own** default attribution settings if you ask, for example
`Set my default attribution model to Last Click` or `Switch me to cash accounting`.
That only affects your defaults, not anyone else's.
## File a support ticket
If you still need help from our Support team, you can file a ticket without
leaving Northbeam AI. There are two ways:
* Click the **Submit a ticket** button in the conversation.
* Ask Northbeam AI to submit a ticket for you.
Either way, Northbeam AI may ask a few follow-up questions so our Support team has
the right context. It confirms the details with you before filing.
Once the ticket is filed you get the ticket number and a link to view it. You can
also open the **Customer Portal** to track all of your requests in one place.
## Context Center
**Context Center** is a shared library of reference documents that Northbeam AI can
use across every conversation on your dashboard. It tells Northbeam AI *what to
know* about your business.
Open it from **Context Center** at the top of the conversation list.
Good things to upload:
* Brand guidelines and glossaries
* Pricing references and partner lists
* Budget plans and promotion calendars
* Internal operating procedures and media-buying playbooks
Add a document with **New File**. Give it a short description — Northbeam AI uses
the description to decide when the document is relevant, so it is worth writing a
real one. You can edit, download, or delete a document at any time, and search the
list by filename or description.
Uploads accept `.csv`, `.txt`, `.md`, `.json`, and `.yaml` files, up to 1 MB each,
with a limit of 100 documents per dashboard. Descriptions can be up to 500
characters.
Context Center is shared: every user on the dashboard sees the same files and
Northbeam AI uses them for everyone.
## Custom Instructions
**Custom Instructions** are standing rules that guide how Northbeam AI answers and
analyzes. Where Context Center tells it *what to know*, Custom Instructions tell it
*how to behave*.
Open them from **Custom Instructions** at the bottom of the conversation list.
There are two boxes:
| | Applies to | Use it for |
| - | - | - |
| **Your Instructions** | Your conversations only, on every dashboard you have access to | Personal preferences — response length, level of detail, formatting |
| **Company-wide Instructions** | Everyone on this dashboard | Business rules — fiscal calendar, accounting conventions, attribution preferences, targets |
Examples:
* Your Instructions: `Keep answers concise and lead with the most important numbers.`
* Company-wide Instructions: `Our fiscal year starts in April. Use accrual accounting and compare performance against our contribution-margin target.`
Each box holds up to 2,000 characters.
Despite the name, **Company-wide Instructions apply to one dashboard, not to your
whole company.** If you have more than one Northbeam dashboard, add your
instructions — and your Context Center files — separately on each one.
## Usage limits
Northbeam AI has a usage limit.
* Everyone gets a baseline limit.
* Your usage resets every week. If you reach your limit, you can pick up again
after it resets.
* We plan to offer a monthly option to raise your limit in the future.
## Does this replace Northbeam Support?
No. Northbeam AI makes it faster to get answers and to reach our team from inside
the product. When something needs a person, ask it to file a support ticket and our
Support team picks it up from there.
## Related
* [Connect Northbeam to your AI assistant](/docs/northbeam-mcp) — use Northbeam data from ChatGPT, Claude, or another tool via MCP
* [Northbeam MCP Server FAQs](/docs/northbeam-mcp-server-faqs) — security and privacy
# 🏍️ Northbeam Apex
Source: https://docs.northbeam.io/docs/northbeam-apex
Optimize your Meta ads against first-party Northbeam data with this new integration.
## What is Northbeam Apex?
**Northbeam Apex is a direct integration between Northbeam and our advertising platform partners that lets the partner fold Northbeam's first-party, multi-touch attribution signal directly into how they optimize ad delivery.**
With Apex, participating platform partners can integrate Northbeam's MTA-derived performance into their algorithm's optimization process — so ad delivery is optimized against the data you already trust, instead of platform-default last-click.
With a more informed, cross-channel signal built from your actual orders and the touchpoints leading to them, the platform's algorithm can better understand how your ads affect the entire customer journey and **optimize more effectively than ever before.**
**In short: activating Apex could help you find as much as +25% ROAS with the press of a button. **
These are the results of our most recent A/B testing of Apex-empowered campaigns versus controls.
***
## How does Apex work?
Apex flips the standard model: instead of sending the platform more raw events for it to attribute itself, **Northbeam does the attribution first** and sends the platform the result.
* Northbeam captures first-party events via its own pixel and your order feed.
* Northbeam's ML-based MTA model splits credit across every touchpoint in the customer journey.
* Apex sends the Northbeam-attributed performance for each ad to the partner platform.
* The partner uses that signal to optimize ad delivery against the outcomes you actually care about.
The result is the platform's auction aligning to how *you* measure success — not how it measures it by default.
### **Apex is additive.**
It does not replace your existing pixel or CAPI connections. Your existing setup keeps working exactly as it does today. Apex adds a parallel, attributed signal the platform uses to optimize differently.
***
## Apex vs. CAPI and enrichment tools
A common question: *I already send Meta enriched conversion data through a CAPI-based products — does Apex conflict with that, or make it redundant?*
**Neither. They solve two different problems, and they compound.**
| | **Enrichment / CAPI-based products** | **Northbeam Apex** |
| - | - | - |
| **What it sends** | The raw conversion, enriched with as much identity and order detail as possible | Northbeam's attributed credit for that conversion |
| **What that does** | Helps Meta match as many conversions as possible back to ad interactions | Helps Meta understand which ads actually drove the outcome |
| **Question it answers** | "Did Meta touch this customer at all?" | "How much of this sale does Meta deserve?" |
### A single order, end to end
On Monday, a \$100 order comes into your store.
**Your enrichment tool shares the conversion itself:**
* Order value
* Customer email
* Customer ID
* Phone number
* Product purchased
* Etc.
Meta uses that to match the buyer to any ad interactions it drove — connecting the dots between the order and the touchpoints that preceded it.
**Northbeam Apex then shares the credit:**
* Of that \$100, Northbeam's MTA model determines Meta contributed **\$45**.
Meta optimizes delivery toward the ads earning that \$45 — not toward its own last-click view of the same order.
### Enrichment connects the dots. Apex weights them.
Enrichment tools make sure Meta **sees** every conversion and touchpoint. Apex tells Meta **how much credit** those touchpoints actually deserve. Keep both — leave your existing pixel and CAPI setup exactly as it is.
***
## Apex: two pieces to understand
There are two distinct components to Apex, and it's important to understand them separately:
#### 1. The data connection
This is what you set up in Northbeam. Turning this on starts sending Northbeam's order-level MTA data to the platform. It trains the platform's model. It does not turn on live optimization.
#### 2. The optimization layer
This is how the platform actually uses Apex data to optimize your campaigns.
On Meta, this is called **Custom Attribution** and is configured at the ad-set level in Meta Ads Manager. This layer is currently in beta for Meta, with broader rollout during 2026.
***
## Supported platforms
| **Platform** | **Status** |
| - | - |
| **Meta** | All customers can set up Apex data sharing today. |
| **Snap** | Closed beta; no timeline on broader rollout. |
| **AppLovin** | Available. |
| **Pinterest** | Apex consent is required to access Clicks + Deterministic Views (C+DV). Apex is not currently used for Pinterest optimization. |
| **Others** | Additional platform integrations are on the roadmap. |
***
## Setting up Apex
### Before you start
Regardless of platform, setup begins in [Apex](https://dashboard.northbeam.io/settings/apex) in your Northbeam dashboard. You'll define your **North Star metric** — the signal Apex sends to the platform to optimize toward:
* **Revenue type:** First-Time, Returning, or Blended
* **Attribution model:** Clicks-Only, Clicks + Deterministic Views (CDV), Last Touch, Linear, or First Touch
* **Attribution window:** 1 / 3 / 7 days
* **Accounting mode:** Accrual
Once your North Star is set, enable Apex consent for your desired platform(s) in the same settings page.
### **Changing your North Star after setup resets the model's calibration period.**
Plan for approximately two weeks before the model is fully re-warmed. Coordinate with your CSM before making changes if you have active optimization campaigns running.
***
### Meta
Meta is the most fully featured Apex integration today and the most common starting point. The setup below is specific to Meta.
#### Legacy vs. current version
The current version of Apex sends order-level data to Meta via CAPI and is the foundation for active Meta-side optimization.
| | **Legacy Apex** | **Enhanced Apex (current)** |
| - | - | - |
| Account-level data passback | ✅ | ❌ |
| Order-level data passback | ❌ | ✅ |
| Order-level algorithm optimization | ❌ | ✅ |
| Set a North Star metric | ✅ | ✅ |
| Meta optimizes campaigns vs. North Star | ❌ | ✅ (gated beta) |
| A/B test performance at Meta ad-set level | ❌ | ✅ (gated beta) |
### Enhanced Apex sends richer signal.
Legacy Apex passed back aggregated ad-level totals. Enhanced Apex sends touchpoint-level data — giving Meta a multi-touch picture of what drove every sale.
***
## Next step
With Apex explained, the next step is turning it on: [Enable Apex for Meta](/docs/setting-up-apex).
# Sales Attribution Export
Source: https://docs.northbeam.io/docs/northbeam-api-data-export-1
Export your performance metrics by attribution model, window, and accounting mode.
The **Sales Attribution** report is one of the report types available in [Data Exports](/docs/northbeam-api-data-exports-overview). It exports your performance metrics — such as Attributed Revenue and Transactions — for different Attribution Windows (1, 3, 7, etc.), Accounting Modes (cash or accrual), and Attribution Models (e.g. Clicks only or Clicks + Modeled Views).
For the setup shared by every report — **authentication**, **destinations** (GCS/S3), and **polling for results** — see the [Data Exports](/docs/northbeam-api-data-exports-overview) overview. This page covers what's specific to the Sales Attribution report.
Before creating an export, we recommend fetching the available **attribution models**, **metrics**, and **breakdown labels** first, so you know your options.
> If you have any doubts on how to use the endpoints, refer to the [API Reference](/reference/post_data-export-1) for guidance.
***
## Fetching attribution models
To fetch your attribution models, you can use one of the following snippets:
> You can find request examples in other languages in the [API Reference](/reference/post_data-export-1)
```curl theme={null}
curl --request GET \
--url https://api.northbeam.io/v1/exports/attribution-models \
--header 'Authorization: ' \
--header 'Data-Client-ID: ' \
--header 'accept: application/json'
```
```python theme={null}
import requests
url = "https://api.northbeam.io/v1/exports/attribution-models"
headers = {
"accept": "application/json",
"Authorization": "",
"Data-Client-ID": ""
}
response = requests.get(url, headers=headers)
print(response.text)
```
This will send a GET request to the Data Export API, which will return the available attribution models for your account in JSON format. Make sure to replace ``, and `` with the appropriate values for your account.
Once you send the GET request to the Data Export API using the shell snippet provided earlier, you will receive a JSON response containing the available attribution models for your account. The response will appear as follows:
```json theme={null}
{
"attribution_models": [
{
"id": "northbeam_custom",
"name": "Clicks only"
},
{
"id": "northbeam_custom__va",
"name": "Clicks + Modeled Views"
},
{
"id": "last_touch",
"name": "Last touch"
},
{
"id": "last_touch_non_direct",
"name": "Last non-direct touch"
},
{
"id": "first_touch",
"name": "First touch"
},
{
"id": "linear",
"name": "Linear"
}
]
}
```
***
## Fetching metrics
To fetch your metrics, you can use this snippet:
```curl theme={null}
curl --request GET \
--url https://api.northbeam.io/v1/exports/metrics \
--header 'Authorization: ' \
--header 'Data-Client-ID: ' \
--header 'accept: application/json'
```
```python theme={null}
import requests
url = "https://api.northbeam.io/v1/exports/metrics"
headers = {
"accept": "application/json",
"Authorization": "",
"Data-Client-ID": ""
}
response = requests.get(url, headers=headers)
print(response.text)
```
This will send a GET request to the Data Export API, which will return the available metrics for your account in JSON format. Make sure to replace ``, and `` with the appropriate values for your account.
After executing the request, you will receive a JSON response that contains the available metrics. If you have connected any platform with their own metrics, such as TikTok, Meta (Facebook), or Google, they will also be listed in the response.
The response will look like the following:
```json JSON theme={null}
{
"metrics": [
{
"id": "aov",
"label": "AOV"
},
{
"id": "aovFt",
"label": "AOV (1st time)"
},
{
"id": "aovFtLtv",
"label": "LTV AOV (1st time)"
},
{
"id": "aovLtv",
"label": "LTV AOV"
},
{
"id": "aovRtn",
"label": "AOV (Returning)"
},
{
"id": "aovRtnLtv",
"label": "LTV AOV (Returning)"
},
{
"id": "cac",
"label": "CAC"
},
{
"id": "cacFt",
"label": "CAC (1st time)"
},
{
"id": "cacFtLtv",
"label": "LTV CAC (1st time)"
},
{
"id": "cacLtv",
"label": "LTV CAC"
},
{
"id": "cacOrderSubscription",
"label": "Subscription CAC"
},
{
"id": "cacOrderSubscriptionFirstTime",
"label": "Subscription CAC (1st time)"
},
{
"id": "cacOrderSubscriptionOther",
"label": "Subscription CAC (Other)"
},
{
"id": "cacOrderSubscriptionRecurring",
"label": "Subscription CAC (Recurring)"
},
{
"id": "cacRtn",
"label": "CAC (Returning)"
},
{
"id": "cacRtnLtv",
"label": "LTV CAC (Returning)"
},
{
"id": "cpm",
"label": "CPM"
},
{
"id": "ctr",
"label": "CTR"
},
{
"id": "customGoal:email_capture",
"label": "Email Signups"
},
{
"id": "customGoalCost:email_capture",
"label": "Cost per Email Signup"
},
{
"id": "customGoalCostLtv:email_capture",
"label": "LTV Cost per Email Signup"
},
{
"id": "customGoalLtv:email_capture",
"label": "LTV Email Signups"
},
{
"id": "customGoalRate:email_capture",
"label": "Email Signup Rate"
},
{
"id": "customGoalRateLtv:email_capture",
"label": "LTV Email Signup Rate"
}
]
}
```
> The JSON response above is for demonstration purposes only and therefore does not include all possible metrics.
***
## Fetching breakdown labels
To fetch your breakdowns, use the following shell snippet:
```curl theme={null}
curl --request GET \
--url https://api.northbeam.io/v1/exports/breakdowns \
--header 'Authorization: ' \
--header 'Data-Client-ID: ' \
--header 'accept: application/json'
```
```python theme={null}
import requests
url = "https://api.northbeam.io/v1/exports/breakdowns"
headers = {
"accept": "application/json",
"Authorization": "",
"Data-Client-ID": ""
}
response = requests.get(url, headers=headers)
print(response.text)
```
Executing this shell command will send a GET request to the Data Export API and return the available labels you can use to break down your exported data by different attributes. Please replace `` and `` with your own account's values.
It's worth noting that breakdown labels can be useful for grouping your data by different platforms, allowing you to analyze your data by platform and identify trends or areas for improvement.
The response will be in JSON format and will include all the available breakdown labels for platforms in your account. Here is an example of the JSON response:
```json theme={null}
{
"breakdowns": [
{
"key": "Category (Northbeam)",
"values": [
"Paid - Other",
"Influencer",
"Organic",
"Paid - Prospecting",
"Synthetic",
"Unattributed",
"Organic Search",
"Email",
"Organic Social",
"Other",
"Transactional",
"Paid - Display",
"Paid - Video",
"Paid - Nonbranded Search",
"Paid - Awareness"
]
},
{
"key": "Targeting (Northbeam)",
"values": [
"Paid - Other",
"Other",
"Paid - Prospecting",
"Paid - Display",
"Paid - Video",
"Paid - Nonbranded Search"
]
},
{
"key": "Platform (Northbeam)",
"values": [
"Google Ads",
"Influencer",
"Organic",
"LinkedIn Ads",
"Other",
"Unattributed",
"Organic Search",
"Other Email",
"TikTok",
"Transactional",
"Facebook Organic",
"Pinterest",
"YouTube Ads",
"Misc - Exclude Me",
"Facebook Ads",
"Klaviyo",
"Snapchat Ads"
]
},
{
"key": "Influencers (by Platform)",
"values": ["TikTok", "YouTube", "Podcast", "Instagram"]
}
]
}
```
> When creating a data export, you have the option to choose not to use any breakdown label. In this case, the exported data will not be grouped by any platform or other criteria, and will not include any breakdowns.
***
## Creating a data export
To create a data export, you can use the following request example:
```curl theme={null}
curl --request POST \
--url https://api.northbeam.io/v1/exports/data-export \
--header 'Authorization: ' \
--header 'Data-Client-ID: ' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"level": "ad",
"time_granularity": "DAILY",
"period_type": "YESTERDAY",
"breakdowns": [
{
"key": "Category (Northbeam)",
"values": [
"Influencer",
"Organic",
"Organic Search",
"Email",
"Organic Social",
"Other"
]
}
],
"options": {
"export_aggregation": "BREAKDOWN",
"remove_zero_spend": false,
"aggregate_data": false,
"include_ids": false,
"include_kind_and_platform": false
},
"attribution_options": {
"attribution_models": ["northbeam_custom__va"],
"accounting_modes": ["accrual", "cash"],
"attribution_windows": ["1"]
},
"metrics": [
{"id": "customGoal:email_capture"},
{"id": "cpm"},
{"id": "spend", "label": "yesterday_spend"},
{"id": "cac"},
{"id": "rev"}
]
}
'
```
```python theme={null}
import requests
url = "https://api.northbeam.io/v1/exports/data-export"
payload = {
"level": "ad",
"time_granularity": "DAILY",
"period_type": "YESTERDAY",
"breakdowns": [
{
"key": "Category (Northbeam)",
"values": [
"Influencer",
"Organic",
"Organic Search",
"Email",
"Organic Social",
"Other"
]
}
],
"options": {
"export_aggregation": "BREAKDOWN",
"remove_zero_spend": False,
"aggregate_data": False,
"include_ids": False,
"include_kind_and_platform": False
},
"attribution_options": {
"attribution_models": ["northbeam_custom__va"],
"accounting_modes": ["accrual", "cash"],
"attribution_windows": ["1"]
},
"metrics": [
{"id": "customGoal:email_capture"},
{"id": "cpm"},
{"id": "spend", "label": "yesterday_spend"},
{"id": "cac"},
{"id": "rev"}
]
}
headers = {
"accept": "application/json",
"content-type": "application/json",
"Authorization": "",
"Data-Client-ID": ""
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
Note that only `metrics` and `attribution_options` are required to create an export. The other fields are either optional or have default values.
> For more information on payload options please refer to the [API Reference](/reference/post_data-export-1) for assistance.
Here is a brief explanation of some of the key parameters in the request body:
* `level`: Specifies the level of granularity for the export. In this case, the
export is at the ad level.
* `time_granularity`: Specifies the time granularity for the export, in this
case, it's set to daily.
* `period_type`: Specifies the period for which the data should be exported. In
this case, the period is set to yesterday.
* `breakdowns`: Specifies the breakdowns to apply to the exported data. In this
case, the data will be grouped by the values in the "Category (Northbeam)"
breakdown. You must use the labels fetched from the `/breakdowns` endpoint.
* `metrics`: Specifies the metrics to include in the exported data. You must use
the metrics available from the `/metrics` endpoint. Note that the `label`
parameter under `metrics` is optional and can be used to specify a custom
label for the metric in the exported data. If a label is not provided, the
default label for the metric will be used.
* `attribution_options`: Specifies the attribution models, attribution windows,
and accounting modes to apply to the exported data. The attribution models
must be the ones from the `/attribution-models` endpoint.
* `options`: Specifies additional options, such as whether to aggregate data,
whether to remove zero spend rows, and how to aggregate data.
After sending the request, you will receive a response in JSON format containing the ID of the export. You can use the ID to check the status of the export or to download the exported data.
```json theme={null}
{
"id": ""
}
```
***
## Fetching the result
The create response returns an `id` (shown above). Poll the shared results endpoint with it until `status` is `SUCCESS`, then download the file from the `result` link — this endpoint works the same for every report type. See [Fetching your export results](/docs/northbeam-api-data-exports-overview#fetching-your-export-results) in the Data Exports overview.
# Exporting To GCS
Source: https://docs.northbeam.io/docs/northbeam-api-data-export-gcs-export-1
This page describes the Exporting To GCS of our Data Export API
# Exporting to an external GCS bucket
By default, all data exports are stored in Northbeam's internal GCS. However, if you prefer to export your data to your own GCS bucket, you can do so by following these steps:
1. Grant `Storage Object Admin` permissions to the email address
`nb-data-export@north-beam-io.iam.gserviceaccount.com` in your bucket's IAM
configuration.
2. Input the name of the GCS bucket you want us to send the data to
3. Click 'validate' to make sure the connection works
# Rate Limits
Source: https://docs.northbeam.io/docs/northbeam-api-data-export-rate-limits-1
This page describes the Rate Limits of our Data Export API
# Rate Limits
| Endpoint | Rate limit |
| :- | :- |
| `/data-export` | 60 req/minute |
| `/data-export/result` | 100 req/second |
| `/breakdowns` | 100 req/second |
| `/attribution-models` | 100 req/second |
| `/metrics` | 100 req/second |
# Exporting To S3
Source: https://docs.northbeam.io/docs/northbeam-api-data-export-s3-export-1
This page describes the Exporting To S3 of our Data Export API
# Exporting to an external S3 bucket
If you want to export your data to your S3 bucket, you can do so by following the steps below:
1. Create a role with **Custom trust policy**, including the Northbeam user (below) as a Principal with the `sts:AssumeRole` permission:
> `arn:aws:iam::892581138023:user/nb-data-orders-export-custom-sa-user`
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::892581138023:user/nb-data-orders-export-custom-sa-user"
},
"Action": "sts:AssumeRole"
}
]
}
```
2. Copy the ARN of the role you created on step `1`, and the name of the bucket you wish to use
3. Create a policy (inline in the role or standalone) providing the permissions below, just changing the placeholders `` and `` with the information you got from step `2`.
> PS: The action iam:SimulatePrincipalPolicy is required, as our system relies on it to validate the bucket permissions.
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:ListBucket",
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::", // Add your bucket name
"arn:aws:s3:::/*" // Add your bucket name
]
},
{
"Sid": "Statement2",
"Effect": "Allow",
"Action": ["iam:SimulatePrincipalPolicy"],
"Resource": [""] // Add your role ARN
}
]
}
```
4. If you created a standalone policy, attach it to the role you created on step `2`.
5. Provide the role ARN in each data export request through the `aws_role` parameter.
# Data Exports
Source: https://docs.northbeam.io/docs/northbeam-api-data-exports-overview
Export your Northbeam data to your own cloud storage. An overview of the report types, destinations, and the shared results endpoint.
## What are Data Exports?
**Data Exports** let you export your Northbeam data to your own cloud storage (GCS or S3) via the API. Data Exports is the parent surface — the same as the **Data Exports** tab in the app — and it can run several different **report types**. Every report shares the same setup (authentication, destinations, and result polling); each report type then has its own creation endpoint and options.
## Report types
| Report | What it exports | Guide |
| - | - | - |
| **Sales Attribution** | Performance metrics (attributed revenue, transactions, CAC, …) by attribution model, window, and accounting mode. | [Sales Attribution Export](/docs/northbeam-api-data-export-1) |
| **Orders** | Your orders, one row per order, with product information. | [Orders Export](/docs/northbeam-api-orders-export) |
The rest of this page covers the setup that is common to **all** report types.
***
## Authentication
Every request needs an API key and your client id, sent as headers. Generate a key by following the [Authentication](/docs/authentication) guide. The examples in each report's guide show how to pass the `Authorization` and `Data-Client-ID` headers.
***
## Destinations
Exports are written to a cloud storage bucket you own. Provide the destination in the create request of whichever report you're running:
* **GCS** — pass `bucket_name`. See [Exporting to GCS](/docs/northbeam-api-data-export-gcs-export-1) for how to grant Northbeam write access.
* **S3** — pass `bucket_name` plus `aws_role` (an IAM role ARN with write access) and `region`. See [Exporting to S3](/docs/northbeam-api-data-export-s3-export-1).
The destination fields are the same across report types.
***
## Fetching your export results
Creating any export returns an `id`. Exports run asynchronously, so poll the shared **results** endpoint with that id until it finishes — this endpoint is the same for every report type.
```curl theme={null}
curl --request GET \
--url https://api.northbeam.io/v1/exports/data-export/result/ \
--header 'Authorization: ' \
--header 'Data-Client-ID: ' \
--header 'accept: application/json'
```
```python theme={null}
import requests
url = "https://api.northbeam.io/v1/exports/data-export/result/"
headers = {
"accept": "application/json",
"Authorization": "",
"Data-Client-ID": ""
}
response = requests.get(url, headers=headers)
print(response.text)
```
The response `status` field has three possible values:
| Status | Description |
| - | - |
| `PENDING` | The export is still being processed. Keep polling until the status changes. |
| `SUCCESS` | The export is complete. The `result` field contains a link to the exported file(s). |
| `ERROR` | The export failed. Submit a new export request. |
**While processing (`PENDING`):**
```json theme={null}
{
"data_export_id": "",
"status": "PENDING",
"result": [],
"created_at": "2023-05-03T19:12:53.933Z",
"finished_at": null
}
```
**When complete (`SUCCESS`):**
```json theme={null}
{
"data_export_id": "",
"status": "SUCCESS",
"result": [""],
"created_at": "2023-05-03T19:12:53.933Z",
"finished_at": "2023-05-03T19:13:20.000Z"
}
```
> **Important:** exports can take anywhere from a few seconds to several minutes, and a `200 OK` does not mean the export is ready. Keep polling only while `status` is `"PENDING"`; on `"SUCCESS"` download the file from the link in `result` (the link is only valid for a limited time, so re-request it if it expires); on `"ERROR"` stop polling and submit a new export. The only supported format today is CSV.
***
## Rate limits
The result endpoint and the discovery endpoints can each be called up to 100 requests/second. See [Rate Limits](/docs/northbeam-api-data-export-rate-limits-1) for the full table.
# Orders Export
Source: https://docs.northbeam.io/docs/northbeam-api-orders-export
Export your orders, including product information, to your own GCS or S3 bucket.
The **Orders** report is one of the report types available in [Data Exports](/docs/northbeam-api-data-exports-overview). It exports your orders — one row per order — including product information, directly to your own GCS or S3 bucket.
This page covers only what's specific to the Orders report. For the setup shared by every report — **authentication**, **destinations** (GCS/S3), and **polling for results** — see the [Data Exports](/docs/northbeam-api-data-exports-overview) overview.
## Creating an Orders export
Send a `POST` request to `/data-export/orders`. The export runs asynchronously; the response returns an `id` you poll for the result (see [Fetching your export results](/docs/northbeam-api-data-exports-overview#fetching-your-export-results)).
Required fields:
* `bucket_name` — the GCS or S3 bucket to export to. For an **S3** destination, also provide `aws_role` and `region`; omit them for **GCS**. See [Destinations](/docs/northbeam-api-data-exports-overview#destinations).
* `start_date` / `end_date` — the export window (ISO 8601 date-times). `start_date` is inclusive, `end_date` is exclusive.
## Columns
If you omit `columns`, the export uses its **default** set of order columns, which includes the customer type. To customize the file, pass `columns` as a list of column ids — you then get **exactly** the columns you list, in that order. A few notes:
* `customer_type` (first-time vs. returning) is part of the default set. It is included when you omit `columns`; if you send an explicit `columns` list, include `"customer_type"` in it to keep it.
* `products` is a single column of the order's product **SKUs**, comma-separated, falling back to the product id when a SKU is not set.
* `order_tags` and `source_name` are also available as columns.
For the complete list of available column ids, see the `columns` field in the [API Reference](/reference/post_data-export-orders).
## Example request
```json theme={null}
{
"bucket_name": "my-northbeam-exports",
"start_date": "2026-01-01T00:00:00Z",
"end_date": "2026-02-01T00:00:00Z",
"columns": ["order_id", "order_ts", "order_revenue_total", "customer_type", "products"]
}
```
The response contains the export `id`:
```json theme={null}
{
"id": ""
}
```
Poll `GET /data-export/result/{export_id}` with that id until `status` is `SUCCESS` — see [Fetching your export results](/docs/northbeam-api-data-exports-overview#fetching-your-export-results).
> For the full request/response schema, see the [API Reference](/reference/post_data-export-orders).
# Northbeam's Data Sources
Source: https://docs.northbeam.io/docs/northbeam-data-sources
Where does Northbeam get its data from?
Here is a breakdown of our data sources as well as how they work together to capture the full customer journey.
## Frontend Data Source
[Northbeam Pixel](/docs/add-pixel)
[Purchase Events](/docs/purchase-pixel)
UTM Parameters
First-Party Cookies
What is it?
A small code snippet embedded in your website.
Northbeam provides a variety of scripts to track conversions. This includes purchases, email sign ups, or even a custom goal.
Tags added to URLs to track where traffic comes from (e.g., ads, emails, social).
Small data files set by the website a user visits.
What does it do?
Collects behavioral data from visitors, including Marketing touchpoints & Pages visited.
Feeds data into Northbeam's backend device graph.
Tracks complete customer journeys from initial visit to purchase.
These scripts are unique to Northbeam. They feed into your device graph and displayed in your dashboard
Helps connect conversion events to the ad or marketing channel that drove them.
Stores login, preferences, and browsing behavior.
### How Northbeam tracks using First-Party Cookies
* Northbeam sets up first-party tracking using a subdomain (e.g., i.store.com).
* This subdomain is owned by your domain, making tracking first-party and not blocked by browsers.
* First-party cookies store user data, and pixel events are sent securely to your Northbeam dashboard
* This ensures accurate attribution and privacy-compliant tracking without relying on third-party cookies.
## Backend Data Source
| Shopify Integration |
| :- |
| Northbeam natively integrates with Shopify, allowing us to fetch all your order data and establish a reliable revenue source of truth. |
### We rely on server-side data as the source of truth to ensure we capture all order information—including orders that don’t fire web pixels. This includes
* Offline Orders
* Draft Orders
* Recurring Subscriptions
* Other cases where client-side tracking misses
## Connecting Frontend and Backend
Northbeam's data sources work together to give you the most accurate and complete view of customer's journey. Please submit a [Support ticket here](https://www.northbeam.io/submit-a-support-ticket) if you have any further questions.
# Connect Northbeam to Your AI Assistant
Source: https://docs.northbeam.io/docs/northbeam-mcp
Northbeam MCP lets an AI assistant like ChatGPT or Claude read your Northbeam data, so you can ask questions in plain language and get answers from your own dashboards.
Northbeam MCP lets an AI assistant like ChatGPT or Claude read your Northbeam data, so you can ask questions in plain language and get answers from your own dashboards.
Northbeam MCP is available on every Northbeam plan.
***
## Choose your assistant
* **[ChatGPT](/docs/connect-northbeam-to-chatgpt)** — requires a paid ChatGPT plan (Pro, Team, Enterprise, or EDU).
* **[Claude](/docs/connect-northbeam-to-claude)** — works with Claude on the web, Claude Desktop, and Claude Code, on any Claude plan.
* **[Another AI tool](/docs/connect-northbeam-to-ai-agent)** — any assistant that supports custom connectors.
Each guide takes a few minutes. You will sign in with your normal Northbeam login — there is no separate account to create and no API key to manage.
***
## What you can ask
Once connected, your assistant can pull live data from your Northbeam dashboards. For example:
1. `What was my Meta ROAS last week vs the prior week?`
2. `Break down spend and revenue by platform for the last 30 days.`
3. `Show me my top 10 orders by revenue this month.`
4. `List my Northbeam dashboards.`
If you have access to more than one dashboard, tell the assistant which one to use so it queries the right account.
***
## What it can and cannot do
The connection is **read-only**. Your assistant can query and summarize your Northbeam data, but it cannot change anything in Northbeam.
It also follows your existing permissions. If you cannot see something in Northbeam, your assistant cannot see it through MCP either.
***
## Questions about security and privacy
See the [Northbeam MCP Server FAQs](/docs/northbeam-mcp-server-faqs) for how MCP works, what data is sent to your AI provider, and how that provider handles it.
# Northbeam MCP Server FAQs
Source: https://docs.northbeam.io/docs/northbeam-mcp-server-faqs
How the Northbeam MCP server works, what data it sends to your AI provider, and how that provider handles it.
[← Connect Northbeam to Your AI Assistant](/docs/northbeam-mcp)
### Which Northbeam plans include MCP?
Northbeam MCP is available on every Northbeam plan.
### What is MCP, and why does it matter for security?
MCP (Model Context Protocol) is a standard way for AI applications such as Claude or ChatGPT to request information from services such as Northbeam.
An MCP connection has two parts:
* Northbeam runs the MCP server and controls what data it makes available and who can access it.
* Your AI provider runs the MCP client and controls how the data is handled after it reaches the AI application.
For questions about access to Northbeam data, contact Northbeam. For questions about storage, retention, or model training, check with your AI provider.
### What Northbeam data can the AI access?
Through the Northbeam MCP server, an AI application can access the same types of information available on the Northbeam dashboard, including performance metrics, attribution data, orders, and—if enabled—product-level attribution.
The Northbeam MCP server follows each user’s existing permissions. It does not give users additional access. If someone cannot view certain information in Northbeam, they cannot access it through the MCP server either.
### How much data is sent?
The Northbeam MCP server sends data only when the AI application makes a specific request, called a “tool call.” Each tool retrieves a limited set of information, such as metrics for a date range or details about an order.
There is no automatic background sync or bulk export. However, the AI application may make several tool calls to answer one question. The AI provider—not Northbeam—determines which tools are called, how often they are called, and what information is requested.
### Is my data stored after a query or used to train AI models?
After the Northbeam MCP server sends data to the AI application, the AI provider’s policies apply. Northbeam does not control whether the provider stores the data, keeps conversation history, or uses the data for model training.
Review your AI provider’s trust center, privacy documentation, and commercial terms for details.
### Does my AI plan affect how my data is handled?
The Northbeam MCP server works the same way regardless of your AI plan. However, AI providers may offer different privacy, retention, and training policies for different plans—for example, Claude Enterprise versus Claude Pro or ChatGPT Business versus ChatGPT Plus.
Check your AI provider’s documentation to understand the policies that apply to your specific plan.
# Northbeam Metrics 101
Source: https://docs.northbeam.io/docs/northbeam-metrics-101
Use this guide to understand our metrics
It's important to understand what our different metrics mean and how they may be different from the metrics you're used to seeing.
## Finding Metrics in the Dashboard
To find the full list of our metrics within your dashboard:
1. Navigate to the **Attribution Page**
2. Click **Customize ⚙️**
From here, you'll see a list of all the metrics we provide and you'll be able to add/remove any from your view:
***
## Northbeam Conversion Metrics
Conversion metics are by far the most commonly used metrics within Northbeam.
**Note: All conversion metrics in Accrual Accounting mode are reported in an Attribution Window, which is denoted in the metric name.**
Examples:
* Transactions (1d) - Transactions completed in a 1-day window
* Attributed Rev (1d) - Revenue in a 1-day window
* ROAS (7d) - Return on Ad Spend calculated with Revenue in a 7-day window
**Learn more about our[Attribution Windows here](/docs/attribution-windows).**
For simplicity, we have omitted the attribution windows from the list below.
Metric Name
Definition
Calculation or Notes
Transactions
Number of Transactions from All Customers
*
Transactions (New)
Number of Transactions from New Customers
*
Transactions (Returning)
Number of Transactions from Returning Customers
*
Attributed Rev
Attributed Revenue from All Customers
Revenue attributed to touchpoints in the given time period. Available in Accrual Accounting.
Attributed Rev (New)
Attributed Revenue from New Customers
Revenue attributed to touchpoints in the given time period. Available in Accrual Accounting.
Attributed Rev (Returning)
Attributed Revenue from Returning Customers
Revenue attributed to touchpoints in the given time period. Available in Accrual Accounting.
Rev
Revenue from All Customers
Only available in Cash Accounting. No attribution windows available.
Rev (New)
Revenue from New Customers
Only available in Cash Accounting. No attribution windows available.
Rev (Returning)
Revenue from Returning Customers
Only available in Cash Accounting. No attribution windows available.
# Offline Channel
Source: https://docs.northbeam.io/docs/offline-channel
Offline Channels (like Podcasts, Linear, DOOH, Direct Mail, and CTV) do not generate Clicks, so Northbeam can't directly attribute conversions to them the way it does for digital channels.
Instead, we can use correlative analysis, aka our [Metrics Explorer](/docs/metrics-explorer), to understand the potential impact of offline spend.
* Metric Explorer looks for patterns and relationships between offline spend and performance metrics like **First-Time Revenue**. This is a correlation analysis, not causation.
* For example, if you spend \$30,000 on a TV Ad, Northbeam may identify a lift in First-Time Revenue **proportional growth** over that time period and suggest a **possible relationship**.
* You can also use [Custom Labels](/docs/manage-breakdowns) and Regex (Regular Expressions) to separate and analyze different versions of TV Ads in their own campaigns.
* Isolate TV Ad *Version A* vs. *Version B* to measure each one's specific impact on First-Time Revenue.
* Even if TV Spend does not directly increase First-Time Revenue, you might see a **lift** in other digital channels like Google or Meta. This is known as the **halo effect**, where spend in one channel indirectly boosts attributed performance in another.
While attribution is limited, spend efficiency and performance trends can still be analyzed to inform decisions.
Please reach out to your Media Strategist, Customer Success Manager, or contact [Support](https://www.northbeam.io/submit-a-support-ticket) if you have any questions.
# Onboarding FAQs
Source: https://docs.northbeam.io/docs/onboarding-faqs
This FAQ page is designed to help you get comfortable as you navigate Northbeam's MTA
Now that you have successfully set up Northbeam, you may want to go deeper on the following subjects:
#### [Troubleshooting Northbeam Data](/docs/troubleshooting-tracking-issues)
#### [Checking UTM Tracking](/docs/checking-utm-tracking)
#### [Checking Ad Platform Connections](/docs/checking-api-connections)
#### [Gclid, Fbclid, and Redirects](/docs/gclid-fbclid-redirects)
#### [Differences in Ad Performance](/docs/differences-ad-performance)
#### [Differences in Total Revenue and Orders](/docs/why-doesnt-northbeam-match-my-shopify-reporting)
# Need more help?
If you have any other questions or run into something that isn't covered here, our team is here to help you every step of the way. Please reach out to your Customer Success Manager or submit a [Support](https://www.northbeam.io/submit-a-support-ticket) ticket.
# All Pixel Functions
Source: https://docs.northbeam.io/docs/optional-additional-methods
Every function the Northbeam Pixel provides, and where each one is documented.
The Northbeam Pixel adds these functions to `window.Northbeam`. The [Northbeam Pixel](/docs/add-pixel) must be on the page before you call any of them. Each one works the same way on Shopify and custom stores.
| Function | What it does | Documented in |
| :- | :- | :- |
| `fireSlimPurchaseEvent` | Records a completed order. **Recommended.** | [Purchase Events](/docs/purchase-pixel#window-northbeam-fireslimpurchaseevent) |
| `firePurchaseEvent` | The original purchase function. Only its order ID is used | [Purchase Events](/docs/purchase-pixel#window-northbeam-firepurchaseevent) |
| `identify` | Links the visitor to their email address | [Identify Events](/docs/third-party-checkouts#identify-reference) |
| `identifyCustomerId` | Links the visitor to their customer ID | [Identify Events](/docs/third-party-checkouts#identifycustomerid) |
| `trackPageView` | Records a page change on single-page apps only | [Page View Events](/docs/page-view-events) |
| `fireCustomGoal` | Records a custom action, like a sign-up or add-to-cart | [Custom Goals](/docs/setting-up-custom-goals) |
| `fireEmailCaptureEvent` | Records an email sign-up | [Below](#fireemailcaptureevent) |
| `onNorthbeamLoad` | Runs your code as soon as the pixel loads | [Below](#run-code-when-the-pixel-loads-onnorthbeamload) |
***
## `fireEmailCaptureEvent`
Records that a visitor signed up with their email address, for example through a newsletter form.
To track email or SMS sign-ups, we recommend a [Custom Goal](/docs/setting-up-custom-goals) instead.
```javascript theme={null}
window.Northbeam.fireEmailCaptureEvent("john.smith@gmail.com", "klaviyo_footer")
```
| Argument | | Type | Description |
| :- | :- | :- | :- |
| 1 | *required* | String | The email address |
| 2 | | String | Where the email was captured (for example, `"klaviyo_footer"`) |
You don't need to call `identify` after `fireEmailCaptureEvent`. It identifies the visitor automatically.
## Run code when the pixel loads (`onNorthbeamLoad`)
Use this to call a Northbeam function as soon as the pixel is ready. This helps if your code might run before the pixel has loaded.
```javascript theme={null}
```
# Order Definition
Source: https://docs.northbeam.io/docs/order-definition
This page describes Northbeam's semantic definition of an order and how order attributes play a role in determining Subscription or Returning Customer metrics
## Northbeam's Definition of an Order
Different Order Management Systems(OMS) consider the notion of an order differently. For best results, we recommend submitting orders that have been shipped, where the costs associated with the order (and/or other metadata subject to alteration after initial creation) is considered more or less settled.
Because an unfavorable amount of time usually passes between when the order is placed and lands in a customer's OMS also support an initial order submission with 'estimated' costs (i.e. shipping that is quoted at the time of order submission, but may be subject to change) to support timely order attribution (MTA). At the time of shipment, a customer can make an API call to update the order. An call made that includes an order with an `order_id` that matches a previously submitted `order_id` is updated with the most recent call's attributes.
## Order Attributes
Each order has a set of **required** attributes as well as *optional* attributes that can be submitted for each order. These fields are also documented in the [API Reference](https://northbeam-orders-api.readme.io/reference), albeit in much more detail here.
### Required Attributes
Certain metadata is required for an order to be submitted. Without these fields, an API call will return an error as part of our validation check to make sure the Orders contained in an API call pass muster. The following order attributes are required:
* `order_id` - This is the canonical identity of an order for a customer in Northbeam's Order database. This number is typically the same as the id that is used in a customers OMS and must be the same as the `id` that is submitted using Northbeam's [Fire Purchase Event](https://northbeam-pixel-api.readme.io/recipes/fire-purchase-event) recipe from the website. It is important that these two match so that we can pair the website event with the corresponding order.
* `customer_id` - This is the canonical identity of a customer's customer in Northbeam's Order Database. This number is also typically the same as the id that denotes a customer in a customer's OMS and must be the same as the `customer_id` that is submitted using Northbeam's [Fire Purchase Event](https://northbeam-pixel-api.readme.io/recipes/fire-purchase-event) recipe from the website. It is important that these two match so that we can pair the website event with the corresponding order.
* `time_of_purchase` - This field denotes the time at which the order is created/placed. This is also used when aggregating revenue in the platform over time.
* `tax` - the amount in a given currency that was paid as tax for an order
* `currency`- The currency of the order. Note, all monetary 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 product objects describing the products in the order - the list could have only one line item but have at least one member. Similar to `lineItems` in Northbeam's [Fire Purchase Event](https://northbeam-pixel-api.readme.io/recipes/fire-purchase-event)
* `id` - A unique identifier describing the product in the order
* `name` - Name of the product
* `quantity` - How many of the product were sold in the order
* `price` - The price of the product in the currency of the order
* `variant_id` - (**optional**) A unique identifier describing the product variant in the order.
* `variant_name` - (**optional**) The name of the product variant. Cannot be empty when specified.
* `shipping_cost` - The amount that was paid for shipping for this order
### Optional Attributes
The following order attributes are optional
* `customer_email`- the email associated with a customer - not necessary if using Northbeam's [Fire Purchase Event](https://northbeam-pixel-api.readme.io/recipes/fire-purchase-event) - **absolutely necessary** if not using Northbeam's [Fire Purchase Event](https://northbeam-pixel-api.readme.io/recipes/fire-purchase-event) and using Northbeam's [Identify](https://northbeam-pixel-api.readme.io/recipes/identify) recipe instead
* `customer_phone_number`- The phone number associated with a customer
* `customer_name`- The name associated with a customer
* `customer_ip_address` - The IP address associated with a customer
* `discount_codes`- a list of strings that resemble Coupons or discount codes used in the order - similar to `coupons` in Northbeam's [Fire Purchase Event](https://northbeam-pixel-api.readme.io/recipes/fire-purchase-event)
* `discount_amount`- The amount of money discounted due to discount codes in the currency of the order
* `order_tags`- A list of internal tags describing the order - these tags may also be used to denote the subscription stage or customer stage of the order, as well as for exclusions to exclude orders that you do not seek to have attributed - to learn more read on in Subscriptions, Customer Stage, and Exclusions.
* `is_recurring_order`- a boolean value that denotes whether or not this order is part of a recurring purchase (subscription)
* `refunds` - A list of product objects describing the refunded products
* `product_id` - A unique identifier describing the product in the refund (should also be included in the products list). If an entry is made in the optional `refunds` object, this field is required.
* `quantity`- The number of products refunded (should be less than or equal to the corresponding quantity in the products list). If an entry is made in the optional `refunds` object, this field is required.
* `refund_amount` - The total amount refunded to the customer in the currency of the order. If an entry is made in the optional `refunds` object, this field is required.
* `refund_cost` - The estimated total cost of the refund, including the refund amount to the customer and any other overhead costs (i.e. shipping, fees). If an entry is made in the optional `refunds` object, this field is required.
* `refund_made_at` - The time the refund was fulfilled by your brand. ISO-8601 timestamp. If an entry is made in the optional `refunds` object, this field is required.
* `variant_id` - A unique identifier describing the variant of the product in the refund (should also be included in the products list). This field is entirely optional but should be included if the refund is for a product and a `variant_id` was provided in the `products` field.
* `customer_shipping_address` - an object that captures the shipping address for the order
* `address1`- The street address of a customer's shipping address. If an entry is made in the optional `customer_shipping_address` object, this field is required.
* `address2` - An optional additional field for the street address. If an entry is made in the optional `customer_shipping_address` object, this field is required.
* `city` - The city or locality of a customer's shipping address. If an entry is made in the optional `customer_shipping_address` object, this field is required.
* `state` - The state or region of the customer's shipping address. If an entry is made in the optional `customer_shipping_address` object, this field is required.
* `zip` - The postal code or region-code (in outside US) of the customer's shipping address. If an entry is made in the optional `customer_shipping_address` object, this field is required.
* `country code` - A three-letter ISO 3166 country code of a customer's shipping address. If an entry is made in the optional `customer_shipping_address` object, this field is required.
## Roles of `order_tags` of an order
Order tags play a wide variety of roles when it comes to an how ads that may have driven the order are attributed. Order tags are used in determining if the order is
* part of a subscription, and if it is a first-time or a recurring order.
* from a first time or returning customer
* whether the order is to be excluded from attribution altogether
### Subscriptions
Northbeam's customers often want to be ad attribution or revenue as a function of whether the orders are part of a subscription initiation or part of a recurring order. Order tags are used here so that we may identify order that are part of a first time subscription order or if they are a recurring order.
Using the `Subscription Order Tags` page in the `Settings` Section of your Northbeam Dashboard, a customer can choose which order tags are associated with which stage of a subscription - thus enabling them to delineate between first time or recurring subscription order and revenue. A category `Other` is also included to capture orders that could be either.
### Customer Stage
Order tags can also play a role in determining if the order is from a first time or returning customer. By default, the logic we apply to determine if an order is form a first-time or returning customer is by taking all orders from a particular `customer_id` and looking at the orders as a function of time. The first order in the sequence is a first-time customer, and all subsequent orders are labeled returning customer.
If this logic is insufficient for your use case, please contact `success@northbeam.io` and consult us on how we can leverage your order tags to capture the logic you seek to leverage!
This delineation can be used to analyze orders (and revenue) as a function of both of these customer stages.
### Order Exclusions
There are certain cases where it is desire-able to exclude certain orders altogether. This may be the case if you are looking to do ad attribution or analyze revenue as a function of web store orders but your OMS also includes orders that came from a brick and mortar store. If these undesire-able orders are tagged with a specific tag, these can be added to the `Exclude Orders by Tag` section in the `Settings` page of your Northbeam dashboard.
# Order Segmentation
Source: https://docs.northbeam.io/docs/order-segmentation
Order Segmentation makes it easy to break down attributed revenue and orders into meaningful groups directly within your Northbeam dashboard.
## Introduction
Order Segmentation makes it easy to break down attributed revenue and orders into meaningful groups directly within your Northbeam dashboard.
You can create segmentations using:
* Order tags
* Discount codes
* Shipping country
For example, you could create a **Promo Code** segmentation to group orders based on the discount code used.
**Segmentation:** `Promo Code`
**Segments:**
* Podcast
* YouTube
* IG Influencers
* Friend Referrals
Each segment can contain the discount codes associated with that group.
For example, the **Podcast** segment could include all promo codes used by podcast partners, while the **YouTube** segment could include promo codes used by YouTube creators.
Northbeam will then assign orders to the appropriate segment based on the discount code used on the order.
Once created, you can compare Revenue, Orders, ROAS, CAC, and other supported metrics across each segment alongside your existing performance data.
This gives you a fast way to answer questions like:
* How much revenue came from podcast promo codes?
* How many new customers came from influencer codes?
* How does CAC compare across different partner groups?
Previously, this type of reporting often required custom workarounds or separate dashboards. Order Segmentation lets you create and manage these groups directly in Northbeam.
***
## Before You Start
Order Segmentation is the **easiest way** to **break down order groups** directly within a **single Northbeam dashboard**. It is quick to set up and does not require custom development or coordination between your development team and Northbeam.
Separate dashboards can offer more flexibility for specific use cases, but they require additional setup and development work on both sides and are only available on certain service plans.
## Current Limitations
* **All attribution models except Clicks + Deterministic Views support segmented reporting.** Clicks + Deterministic Views can still appear in your dashboard for overall performance, but they cannot currently be broken down by segment.
* **Spend and Visits are not segmented.** ROAS, CAC, and ECR use the row's total Spend or Visits.
* **Segmented metrics refresh once per day.** For the cleanest comparison, use a date range that ends yesterday.
* **Hourly reporting is not supported.** Segmented metrics are available at the daily level.
For more detail, see [Important Constraints](#important-constraints).
***
## Step 1: Open Order Segmentation
Open [Order Segmentation](https://dashboard.northbeam.io/order-segmentations).
If you do not see Order Segmentation in your account, contact Northbeam and we can enable it for you.
***
## Step 2: Create Your Segmentation
Click **Add Segmentation**.
Think of a **segmentation** as the overall category and **segments** as the groups within it.
For example:
**Segmentation:** `Promo Code`
**Segments:**
* Podcast
* YouTube
* IG Influencers
* Friend Referrals
This setup lets you compare performance based on the type of promo code used on an order.
***
## Step 3: Add Segment Rules
For each segment, define the rules Northbeam should use to match orders.
You can currently build rules using:
* Order tags
* Discount codes
* Shipping country code
For example, a Podcast segment could use:
`Discount code` → `is one of` → `[list of podcast promo codes]`
Use **Bulk edit** when adding a larger list of values.
You can also use:
* **AND conditions** when multiple conditions must be true
* **OR groups** when an order can match one of several sets of conditions
Supported operators include:
* Equals
* Contains
* Starts with
* Ends with
* Is one of
* Does not equal
* Does not contain
* Case-insensitive versions of supported operators
### Order-level attributes only
Rules currently support order-level attributes.
Rules based on SKU, product, or order value are not currently supported.
***
## Step 4: Set Segment Priority
Segments are evaluated from **top to bottom**.
If an order matches more than one segment within the same segmentation, the **first matching segment wins**.
For example:
1. Podcast
2. YouTube
3. IG Influencers
If an order matches both Podcast and YouTube, Northbeam assigns it to **Podcast** because Podcast has the higher priority.
Drag and reorder segments to change their priority.
An order can only match **one segment within the same segmentation**.
However, the same order can belong to segments across different segmentations.
For example:
* `Promo Code: Podcast`
* `Market: United States`
***
## Step 5: Test Your Segmentation
Before saving, click **Test** in the upper-right corner.
Northbeam will show how many orders matched each segment during the selected lookback period.
You can test against the last:
* 7 complete days
* 14 complete days
* 30 complete days
* 60 complete days
* 90 complete days
The test counts **orders**, not attributed revenue.
Use the test to confirm:
1. Your rules match the orders you expect.
2. Your segment priority is correct.
3. Orders are not unexpectedly falling into `Uncategorized`.
### What does `Uncategorized` mean?
`Uncategorized` contains orders that did not match any segment in that segmentation.
If your counts look lower than expected, check `Uncategorized` first.
You can also click **View matched orders** to review the individual orders assigned to each segment.
***
## Step 6: Choose Your Metrics
Revenue and Orders are available for each segment, including New and Returning customer variants.
You can also enable:
* ROAS
* CAC
* ECR
* AOV
For example, a Promo Code segmentation could create metrics such as:
* Promo Code: Podcast Revenue
* Promo Code: Podcast Orders
* Promo Code: Podcast CAC
* Promo Code: YouTube Revenue
* Promo Code: IG Influencers Revenue
## How Spend and Visit Metrics Work
Order Segmentation only splits **conversion-based metrics**, such as Revenue and Orders.
It does **not** split:
* Spend
* Visits
This means segment-level Spend and Visits do not exist.
Metrics that depend on Spend or Visits use the row's total value:
* **Segment ROAS** = `Segment Revenue / Total Spend`
* **Segment CAC** = `Total Spend / Segment Orders`
* **Segment ECR** = `Segment Orders / Total Visits`
### Spend and Visits are not segmented
For example, Podcast CAC uses total row Spend divided by Podcast Orders. It does not use Podcast-specific Spend.
***
## Step 7: Save and View Your Segments
Once your setup looks correct, click **Save**.
Changes apply to historical orders immediately. There is no historical backfill to wait for because Northbeam evaluates the segmentation rules when the data is queried.
To add segment metrics to the Sales page:
1. Open the [Sales page](https://dashboard.northbeam.io/sales).
2. Click **Customize Table**.
3. Find **Order segments**.
4. Select the metrics you want to add.
***
## Segment Combinations
Segment Combinations let you combine existing segments into a broader reporting group.
For example, if your Promo Code segmentation contains:
* Podcast
* YouTube
* IG Influencers
* Friend Referrals
You could create a combination for:
`Podcast + YouTube + IG Influencers`
This lets you keep the individual segments while also reporting on the combined group.
To create a Segment Combination:
1. Open the **Segment Combinations** tab.
2. Select the segmentation.
3. Select the segments you want to combine.
4. Enter a name.
5. Click **Test**.
6. Click **Save**.
***
## Supported Reporting
Order Segmentation is currently supported in:
| Surface | Support |
| - | - |
| Sales | Segment metrics can be added as columns |
| Metrics Explorer | Segment metrics can be selected like other metrics |
| Creative Analytics | Segment metrics can be added to creative reporting |
| Overview | Segment metrics can be used in tiles |
| Custom Metrics | Segment metrics can be used in formulas |
| Orders | View matched segments and filter orders by segment |
Order Segmentation is not currently supported in:
* Data Export
* Scheduled Reports
* Profit Benchmarks
* MMM
* Incrementality
* LTV
* Model Comparison
* Performance Alerts / Monitor
* Hourly reporting
* Clicks + Deterministic Views
***
## Important Constraints
## Touchpoint-Based Metrics Refresh Once Per Day
Order Segmentation uses Northbeam's touchpoint-based metrics.
These metrics are rebuilt **once per day**. This is the same cadence used by other features that rely on touchpoint data.
Examples include:
* Order Segment metrics
* Clicks + Deterministic Views
* Custom Metrics that depend on touchpoint-based metrics
Standard metrics may update more frequently.
Because of this, date ranges that include **today** can show differences between Order Segment metrics and fresher standard metrics.
For the cleanest comparison, use a date range that ends **yesterday**.
Hourly reporting is not currently supported.
## Attribution Model Support
Order Segmentation supports **all attribution models except Clicks + Deterministic Views**.
Clicks + Deterministic Views can still appear in your dashboard for overall performance, but Northbeam cannot currently break those results down by Order Segment.
For example, Northbeam can show your total Clicks + Deterministic Views Revenue, but cannot split that revenue into Podcast, YouTube, or other Order Segments.
## Unmatched Orders
Orders that do not match a defined segment fall into:
`Uncategorized`
Include `Uncategorized` when reconciling segment totals.
***
## Order Segmentation FAQ
## Do I need to wait for a backfill?
No. New and edited segmentations can apply to historical orders immediately.
## What does `Uncategorized` mean?
`Uncategorized` contains orders that did not match any segment within that segmentation.
## Can an order match multiple segments?
Within the same segmentation, no.
If an order matches multiple segments, the first matching segment wins.
Across different segmentations, yes.
## Can I change segment priority?
Yes. Drag and reorder your segments.
Northbeam evaluates them from top to bottom.
## Can I preview a segmentation before saving?
Yes. Click **Test** to see how many orders match each segment.
The test counts orders, not attributed revenue.
## Can I use segment metrics in Custom Metrics?
Yes. Supported Order Segment metrics can be used in Custom Metrics.
## Can I export segment metrics?
No. Segment metrics are not currently supported in Data Export or Scheduled Reports.
## Does Order Segmentation support hourly reporting?
No. Segmented metrics are available at the daily level and refresh once per day.
## Which attribution models support Order Segmentation?
Order Segmentation supports all attribution models except **Clicks + Deterministic Views**.
Clicks + Deterministic Views can still be used for overall performance reporting, but cannot currently be broken down by Order Segment.
## Why don't my segment totals match standard Revenue?
Check the following:
1. **Does your date range include today?** Segmented metrics refresh once per day, while some standard metrics may update more frequently.
2. **Are orders falling into **`Uncategorized`**?** Include `Uncategorized` when reconciling your totals.
## Does Order Segmentation work with Amazon orders?
Partially.
Shipping country and discount code rules can work with Amazon orders.
Amazon does not provide merchant-created order tags in the same way Shopify does. Rules based on Shopify or Orders API order tags will generally not match Amazon orders and may fall into `Uncategorized`.
Amazon PII is also removed after 90 days, so keep this in mind when reviewing older Amazon order data.
# Order Tags
Source: https://docs.northbeam.io/docs/order-tags
Order Tags are used to label orders within Northbeam. This begs the question -- why would I need to label my orders?
## What are Order Tags?
Order Tags is a piece of data (usually a word or words) attached to an order. In Northbeam, they're used to label special type of orders type of orders.
## What are Order Tags used for?
Order Tags have two primary uses within Northbeam:
1. Addressing Unattributed Orders
2. Subscription Orders
## 1. Addressing Unattributed Orders
Order Tags are meant to exclude any Unattributed Orders that we expect to be Unattributed. This is an extremely important step of the Onboarding Process called Data Validation. Learn more about Unattributed [here](/docs/differences-in-unattributed-data#orders-appear-as-unattributed).
## 2. Subscription Orders
Order Tags are also used for Subscription Orders. We use tags to distinguish between One-Time Orders and Subscription Orders. To take it one step further, tags are also used to distinguish between First Time Subscription Orders and Recurring Subscription Orders.
***
## Step 1: Placing Order Tags
Tags are to be placed through your Order Management System, which will sync with Northbeam.
* **Shopify Brands** -- Tags placed on the Order level (or Customer level). See Shopify docs [here](https://help.shopify.com/en/manual/shopify-flow/reference/actions/add-order-tags). Once tags are placed on your respective orders, our native Shopify connector will import the tags.
* **All Other Platforms (WooCommerce, Magento, Custom)** -- Tags are to be passed through the Orders API. During your onboarding process, a REST API was set up to send POST requests to our server. Within our [API docs](https://northbeam-orders-api.readme.io/reference/post_orders), you'll see an object called `order_tags`. Please pass tags using this object for all appropriate orders.
## Step 2: Checking Order Tags
Once the Tags are set up in your Order Management System (ex. Shopify or Orders API), it's important to make sure they're getting pulled into your dashboard.
The [Orders page](https://dashboard.northbeam.io/orders) is a perfect place to do this.
1. On the left navigation, click the **Shopping Cart icon**
2. Scroll down to the **table**
3. Click the column called **"Tags"** and see if they're getting pulled through for all necessary orders
4. **If there's lots of volume**, it may be easier to export the data by clicking **"Export Data"**
## Step 3: Applying Order Tag Exclusions
Great! Once you've confirmed that the tags are in, let's exclude using the Order Exclusion tool.
To find Order Exclusion tool:
1. Open [Excluded Orders](https://dashboard.northbeam.io/settings/excluded-orders).
2. Click **Add Exclusion**
3. Populate the **Tag Type, Logic**, and **Tag Name**
4. Don't forget to toggle it to **Active**
## Step 4: Seeing your Excluded Orders
As a result, all orders with an excluded tag will be grouped into the platform called "Excluded". These can be seen on the Sales Page.
1. Open the [Sales page](https://dashboard.northbeam.io/sales).
2. Toggle to the **Campaign Level** and apply the **Platform breakdown**
3. Expand the **Excluded** group and you'll see the individual tags, along with associated transactions and revenue
1. Labeled as `Excluded: [Tag Name]`
## Step 5: Filtering out Excluded (Optional)
When an order is Excluded, it's moved to the group named "Excluded" and the associated Transactions and Revenue are still included in the view.
If we want to remove these, we can use the **Filter** function.
### Filtering in the Sales Page
### Filtering in the Overview Page
# Orders API
Source: https://docs.northbeam.io/docs/orders-api
Learn how to send order data to Northbeam using the Orders API, with steps for setup, validation, backfilling, and monitoring.
**The Northbeam Orders API is a customizable solution specific to your business.**
You will use this API to actively push order data to Northbeam by making POST requests to `https://api.northbeam.io/v2/orders`.
Full API reference: [/reference/post\_orders-1](/reference/post_orders-1).
## Get API credentials
* Open [API Keys](https://dashboard.northbeam.io/settings/api-keys) in your Northbeam dashboard.
* Click **Create new API key** to generate:
* **Authorization** (API Key)
* **Data-Client-ID** (Client ID)
| Header | Value | Description |
| - | - | - |
| `Authorization` | `` | Your Northbeam API key |
| `Data-Client-ID` | `` | Your Northbeam client ID |
| `Content-Type` | `application/json` | Tells the API you’re sending JSON |
**Production endpoint:** `https://api.northbeam.io/v2/orders`
**Example (cURL):**
```curl theme={null}
curl --request POST \
--url https://api.northbeam.io/v2/orders \
--header 'Authorization: ' \
--header 'Data-Client-ID: ' \
--header 'Content-Type: application/json' \
--data @orders.json
```
These headers are **required for every request**. Without them, the Orders API will reject your call.
## Build your payload
All of these fields are required for full functionality in Northbeam. Full API reference: [/reference/post\_orders-1](/reference/post_orders-1).
| Field | Type | Description |
| :- | :- | :- |
| `order_id` | string | Unique identifier for the order. Must match the `id` in [firePurchaseEvent](https://northbeam-pixel-api.readme.io/recipes/fire-purchase-event) so we can pair website events with orders. |
| `customer_id` | string | Must be unique per customer in your OMS. |
| `customer_email` | string | The email associated with the customer. |
| `time_of_purchase` | date-time (ISO-8601) | Must be in ISO-8601 format. **Must occur AFTER the frontend [firePurchaseEvent](https://northbeam-pixel-api.readme.io/recipes/fire-purchase-event).** Include a timezone offset if not reporting in UTC. **Example:** FPE timestamp = `2025-09-29T15:30:00Z` ❌ `2025-09-29T15:00:00Z` (too early) ✅ `2025-09-29T15:31:00Z` (UTC) ✅ `2025-09-29T15:31:00-07:00` (with offset) |
| `currency` | string | ISO-4217 currency code (e.g., USD). All monetary fields assume this currency. |
| `purchase_total` | number | Total collected including tax, shipping, and fees. |
| `tax` | number | Amount paid as tax. Required if you want taxes deducted from revenue in reporting. |
| `shipping_cost` | number | Amount paid for shipping. Required if you want shipping deducted from revenue in reporting. |
| `products` | array of objects | Must contain at least one product. **Required keys:** `id` (string), `name` (string), `quantity` (number), `price` (number) **Optional keys:** `variant_id` (string), `variant_name` (string) |
| `order_tags` | array of strings | Required for offline orders. Used to mark subscription stage or exclude orders from attribution. |
| `refunds` | array of objects | Used to keep revenue calculations correct. **Required keys:** `product_id` (string), `quantity` (number), `refund_amount` (number), `refund_made_at` (date-time) If you want refunds broken out in reporting, you must also include an `order_tag`. |
| `customer_shipping_address` | object | Enables Customer LTV reporting by region and state. **Required keys if included:** `address1` (string), `address2` (string), `city` (string), `state` (string), `zip` (string), `country_code` (string) |
| `discount_codes` | array of strings | Enables Customer LTV by discount code. |
| `discount_amount` | number | Required if you want discounts broken out in dashboard reporting. |
### Example payload
```json theme={null}
[
{
"order_id": "abc-123",
"customer_id": "def-456",
"customer_email": "example@gmail.com",
"time_of_purchase": "2025-09-29T15:31:00Z",
"currency": "USD",
"purchase_total": 110.99,
"tax": 5.00,
"shipping_cost": 10.99,
"products": [
{
"id": "prod-1",
"name": "Sample Product",
"quantity": 1,
"price": 95.00,
"variant_id": "var-1",
"variant_name": "Size M"
}
],
"order_tags": [
"Online Order",
"Subscription First"
],
"refunds": [
{
"product_id": "prod-1",
"quantity": 1,
"refund_amount": 10.00,
"refund_made_at": "2025-09-30T10:00:00Z"
}
],
"customer_shipping_address": {
"address1": "123 Main St.",
"address2": "Apt. 1A",
"city": "San Francisco",
"state": "CA",
"zip": "94112",
"country_code": "USA"
},
"discount_codes": [
"WELCOME10"
],
"discount_amount": 10.00
}
]
```
## Verify your payload
Before sending the orders, confirm your payload structure and values are valid. Most issues come from malformed payloads or missing fields.
**Common validation checks:**
* ✅ `order_id` must be unique per order and match the `id` used in `firePurchaseEvent`.
* ✅ `time_of_purchase` must be **AFTER** the corresponding `firePurchaseEvent` timestamp and in proper ISO-8601 format with timezone offset.
* ✅ `products` array must include at least one product with `id`, `name`, `quantity`, and `price`.
* ✅ `currency` must be a valid ISO-4217 code (e.g., `USD`, `EUR`).
* ✅ `customer_email` must match the email on the actual order in your OMS (case-sensitive in some systems).
* ✅ `customer_id` accuracy is critical – this is what Northbeam uses to distinguish between new and returning customers. If it’s inconsistent (e.g., mixing Shopify IDs and internal IDs), customer LTV and new/returning logic will be incorrect.
* ✅ `order_tags` are required and used for two main purposes:
* **Subscriptions** – Use distinct tags to separate:
1. First-time subscription orders (subscription starts)
2. Recurring subscription renewals (auto-charges that happen in the backend)
* **Offline Orders** – Tag any orders not placed through your live production website (and therefore without frontend pixel events). Our team excludes these from diagnostics monitoring.
* ✅ `refunds` objects must include `product_id`, `quantity`, `refund_amount`, and `refund_made_at`.
* ✅ If including `customer_shipping_address`, all required subfields (`address1`, `city`, `state`, `zip`, `country_code`) must be present.
Order tags are **very important for our data validation phase**.
We cross-check pixel events against raw order data. If tags are missing or incorrect and large discrepancies appear, we’ll need to investigate further — which can prolong the implementation process.
**Common mistakes to avoid:**
* ❌ Using inconsistent `customer_id`s (e.g., switching between Shopify and internal IDs)
* ❌ `time_of_purchase` set **BEFORE** the frontend pixel fire
* ❌ Untagged **subscription orders**, which prevents [Subscription Analytics](/docs/subscription-analytics) from working correctly
* ❌ Untagged **offline orders**, leading to large discrepancies in pixel vs. order data. This prolongs our data validation process.
* ❌ Missing `products` array or leaving it empty
* ❌ Currency not set as a valid ISO-4217 code (e.g., using “US Dollars” instead of `USD`)
## Backfill historical orders
Backfilling your historical data is extremely important. This ensures your Customer LTV is complete. This is also key for accurate New and Returning Data.
**Accurate New and Returning Data**
Northbeam determines whether a customer is **new** or **returning** based on the `customer_id` attached to each order. Without historical orders, someone who purchased in the past but buys again today will be counted as a **new** customer — because their first order isn’t in the system.
**Backfilling ensures repeat customers are recognized correctly.**
**What to send**
* Send all historical orders you want in Northbeam (recommended: up to 5 years).
* Use the same payload format from [Build your payload](#build-your-payload).
* Keep `order_id` stable; resending the same `order_id` overwrites the prior record.
**How to send**
* Batch up to **1000 orders per request**.
* Backfill in time windows (for example, month by month).
Backfilling is only required for new onboards. If your historical orders already exist for any reason (e.g., transition from Shopify to the Orders API), this step isn’t needed.
## Set up ongoing batches
After history is loaded, keep Northbeam up to date with regular batches.
**Cadence**
* Northbeam processes on your plan frequency, not in real time.
* Send **at least 2× more frequently** than your plan’s processing cadence.
* Example: on a 4× per day plan, send **8× per day**.
**Batching**
* Up to **1000 orders per request**.
* Include new and changed orders since the last run.
* Resend modified orders using the same `order_id`.
**Operational notes**
* **Retries**: if a request fails, retry the same batch; using the same `order_id`s is safe.
* **Idempotency**: the latest record for an `order_id` takes priority.
**Implementation tip:** most teams set this up as a scheduled job (e.g., cron, Airflow, or a serverless function like AWS Lambda).
## Test in sandbox (optional)
Use the UAT endpoint to validate payloads before sending real data to production.
**Sandbox endpoint:** `https://api-uat.northbeam.io/v2/orders`
You can test without production keys by using these header values. Testing with your real keys also works, but the sandbox database is purged periodically, so treat it as a testing environment only.
```
--header 'Authorization: None'
--header 'Content-Type: application/json'
--header 'Data-Client-ID: test'
```
**Sandbox testing notes**
* The sandbox does **not save orders** — it only checks that your payload is valid.
* A “pass” response confirms the request structure is correct, but it does **not** validate the actual numbers.
**For full validation of values (totals, tax, discounts, etc.)**, send test data to the production endpoint. We can remove those test orders for you afterward if needed.
## Data diagnostics
Northbeam provides a diagnostics tool to help you monitor Orders API activity in production.
If there are any issues with your API upserts, errors will appear here with details to help you debug. Common causes include **malformed payloads** or **missing required fields**.
### Where to find it
In the Northbeam dashboard:
1. Open [Data Diagnostics](https://dashboard.northbeam.io/settings/tracking-events).
### Error table
Each error entry includes:
* **Request ID**
* **Error message**
* **Error type** (e.g., `payload_validation_error`)
* **Timestamp of error**
* **Link to request** for deeper inspection
**Tip:** most errors are due to **missing required fields** or **invalid payload format**.
Fix the payload and resend with the same `order_id` — the latest record will take priority.
### Error trends
* A chart shows API error counts over time (1–30 day ranges available).
* Errors typically appear within **1–3 minutes** after they occur.
* Use this view to identify spikes or recurring issues.
**Monitoring:** this view is most helpful for spotting systemic issues (e.g., a bad deploy or recurring field mismatch) rather than one-off errors.
# Limits
Source: https://docs.northbeam.io/docs/orders-api-limits
This Page describes the limitations of the Orders API and suggested uses
The Orders API upsert function allows for uploads of order batches. While the API has a hard limit of 1000 orders per call, we recommend using the order size per call that best suits your needs.
## Rate limits
Order upload requests are rate-limited per API key by the total request-body size sent over a sliding time window.
| Endpoint | Limit per API key |
| - | - |
| `POST /v1/orders` | 30 MB per 60 seconds |
| `POST /v2/orders` | 30 MB per 60 seconds |
| `PATCH /v2/orders` | 30 MB per 60 seconds |
The budget is shared across all three endpoints — bytes sent to any of them count toward the same 30 MB / 60 s window per API key.
## Response when rate-limited
When the limit is exceeded, the API responds with:
* HTTP status `429 Too Many Requests`
* `Retry-After` header with the number of seconds until you can retry
* JSON body:
```json theme={null}
{
"error": "rate_limit_error",
"retry_after_seconds": 37
}
```
# Orders
Source: https://docs.northbeam.io/docs/orders-tracking
Customer journey tracking.
## What is the Orders page?
Open the [Orders page](https://dashboard.northbeam.io/orders).
This page allows you to understand what is driving purchases and the data can also understand the average number of touchpoints it takes someone to convert, as well as what the most common touchpoints are.
Find a walkthrough of our Orders Page, which dives into the following areas:
* Timeframe
* Granularity
* E-Com Platforms
* Ad Platform
## Orders Page Walkthrough Video
## Orders Page FAQs
**Can I search for an Order's ID?**
* Yes, you can search for the ID in the search box at the top of the chart.
## ✅ You're all done with our Attribution Home Page Guide
This Orders feature uncovers how many interactions it typically takes before a purchase, and which channels play the most influential role in the customer journey.
Now that you understand how conversions happen and what's driving your sales, it's time to take a look at your correlation analysis and marketing metrics over time. Let's move on to **Metrics Explorer**.
# Overview Home Page
Source: https://docs.northbeam.io/docs/overview-page
This is your Northbeam starting point.
The **Overview Home Page** is the first page you see when you log into Northbeam. [Open Overview](https://dashboard.northbeam.io/overview).
The dashboards here are built to **visualize** the KPIs that are most important for your business and give you a sense of your **overall business metrics** on any given day.
* [Attribution Models](/docs/attribution-models)
* **Clicks-Only**: credit is *divided equally* among all touchpoints, **excluding bottom-funnel** touchpoints (direct search, branded search, email, SMS).
* The credit that would normally be given to bottom-of-funnel channels is reattributed equally to top-of-funnel channels (linear).
* **First Touch:** credit is *fully* given to the *first* touchpoint.
* **Last Touch**: credit is *fully* given to the *last* touchpoint.
* **Last Non-Direct Touch**: credit is *fully* given to the *last* touchpoint, **excluding direct** site visits.
* This attribution model matches up closest to what most platforms report as "last click."
* [Attribution Windows](/docs/attribution-windows)
* **1-Day Click** (common attribution window)
* **3-Day Click**
* **7-Day Click** (common attribution window)
* **14-Day Click**
* **30-Day Click** (common attribution window)
* **90-Day Click**
* **LTV (Lifetime Value)**
* [Accounting Modes](/docs/accounting-modes)
* **Cash Snapshot:** best for reporting purposes and budget-setting
* This matches most to what you see in your Shopify or your backend e-commerce software.
* **Accrual Performance:** best for daily media buying decisions
* **Granularity**: The level of detail on your metrics can be seen *Monthly*, *Weekly*, or *Daily*, allowing for a broad-scope analysis of performance.
* These various views help teams optimize daily operations while giving executives a broader, more strategic view over time.
* **Time Period**: The date range you want to analyze.
* **Time Comparison**:
* **Previous Period (common)**
* **Same period, prior year**
* **Same period, different year**, or
* **Customize**
Recommended Dashboard Settings:
* **Attribution Model**: Clicks-Only
* **Attribution Window**: 1 Day, 7 Day, 30 Day (this depends on how long your sales cycle is as well as your price points)
* **Accounting Mode**: Cash Snapshot
* **Granularity**: Weekly
* **Time Period**: Monthly (to see month over month on a weekly basis)
* **Time Comparison**: Previous period
## Overview Page Video Walkthrough
### Full Customization
You are able create or rearrange tiles on your Dashboard to showcase KPIs like ROAS, CAC, and transaction data.
* You can change your metrics, rename views, and save customized dashboards for quick access.
* These views are shared across your team.
### Conversion Lag
Under **+ADD TILES**, there are various options to choose from, one of which is **Conversion Lag** charts.
* These charts allow you to show true marketing dollars over time and answer the questions *what am I spending today?* and *what impact will this have on revenue in the future?*
* Marketing touchpoints that accrued today can influence revenue that happens tomorrow.
* Most businesses will utilize a 7-90 Day Window. Your precise window depends on your consideration period:
* How long is your sales cycle?
* How long does it take on average for someone to make a purchase decision?
Recommended Conversion Lag Settings:
* *Attribution Mode*: Clicks + Modeled Views
* *Attribution Window*: 1 day click/1 day view
* *Accounting Mode:* Accrual performance
* *Granular*: Daily
* *Time Period*: 60 days
ℹ️ Businesses with higher price points may see a longer conversion period, so balance your payback period by answering the following:
* How long can you wait before you see that revenue come back?
* How long does it typically take someone to make a purchase decision?
## ✅ Let's keep going
Now you've gotten familiar with the Overview Home Page, you're ready to move forward.
Next is the Attribution Home Page, where you'll learn how Northbeam tracks the full customer journey.
# Data & terminology
Source: https://docs.northbeam.io/docs/overviews/data-terminology
Models, modes, and the honest metric definitions
The language of your data. These articles define how Northbeam assigns credit, what each metric means, and how to read the numbers honestly — the reference you'll come back to whenever a number needs interpreting.
## What you'll do
* Learn the attribution models, windows, and accounting modes
* Look up metric definitions and data sources
* Interpret numbers — good, bad, and hard-to-track
## Attribution fundamentals
***
**Next section:** [Platform](/docs/overviews/platform)
# Features overview
Source: https://docs.northbeam.io/docs/overviews/features
The cross-cutting tools you invoke in the app
Features are the tools that work across every page of the dashboard:
* [Manage breakdowns and saved views](/docs/manage-breakdowns)
* [Profitability benchmarks](/docs/profitability-benchmarks)
* [Model Comparison tool](/docs/what-is-northbeam-model-comparison-tool)
* [Exporting data](/docs/exporting-data) and [Touchpoints export](/docs/touchpoints-export)
* [Subscription analytics](/docs/subscription-analytics)
Use the buttons at the top of the sidebar to switch to the
**Changelog** (what shipped) or **Troubleshoot** (when numbers don't
match).
# Onboarding
Source: https://docs.northbeam.io/docs/overviews/onboarding
What this section covers, and where to start
Everything required to take a new account from empty to reporting real data. Work through it roughly in order — account setup first, then tracking, then orders and spend. Each chapter builds on the one before.
## What you'll do
* Set up your account and invite your team
* Install the pixel and event tracking on your store
* Bring in orders and marketing spend so attribution has data to work with
## Overview
***
**Next section:** [Channels](/docs/landings/channels)
# Platform
Source: https://docs.northbeam.io/docs/overviews/platform
The surfaces of the Northbeam dashboard
A tour of the product, surface by surface: the dashboards, sales and attribution pages, creative analytics, orders, and the features that tie them together — plus what to do when numbers don't match.
## What you'll do
* Learn what each dashboard surface shows and how to configure it
* Understand the products behind the numbers — MTA, Incrementality, MMM, Apex
* Troubleshoot tracking and reconcile mismatches
## Platform
***
**Next section:** [Use cases](/docs/overviews/use-cases)
# Products overview
Source: https://docs.northbeam.io/docs/overviews/products
The measurement stack, and how the pieces relate
Northbeam's products answer different questions and work together:
* **Multi-Touch Attribution (MTA)** — daily attribution across channels, ads, and creatives
* **Incrementality** — controlled experiments that measure causal lift
* **Mixed Media Modeling (MMM)** — long-run channel contribution to revenue
* **Apex** — send Northbeam attribution to Meta
* **AI** — connect Northbeam to Claude and query your data
MTA reports daily, incrementality tests what caused it, and MMM sets
the long-run mix — results feed back into each other.
# Use cases
Source: https://docs.northbeam.io/docs/overviews/use-cases
Outcome-first guides that cut across the docs
Recipes for the questions you actually bring to Northbeam — diagnosing discrepancies, deciding budget moves, running reports. Each article walks one question end to end using tools from the rest of the docs.
## What you'll do
* Diagnose and reconcile numbers you don't trust yet
* Decide and optimize where spend goes
* Operate and report, week to week
## Diagnose & reconcile
***
**Next section:** [Changelog](/docs/landings/changelog)
# Page View Events
Source: https://docs.northbeam.io/docs/page-view-events
Track page changes on single-page apps. Most sites don't need this.
**Most sites don't need anything on this page.** The [Northbeam Pixel](/docs/add-pixel) tracks page views automatically every time a page loads.
You only need this if your site is a **single-page application (SPA)**: a site that changes pages without a full reload.
## Which setup you need
| Your store | What to do |
| :- | :- |
| **Shopify** with a standard theme | Nothing. The pixel handles page views. |
| **Shopify** headless storefront with normal page loads | Nothing. The pixel handles page views. |
| **Shopify** headless storefront that's a single-page app (for example, Hydrogen) | Add `trackPageView`. **Follow this page.** |
| **Custom** site with normal page loads | Nothing. The pixel handles page views. |
| **Custom** single-page app (for example, Next.js, Nuxt, or React Router) | Add `trackPageView`. **Follow this page.** |
Not sure which you have? Ask your developer whether the site is a single-page app.
## How it works
On a normal website, every page change is a full page load. The pixel records a page view each time.
On a single-page app, the URL changes but the page doesn't reload. The pixel doesn't run again, so those page views go **untracked**. To fix this, call `trackPageView()` each time the page changes:
```javascript theme={null}
window.Northbeam.trackPageView();
```
It takes no arguments. It records the page's current URL.
**Only call `trackPageView()` when the page changes without a reload.**
The pixel already records a page view on every full page load. Calling `trackPageView()` on full page loads too will create **duplicate page views**.
Before you start, make sure the [Northbeam Pixel](/docs/add-pixel) is installed on every page. `trackPageView()` won't work until the pixel has loaded.
***
## Option A: Google Tag Manager
Use this if you manage scripts through Google Tag Manager.
### Step 1: Confirm the pixel tag is in Google Tag Manager
The Northbeam Pixel must be its own tag, firing on **All Pages**. It has to load before the `trackPageView()` tag runs.
### Step 2: Create a Custom HTML tag
1. Go to **Tags → New**.
2. Set **Tag Type** to **Custom HTML**.
3. Paste this script:
```html theme={null}
```
The `if` check makes sure the call only runs once the pixel is ready.
### Step 3: Set the trigger
**Don't use an "All Pages" trigger.** That fires on full page loads too and creates duplicate page views.
Pick the trigger that matches how your site changes pages:
| How your site changes pages | Trigger to use |
| :- | :- |
| History API / `pushState` (most SPAs) | **History Change** |
| A custom data layer event | **Custom Event**, matching your event name (for example, `page_view`, `route_change`, or `Loaded a Page`) |
| Hash-based URLs (`#/page`) | **History Change** (it also catches hash changes) |
To set up a History Change trigger:
1. Go to **Triggers → New**.
2. Set **Trigger Type** to **History Change**.
3. Give it a name, for example `History Change - Virtual Page View`.
4. Attach it to your `trackPageView()` tag.
On some SPAs, History Change fires more than once per page change. If you see duplicate page views, open Preview mode and count the History events for one page change. If there's more than one, limit the trigger to one `gtm.historyChangeSource` value (for example, `pushState` only), or use a custom data layer event instead.
### Step 4: Test and publish
In Preview mode, confirm that:
* The Northbeam Pixel tag fires on **all pages**
* The `trackPageView()` tag fires **only** when the page changes without a reload
* No extra page views appear on full page loads
Then **Submit** and publish your container. Unpublished changes don't track anything.
***
## Option B: In your site's code
Call `trackPageView()` from your app's router each time the page changes. Make sure that:
* It runs on every page change that doesn't reload
* It does **not** run on full page loads
* The pixel has loaded before it runs
### React Router example
Call `trackPageView()` whenever the location changes, using [`useLocation`](https://reactrouter.com/en/main/hooks/use-location):
```javascript theme={null}
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';
function NorthbeamPageTracker() {
const location = useLocation();
useEffect(() => {
if (window.Northbeam && typeof window.Northbeam.trackPageView === 'function') {
window.Northbeam.trackPageView();
}
}, [location]);
return null;
}
```
Place this component inside your router. Other frameworks work the same way: call `window.Northbeam.trackPageView()` from the router's navigation hook.
### Shopify Hydrogen
Hydrogen has its own routing and analytics, and the right setup depends on your Hydrogen version. Work with your developer to call `window.Northbeam.trackPageView()` from your router's navigation hook. The same rules apply: only on page changes without a reload, and only after the pixel has loaded.
***
## Troubleshooting
| Problem | Likely cause | Fix |
| :- | :- | :- |
| Page views don't increase after clicking around | `trackPageView()` isn't firing on page changes | Check that your History Change trigger or router hook fires when the URL changes |
| Duplicate page views on first load | `trackPageView()` also fires on full page loads | Use a History Change or custom event trigger, not All Pages |
| Duplicate page views when changing pages (Google Tag Manager) | History Change fires more than once per page change | In Preview mode, count the History events. Limit the trigger to `pushState`, or use a custom data layer event |
| `trackPageView is not a function` in the console | The pixel hadn't loaded when `trackPageView()` ran | Add the `if (window.Northbeam && ...)` check, and make sure the pixel loads first |
| Tag fires but no data shows in Northbeam | The pixel tag isn't published, or it's blocked | Confirm the pixel tag is live and not blocked by your Content Security Policy. Look for `nb-collector` requests in the Network tab |
## Related
* [Northbeam Pixel](/docs/add-pixel): what the pixel does, how to install it, and how to test it
* [Troubleshooting Pixel Tracking](/docs/guide-to-troubleshooting-pixel-tracking)
# Paid Search Team
Source: https://docs.northbeam.io/docs/paid-search-team
Below is a walkthrough video to show Paid Search Best Practices for our customers.
# Walkthrough Video
Recommended Dashboard Settings:
* **Attribution Model**: Clicks-Only (Search campaigns won’t get View credit)
* **Attribution Window**: 1 Day
* **Accounting Mode**: Accrual Accounting
* **Granularity**: Daily
* **Time Period**: Month to Date
* **Time Comparison**: Previous period
* **Filter by**: Which platform you want to look at
* **Breakdown** by: Platform & Category
### TL;DR
**Here are key metrics to use**:
* Spend
* New Customer % (unique to Northbeam)
* ROAS (1-Day Window)
* Auction and softer funnel metrics (secondary but helpful)
**Compare platform vs. Northbeam data**:
* Do not compare branded vs. non-branded performance OR different channels side-by-side without context
* Instead, evaluate each tactic independently.
* Expect differences between Google-reported ROAS and Northbeam's ROAS due to:
* Cash snapshot vs. Accrual performance differences
* First-Time Customer focus
* Adjustment for Multi-Touch and Cross-Channel impact
**When to make decisions**:
* Between Day 14 and Day 60, use Northbeam to find where in-platform data and Northbeam data are different.
* Lean into campaigns where Northbeam shows stronger performance, even if platform data suggests otherwise.
* Always apply your normal scaling and optimization rules, but trust Northbeam's view when directional differences show up.
In your first few weeks, your goal is to find pockets where Northbeam disagrees with the ad platform and trust those differences when making optimizations so you can start really seeing a difference.
Please reach out to your Media Strategist, Customer Success Manager, or contact [Support](https://www.northbeam.io/submit-a-support-ticket) if you have any questions.
# Paid Social Team
Source: https://docs.northbeam.io/docs/paid-social-team
Below is a walkthrough video to show Paid Social Best Practices for our customers. The goal of this video — and this guide — is to help you make smarter optimization decisions using Northbeam's data, especially when it's different from in-platform reporting.
# Walkthrough Video
Recommended Dashboard Settings:
* **Attribution Model**: Clicks-Only or Clicks + Modeled Views
* **Attribution Window**: 1 Day
* **Accounting Mode**: Accrual Accounting
* **Granularity**: Daily
* **Time Period**: 7 Days
* **Time Comparison**: Previous period
### TL;DR
**Here are key metrics to use**:
* Spend
* New Customer % (unique to Northbeam)
* ROAS (1-Day Window)
* Auction and softer funnel metrics (secondary but helpful)
**When to make decisions:**
* Avoid making decisions too early
* **Rule of thumb**: Wait until a campaign has 5-10x your Average Order Value (AOV) in Spend
* Example: If AOV is $80, wait for $400-800 in Spend
* After reaching this threshold, you will know that Northbeam data is accurate so you can start making optimization calls.
**When to scale or bail**:
* Follow your normal scaling rules, but base your decisions on Northbeam's directional insights, especially in the first 30 to 60 days.
* Remember to look at how your performance is pacing and to look at a longer period of time, so you know when to scale (add money) or when to bail (turn off a campaign).
**Watch out for Click-Through-Rate (CTR) Decay**:
* If your CTR is dropping over time (Eg., from 0.8% to 0.4%), head over to[ Creative Analytics](/docs/creative-analytics) to diagnose and improve on creative performance.
You can refer to our [Breakdown FAQ](/docs/manage-breakdowns) to label your campaigns. Labeling is a great way to give your ads a naming taxonomy so you can aggregate based on specific parameters.
As always, remember that Northbeam's numbers will look different. This can also be managed by leveraging your [Profitability Benchmarks](/docs/profitability-benchmarks) once you have a minimum of 90 days with Northbeam data.
Please reach out to your Media Strategist, Customer Success Manager, or contact [Support](https://www.northbeam.io/submit-a-support-ticket) if you have any questions.
# Product Analytics
Source: https://docs.northbeam.io/docs/product-analytics
Data-driven e-commerce merchandising and more.
## What is Product Analytics?
Product Analytics is a Northbeam dashboard that shows you how well your ads are working in relation to the products they sell. This is data-driven merchandising for e-commerce businesses.
By measuring your ads, products, campaigns, and platforms against each other on relative **“indexes” of CAC and ROAS**, you can easily identify your best and worst performing ads, and which products those ads are driving sales towards.
This is useful for businesses that have high numbers of SKUs, do complex bundling schemes, or have bigger strategies for driving repurchases or upsells to existing customers via ad campaigns.
The cornerstone of the Product Analytics Dashboard is the **scatterplot**, which visualizes your assets and products against each other on a relative scale and groups them into four quadrants. The dashboard also has a table function that allows you to refocus the scatterplot into specific products, platforms, campaigns, or individual ads.
**This approach to visualizing product performance can feel unfamiliar at first.** However, this guide will empower you to become a Product Analytics guru, giving you a new tool in your arsenal for driving marketing profitability.
## Product Analytics Walkthrough Video
## Where is Product Analytics?
Open [Product Analytics](https://dashboard.northbeam.io/product-analytics), or select **Product Attribution** under **Attribution** in the left-hand sidebar. Product Analytics availability depends on your account.
## How do you read the Product Analytics dashboard?
### Understanding the scatterplot
The most important thing to understand about Product Analytics is the **scatterplot**. It is divided into four colors, which we call “**quadrants**” (defined later in this guide). Each bubble represents one of your products or assets.
Throughout this documentation, we say “products" or "assets” when speaking about the scatterplot.
This is because this chart shows either products, platforms, campaigns, or ads, depending on the filter you’ve chosen in the screenshot below.
Try the Product filter, then hover over a bubble and read the tooltip. The size of the bubble represents the relative ad dollars spent on each product, platform, campaign, or ad, depending on the filter selected.
The scatterplot shows how all your marketing assets or products fall on a relative scale against each other. They are not against a benchmark - this is only your assets against each other in a vacuum. **To do this, we create both a ROAS Index and a CAC Index of your assets and products.**
## Understanding the ROAS Index and CAC Index
The “ROAS Index” is a measure from 1 to 100. **This takes the ROAS of all your products or marketing assets and scores them against each other on a scale of 1 to 100 - the highest ROAS ad placement would get a score of 100, and your lowest ROAS ad would get a score of 1.**
The “CAC Index” is also a measure from 1 to 100, instead of scoring all your assets or products together on a CAC level. **Your worst-performing CAC asset would get a score of 1, and your best-performing asset by CAC would get a CAC Index score of 100.**
By using these indexes, we can effectively put all your assets together on one chart and visualize how well each asset of your marketing strategy is working in relation to all the others.
## Understanding the colors and quadrants
Each color of the scatterplot represents a specific analysis of the marketing assets that fall within that quadrant.
The quadrants are as follows:
* **Yellow - Top Left Quadrant - High ROAS, High CAC:** these represent the assets or products that are in the top 50% of your assets by ROAS performance, but are in the bottom 50% of your assets or products based on CAC performance.
* **Green - Top Right Quadrant - High ROAS, Low CAC:** these represent the assets or products that are in the top 50% of all assets or products for both CAC and ROAS. These are your best performers.
* **Red - Bottom Left Quadrant - Low ROAS, High CAC:** these are your “underperformers.” These are in your bottom 50% of ROAS performance and bottom 50% of CAC performance.
* **Blue - Bottom Right Quadrant - Low ROAS, Low CAC:** These are performing in the top 50% by CAC but in the bottom 50% on a ROAS measure.
Not all red quadrant assets are bad, and not all green quadrant assets are good. What’s important is understanding why assets are in specific quadrants and what that means for your business.
## Understanding the filters and quick analysis buttons
The four filters above will change the data that appears on the chart and in the table.
* **Product:** shows all your product SKUs and the marketing metrics associated with each one.
* **Platform:** shows all your advertising channels (Meta, Applovin, TikTok, etc.)
* **Campaign:** shows all your ad campaigns across platforms.
* **Ad:** shows all individual ads across platforms.
Pro tip: You can also click into the empty space in any quadrant to automatically filter for all the assets or products in that quadrant.
These filters can “stack” as well. Click the check box in the far left of each row that you want to keep in the chart, and it will create a filter you can see at the top of the table.
For example, you could filter specific products and campaigns to only show ads from Google that sell a handful of specific SKUs.
## Quick analyses buttons
These buttons will show you some quick analyses based on the four quadrants seen in the charts. Use these to get you started. They will automatically filter your scatterplot and table, and you can unclick to remove them.
Please note that you may need to snap between the four filters to refresh the chart once you've unclicked a quick analysis button.
## When should you use Product Analytics?
There are two major use cases for using the Product Analytics dashboard. These are best understood by framing them as questions:
#### Are your ads actually selling the products they are trying to sell?
For example: imagine you are a beauty business. You run many ads for your lip gloss, which is your best performing “hero” product. However, when you check this ad in Product Analytics you notice that only 60% of orders that came from this ad contain the product the ad is promoting, and 40% of orders are for products that are not mentioned at all.
This could uncover some opportunities:
* **Are there popular products that you are not running ads for?** These could prove to be successful ad campaigns on their own.
* **Are your hero product ads actually performing better or worse than the rest of the ads in your portfolio?** There could be opportunities to increase or reduce spend and be more efficient.
* **Should the landing page be structured differently to increase revenue per visitor (RPV)?** If you’re noticing a trend in products purchased that were not promoted in the ad, offering that product in an upsell or bundle may increase RPV and unlock more room to scale the ad.
* **Are there opportunities to improve your CAC or ROAS on specific ads that you haven’t been paying attention to?** Overperformers in the yellow and blue quadrants could turn into big moneymakers.
To answer these questions, we can look at the scatterplot on the ad level filter and look at our favorite, most recognizable ads. Where do they land on the chart?
#### Do you have a product that is selling well, but you are not sure which ad campaign is actually driving those sales?
Imagine the beauty business again. Your second top-performing product could be a beauty blender that doesn’t appear in any of your “top” campaigns.
Which ads are people clicking on that are driving these beauty blender sales? There may be opportunities to scale spend. What other products are people buying alongside this overperformer? Bundling could be an option.
To see these analyses, we would pick a specific SKU from the Products tab and check the box on the left of that row. That would allow that product to carry over across the Platform, Campaign, and Ad filters, showing you which marketing assets are most responsible for those sales in both the scatterplot and the table.
You should look at Product Analytics on a monthly basis to identify any changing trends around seasonality, promo periods, or if you need some ideas for new creative strategies to try.
## Taking action on Product Analytics data
The Product Analytics dashboard can reveal complex relationships between your products and your ads. Each business is different, which makes it challenging to say exactly what you “should do” based on the data you see in these charts.
However, here are some overarching recommendations:
1. **Analyze this data while keeping in mind the specific context of your business.**
1. For example, we recommend you have the COGS (costs of goods sold) for each product readily available to view alongside this data. That can add another layer to this analysis, which makes point #2 easier to understand:
2. **No quadrants is inherently good or bad - it depends entirely on context.**
1. Your top-performing ad for new customer acquisition is likely to be in the bottom left red quadrant, for example. This is not a bad thing, per se. That ad is likely shown to a wide net of potential new customers, many of whom will not purchase, resulting in low ROAS and high CAC. You must understand what your ads are "doing" at each stage of the funnel and how that might affect their ROAS or CAC. If you understand this, then you can look at the quadrants and know if an ad “should” be in that quadrant or not.
3. **To understand why an asset or product is in a specific quadrant, and what to do about it, consult our Quickstart Guide (coming soon).**
## Access to Product Analytics
**Product Analytics is free for all Northbeam users who are on Shopify.** We are slow-rolling this feature out to all clients in 2025. If you would like earlier access, let us know by emailing your account manager at Northbeam.
## ✅ Next stop
This Product Analytics feature allows you to dive into how your products are performing, what's driving conversions, and how each insight can inform your marketing strategy across all channels. Let's keep going and learn about Creative Analytics.
# 💸 Profit Benchmarks
Source: https://docs.northbeam.io/docs/profitability-benchmarks
A step-by-step guide to our new benchmarking tool.
## What are Profit Benchmarks?
**Watch this video for the full tour and explanation!**
Profit Benchmarks is a tool within Northbeam that identifies the data-driven performance benchmarks your advertising campaigns must hit in order to achieve profitability.
Through a step-by-step process, Profit Benchmarks takes your profit goals, promotional periods, and omnichannel marketing performance, and then gives you account-wide targets for ROAS, MER, and more.
**Those benchmarks are then linked throughout your Northbeam dashboards via “red, yellow, and green stoplight” visual cues, letting you quickly understand how well your ads are performing against your long-term goals.**
**With Profit Benchmarks, you don’t have to look at every number in your dashboard to understand your performance, just the numbers that are standing out.**
By establishing performance targets for each of your campaigns, you can demystify what constitutes a “good” or “bad” ad campaign in the context of your specific business.
Rather than focusing on external performance benchmarks from your industry or competitors, you are setting performance goals based on your own business context.
The entire tool is designed with one goal in mind: setting goals to make your marketing profit.
**This is the benchmarking approach you've been hoping for.** This is the "secret sauce" used by many of the world's best performance marketers, turned into an easy tool that you can implement in just a few minutes.
**This guide will help you understand how to use the tool, calculate your benchmarks, and interpret those benchmarks against your own business goals. We recommend you read this guide while you are setting up your first benchmarks.**
## Where are Profit Benchmarks?
The Profit Benchmarks tool is located on the left-hand side, on the Northbeam navigation bar.
## How to use Profit Benchmarks
This product is available after 30 days, BUT we recommend you have at least 90 days of data in Northbeam before trying to establish benchmarks.
This ensures statistical significance against your historical performance.
Before you begin setting benchmarks, be sure to collect the following:
* [ ] Post-Onboarding, have at least 30 days of Northbeam data but best results after you have 90 days of data.
* [ ] Reach out to your Media Strategist or contact [Support](https://www.northbeam.io/submit-a-support-ticket) if you have any questions on the timeline for usage.
* [ ] A full understanding of your marketing budget and allocations
* [ ] A calculation of cost of goods sold (COGS) at a product or ad level
* [ ] An understanding of what a "healthy" business day looks like for your ad account
* [ ] Daily-level insight into the historical performance of your ad account and discounting schedule
These insights are helpful for establishing "healthy day" benchmarks across your entire ad account. Once you have this information, you can navigate to the Profit Benchmarks tool and begin the process.
## The Five Steps of Creating Benchmarks: A Walkthrough
There are five steps in the Profit Benchmarks tool. You must complete each step, but you are not required to do them in order.
You can move around each step as you’re working on your benchmark, as you may need to adjust data more than once to get the output you expect. You can click the tabs on the left to move between each step, and once you’ve completed a step it will have a green checkmark beside it.
### The Benchmark Days Card
**In each step of the tool, on the right you will see the "calculations" card.** This shows you some quick "temperature checks" so you can understand what your benchmark data looks like. Be sure to check this as you're adjusting each step. The data in this card should feel normal for your ad account. **This is critical for getting the benchmarks correct.**
### Select baseline days
In this step, you will choose a range of historical data that best represents, in your opinion, the data that you want to “beat” with your benchmark targets.
**It’s best to choose a range of time that feels most “normal” in your ad account.** You will want to choose the longest range of time possible that could reflect what your future marketing strategy could look like.
### Adjust for profitability
Here you will define what you consider to be a “profitable day” based on your average cost per order as determined by your costs of goods sold across your business.
This step is critical because it establishes what profitability looks like for your specific business. The easiest way to do this is by percentages.
### Adjust for promotions and outliers
On this page you will remove days that don't feel consistent with the rest of your ad performance. It's important in creating benchmarks that your benchmarks are representative of the most "normal" days in your ad account.
**In this tab you can choose to remove:**
* **Promotional outliers**: these are days that you maybe were running huge discounts that drove up performance. These would confound your results so it's worth removing if you have them.
* **Revenue outliers:** sometimes you will have days where perhaps your business went "viral" temporarily, or perhaps you were out of stock on something for a day or two which tanked revenue. This option would remove those days if you have them.
* **Order outliers:** same as revenue outliers, this is an opportunity to remove days that have more or less orders than the "normal" baseline day.
* **Remove spend outliers:** sometimes your ad spend is what confounds the data. Perhaps you spiked spend on a day that you went viral, to ride the wave. This option helps you remove that from the data.
* **Exclude a date range:** here you can freeform remove an entire run of dates. If you had something irregular happen in your ad account and you know the specific range of dates that occurred, we recommend you use this function to remove that range from the benchmark calculation. Remember - you need at least 30 days of good data included to run a good benchmark. The more data you have, the better.
### Adjust for Incrementality
In the previous step, you could remove outliers that didn't hit a specific revenue target. In this step, you can remove outliers that you know don't represent profitable days based on some other metric.
In order to create a benchmark of what profitable days look like, we must remove days that are not profitable - by your definition of "profitable."
**For example, if you know that any days with Facebook CACs over \$100 are not profitable in any circumstance, you can remove those days from your benchmark calculation in this step.**
### Adopt benchmark
In this step, Profit Benchmarks will calculate the benchmarks that will give your profitable performance. It will also show you what your results could be if the benchmarks are followed.
Important: you can change the target metrics using the "configure" button visible in the screenshot below, above the large number on the left.
Before implementing your benchmark, you'll want to follow these steps:
* [ ] Configure your metrics to calculate benchmarks for the metrics that matter the most to you. Do this by clicking the "configure" filter image next to the metrics that are visible.
* [ ] Adjust the attribution models for each metric by clicking the dropdown below each large metric number. Pick the model that matters the most to you.
* [ ] Review the analysis of the benchmark provided. It will tell you how often you've hit that benchmark and the profit you've created from it. Does this feel accurate? If not you may need to revisit previous steps to recalculate.
* [ ] Review the daily profitable KPI results, conversion lag, and channel breakdown charts at the bottom. Do these feel familiar? If not, you may need to adjust your benchmark.
**Press the "adopt benchmark" button at the bottom of this screen to apply your benchmark across your entire account.** This will adjust the appearance of the stoplight tooltips throughout all your dashboards.
## Measuring ads against benchmarks
Now that you've implemented your benchmarks, you will be able to see them using the "stoplight" tooltip hovers throughout your Northbeam dashboards. See an example here:
The hovers will always be one of three colors:
* **Green:** based on all the KPIs you selected during your benchmark process, this ad or set of ads is performing above your targets on all KPIs.
* **Yellow:** This ad or set of ads has some KPI that is at risk of not meeting the benchmark targets. This ad must be analyzed further to see what's happening.
* **Red:** this ad or set of ads has a KPI that is clearly below the target threshold for profitability, resulting in this ad or set of ads not being profitable at this moment.
## Benchmarks Best Practices
1. **First time you get a benchmark, open [Metrics Explorer](https://dashboard.northbeam.io/metrics-explorer) and plot historical performance against your new benchmarks.** What metrics or relationships are most impactful on the KPIs that bring good results? This can help you understand which "levers" are most impactful on whether or not you hit your benchmark goals.
2. **On the [Sales page](https://dashboard.northbeam.io/sales), review your channels at the highest level first.** Are any of them red or yellow? Dive deeper to identify the problematic ads that are affecting results. Are these ads actually underperforming or is this an issue in how you calculated benchmarks?
3. **Update your benchmark at least every six months, but ideally every month**. The marketing environment of 2025 and beyond is constantly changing. You should update your benchmarks accordingly. This ensures that you're holding your ads against the most recent, most relevant standard.
## FAQs
**Who can access Profit Benchmarks?**
* All Northbeam service levels have access to Profit Benchmarks as part of their base Northbeam accounts. It is no additional charge to use Profitability Benchmarks.
**Does setting benchmarks apply them to the view of every user in my Northbeam account?**
* Yes. At this time, any updates to Profit Benchmarks are spread across your account.
**How does benchmarking work across multi-region accounts?**
* At this time, you cannot apply single benchmarks across multiple regions. This is likely not a good idea anyway as each region contains idiosyncrasies that would affect benchmark setting.
**In the Adopt Benchmark stage, how does Northbeam calculate the potential lift these benchmarks would create?**
* We calculate ROAS for your selected days and use that to calculate potential revenue across all the days in the date range you selected. So if your date range is six months, and hypothetically half of the days in that range are "out of benchmark" we would calculate the potential ROI if those days had hit the benchmark.
* So for example, the math would look like this, across two example days:
```
For a benchmark ROAS above 3.0:
Day 1: ROAS = 3.5 - This day is included in the revenue calculation.
Day 2: ROAS = 2.7 - Since this day is below ROAS target benchmarks, we would calculate the estimated ROAS and account for that in the total. (spend * ROAS for selected days)
```
Even if you use another benchmark like CAC, we still use ROAS to calculate your potential returns but filter based on your chosen metric.
Please reach out to your Media Strategist, Customer Success Manager, or contact [Support](https://www.northbeam.io/submit-a-support-ticket) if you have any questions.
# Purchase Events
Source: https://docs.northbeam.io/docs/purchase-pixel
Send completed purchases from your website to Northbeam so orders can be attributed.
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](/reference/post_orders)) 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](/docs/shopify-installation#2-set-up-the-northbeam-custom-pixel). 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](/docs/shopify-custom-backend). |
| **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](/docs/third-party-checkouts). |
## 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](/reference/post_orders)), 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](/docs/add-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](#critical-fire-once-per-order).
* Use the **exact order ID** your backend sends to Northbeam. See [Match the order ID exactly](#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](/reference/post_orders)).
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.
```javascript theme={null}
```
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](/reference/post_orders). 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`](#window-northbeam-fireslimpurchaseevent) instead. If you already use `firePurchaseEvent` and it works, you don't need to change it.
```javascript theme={null}
```
`id` is the only required field. It must exactly match the `order_id` in the [Orders API](/reference/post_orders). For other fields, an empty string (`""`) or `0` is fine when a value doesn't apply. Avoid `null`.
**Order fields**
| Field | Type | Description | Example |
| :- | :- | :- | :- |
| `id` | *String* | The order number. Must exactly match the `order_id` in the [Orders API](/reference/post_orders). 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](https://www.iso.org/iso-4217-currency-codes.html) 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 fields**
These 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:
1. One with a payload containing `data: [{e: "ue",…}]`
2. 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](https://support.google.com/tagmanager/answer/6238868?hl=en).
* **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
```javascript theme={null}
```
## Related
* [Custom](/docs/non-shopify-installation): full setup for custom stores
* [Identify Events](/docs/third-party-checkouts): when your checkout can't pass the order ID
* [Purchases or Orders Are Missing](/docs/purchases-or-orders-are-missing): troubleshooting unattributed orders
# Purchases or Orders Are Missing
Source: https://docs.northbeam.io/docs/purchases-or-orders-are-missing
Determine whether an order is missing browser tracking, server data, or both.
Start with one example order. Record its exact order ID, timestamp, checkout domain, and payment flow.
## 1. Find the order
Open [Orders](https://dashboard.northbeam.io/orders) and search for the exact order ID.
| What you find | What it means | Next check |
| :- | :- | :- |
| Order is absent | Northbeam may not have received the server-side order. | Check the commerce connection or Orders API response. |
| Attributed: **No** | Northbeam received the order but could not attribute it to a customer journey. | Check `firePurchaseEvent` and the order ID. |
| Attributed: **Yes** | The order is attributed. | Check dashboard filters and reporting settings. |
## 2. Compare order IDs
`firePurchaseEvent` and the backend order must use the same identifier. Compare the values character for character, including:
* Capitalization
* Prefixes and suffixes
* Spaces and punctuation
* Order number versus UUID or checkout-session ID
## 3. Check for duplicate purchase events
For non-Shopify checkouts, `firePurchaseEvent` must fire only once per order. If it fires more than once for the same order (for example, when the customer refreshes the confirmation page or the script is installed twice), the order may not attribute. See [Fire once per order](/docs/purchase-pixel#critical-fire-once-per-order).
## 4. Check whether pixel tracking is expected
Some orders do not complete through a web checkout and are not expected to have browser pixel data. Examples include recurring subscriptions, draft orders, offline or POS orders, wholesale orders, and some marketplace or app purchases.
## 5. Check the source
* **Shopify or another commerce integration:** Open [Connections](https://dashboard.northbeam.io/settings/connections) and confirm that the correct store is connected without errors.
* **Orders API:** Review the API response and validation errors. Confirm that the request used the intended production or UAT endpoint.
* **firePurchaseEvent:** Review [Pixel and Event Tracking](https://dashboard.northbeam.io/settings/tracking-script-tags) and the [Purchase Events guide](/docs/purchase-pixel).
For detailed pixel-tracking checks, see [Troubleshooting Pixel Tracking](/docs/guide-to-troubleshooting-pixel-tracking).
# Quickstart
Source: https://docs.northbeam.io/docs/quickstart
The setup path, end to end — each step links to its full guide
Setting up Northbeam is five steps. Work them in order — each one links to
the full guide with the exact scripts and settings.
Check platform access, storefront requirements, and who you'll need
from your team before you start.
[Confirm setup requirements →](/docs/confirm-setup-requirements)
Add the Northbeam pixel and event tracking to your storefront.
[Shopify →](/docs/shopify-installation) ·
[Custom →](/docs/non-shopify-installation)
Send your order data to Northbeam so conversions can be attributed.
[Add orders →](/docs/add-orders)
Connect ad spend so cost metrics like ROAS and CPO can be calculated.
[Add spend →](/docs/add-spend)
Connect each ad platform and add Northbeam UTMs to your ads.
[Integrations and UTMs →](/docs/integrations-and-utms)
## Verify it's working
Once the steps above are done, confirm data is flowing:
Confirm Northbeam UTMs are captured on your landing pages.
Confirm each ad platform is connected and syncing.
## What to expect
Implementation isn't instant — parts of it wait on data syncs and platform
approvals. [What to expect during implementation →](/docs/what-to-expect-during-implementation)
# Sales
Source: https://docs.northbeam.io/docs/sales
Your hub for day-to-day decisions
## What is the Sales page for?
Open the [Sales page](https://dashboard.northbeam.io/sales).
This Sales page is the most utilized page on Northbeam.
Here, you have a complete picture of how your marketing is performing across all channels and you can do your daily campaign optimization.
As you scroll, you will see a chart that shows each of your channels as well as the key metrics associated with each one. This is an overview of each platform that you can sort on the Campaign level, Adset level, and even Ad level. This view is similar to the UI that you typically see inside your ad manager platforms:
* Spend
* Revenue (1st Time)
* ROAS (1st Time)
* New Customers
* CAC (1st Time)
You can customize your table with any metrics that you have utilized in the past, or metrics that you are familiar with. Once you have added your new metric, your chart will update retroactively.
You can learn more about these metrics and other metrics [here](/docs/northbeam-metrics-101).
## Sales Page Walkthrough Video
## ✅ Wrapping up
This All Sales page is essential for understanding your marketing efforts. Now that you have a handle on revenue performance, let's move on to Product Analytics.
# Sales Page Export
Source: https://docs.northbeam.io/docs/sales-page-export
Export the performance data shown on the Sales page as a CSV download or straight into your own Google Cloud Storage bucket, once or on a schedule.
The Sales page export returns the performance data you are already looking at — the chart or the table — as a file. It requires no API key and no engineering work, which makes it the right choice for most one-off analysis and recurring reports.
For row-level touchpoint data, use the [Touchpoints Export](/docs/touchpoints-export) instead. To build a pipeline, use the [Data Export API](/docs/northbeam-api-data-export-1).
## One-time or scheduled
* **One-time:** select your metrics, click **Export Now**, then open [Documents](https://dashboard.northbeam.io/customers/documents) to download the file.
* **Scheduled:** click **Schedule Report** and choose daily, weekly, or monthly. You will receive an email with a link to each completed file.
***
## Export a CSV
1. Open the [Sales page](https://dashboard.northbeam.io/sales).
2. Click **Export**.
3. Select **Chart Values** or **Table Values**:
* **Chart Values** exports the data behind the line chart.
* **Table Values** exports the data in the table.
4. If you selected **Table Values**, click **CSV Export**.
5. Use the **Report Builder** to configure the report.
6. Click **Export Now** for a single file, or **Schedule Report** for a recurring export.
## Table export options
These options appear in the Report Builder when you export **Table Values**.
| Option | What it does |
| :- | :- |
| **Export data broken down by label** | Groups data by the selected labels without breaking it out by date. |
| **Export data broken out by date** | Breaks data out using the selected granularity. Daily is the default; weekly periods run Sunday through Saturday. |
| **Remove \$0 / 0 transaction items** | Removes rows valued at \$0 or with zero transactions. |
| **Export aggregated data only** | Consolidates the selected level instead of returning its individual rows. With Campaign level selected, all campaigns are combined. |
| **Include IDs** | Adds Campaign, Ad Set, or Ad ID columns, depending on the level selected. |
| **Include Kind and Platform** | Adds Northbeam-specific columns describing the traffic source. |
***
## Export to Google Cloud Storage
Use this when you want the Sales table export delivered directly to your own GCS bucket rather than downloaded.
1. Open the [Sales page](https://dashboard.northbeam.io/sales).
2. Click **Export**.
3. Select **Table Values**.
4. Click **Google Cloud Storage**.
5. Grant **Storage Object Admin** access to `nb-data-export@north-beam-io.iam.gserviceaccount.com` in your bucket's IAM settings.
6. Under **Add Your Bucket**, enter your bucket name.
7. Click **Validate** to confirm Northbeam can reach the bucket.
Chart Values cannot be sent to GCS — this option is available for **Table Values** only.
# Set up a Meta Custom Attribution Campaign
Source: https://docs.northbeam.io/docs/setting-up-a-meta-custom-attribution-campaign
Get started with Meta's Custom Attribution using Northbeam Apex.
Once Meta's readiness indicator shows **High** (approximately 10 days after setup), you can run a Custom Attribution campaign. This is the Meta-side optimization layer — the step that actually puts Apex data to work in your ad delivery.
### Custom Attribution is currently in beta.
Reach out to your Customer Success Manager or [Support Team](https://www.northbeam.io/submit-a-support-ticket) if you're not sure whether you're on the list or want to be added ahead of the broader rollout planned for **August 2026**.
If your Apex connection is set up, your data is already flowing and training Meta's model — you'll be ready to launch as soon as access opens up.
### What you'll see in Events Manager
After Apex setup completes, a new Custom Attribution signal will appear under your Purchase event in Events Manager within 48 hours.
A few things to know about it:
* **Isolated signal** - The Custom Attribution signal is fully isolated from your standard Purchase event. Behind the scenes it is not even a Purchase event — it's an AppendAttribution event. You do not need to worry about deduplication with Elevar, your existing CAPI, or any other standard Meta events.
* **No EMQ impact** - This event does not affect Event Match Quality. EMQ is built for a different use case.
* **Data quality issues** will be surfaced in both Events Manager and Ads Manager. If they arise, Northbeam will work with Meta to resolve them.
* **Export data.** Events Manager has an export function that lets you download the raw signal Northbeam is sending at the ad-set level. Note: this may differ slightly from your Northbeam dashboard due to data delays.
### Eligibility requirements
To use Custom Attribution in Ads Manager, your account must:
* Be running Sales-objective campaigns optimizing for Purchase events
* Use **Highest volume** or **Highest value** bid strategy (autobid only)
* Have at least **\~50 Northbeam-attributed orders per day** at the account level, based on your selected **North Star settings**, for best results. The technical minimum is 10 events in 7 days, but model performance improves significantly at higher volume.
* For example, if your North Star is set to 1-day Clicks-Only, Blended Revenue, Accrual accounting, the account should have roughly 50 orders per day under that same Northbeam view.
* Have website or website + app as the conversion destination
**Not compatible with:** Value Rules, non-autobid bid strategies.
### Campaign setup
In Ads Manager, create a new (or duplicate an existing) Sales-objective campaign. At the ad-set level, you'll configure:
1. **Conversion location** — Website (or Website + App)
2. **Performance goal** — Maximize number of conversions or Maximize ROAS
3. **Dataset** — select the pixel configured for Apex (it will show a green indicator when ready)
4. **Conversion event** — Purchase
5. **Attribution model** — select **Custom**
6. **Custom attribution source** — select the Custom Attribution Source (CAS) you would like to use for the ad set. **Your CAS MUST match the pixel you are using for the ad set.**
Custom Attribution is configured at the **ad-set level** — the same level as Incremental Attribution. The two are mutually exclusive on the same ad set, though both can exist within the same campaign.
**Change one variable at a time.** The only thing you're changing in this test is the attribution model. Keep everything else identical to your BAU setup:
* **Performance goal** — use whatever you normally run. Don't switch goals alongside Apex or the test won't be clean. Note: even if your primary KPI is ROAS, Maximize Conversions sometimes drives better ROAS in practice — stick with what you use today.
* **Audience targeting** — keep your existing inclusion, exclusion, and lookalike audiences. Setting "new customers" as your North Star in Northbeam does not automatically make Meta target new customers — you still need the appropriate exclusion audiences in the campaign itself.
### Reporting
The Results column in Ads Manager for Custom Attribution campaigns reflects Northbeam-provided credit and value at the ad ID level — not Meta's standard attribution.
* **Use Northbeam as your source of truth.** Custom, Standard, and Incremental attribution in Ads Manager each use a completely different counting mechanism — comparing them there is apples-to-oranges. In Northbeam, they're all apples — always compare there.
* **48-hour reporting lag.** Custom Attribution conversions appear in Northbeam immediately but show as `–` in Ads Manager for the first 48 hours. Use **Compare Attribution Settings** to view Meta standard attribution alongside Custom during that window.
* **Don't compare against your account average.** The channel average mixes campaigns at different stages, budgets, and optimization histories — it's a noisy baseline that will make results look worse than they are.
## Running the A/B test
### Set up the experiment before launching campaigns
Create the A/B test in Experiments **before** launching the BAU or Apex campaigns. Adding live campaigns later can create audience overlap and weaken the test.
Use Meta's **Experiments** tool to compare your Custom Attribution campaign against your BAU campaign.
### A/B test setup
* In **Experiments**, click **Create an A/B test**.
* Select the campaigns you want to compare:
* **Campaign A:** Select your Custom Attribution campaign. This is the test campaign.
* **Campaign B:** Select your BAU campaign. This is the control campaign.
* For more complex tests, such as a 3-cell test, add additional campaigns as needed.
* Set the test dates:
* **Start date:** One day before the campaign starts.
* **End date:** One day after the campaign ends.
* Turn off **End test early if a winner is found** so the test runs for the full scheduled period.
* Give the test a clear name, such as `Custom Attribution vs BAU - Q3 2026`.
* Select **Cost per purchase** as the key metric for determining the winner.
* Add other business-specific KPIs if needed.
* Click **Review test details** and confirm the campaigns, dates, and metrics are correct.
* Click **Create a test** to start the experiment.
* Use your own source of truth to determine the final campaign winner.
### In-Flight Best Practices
* Avoid changing creative, audiences, or budgets during the test. If a change is required, make the same change in both cells.
* Check for issues, such as duplicate events, that could affect results.
* Avoid similar ads outside the test that target the same audience.
* Keep each campaign in only one test cell.
* Aim for at least **\$5K in spend per cell** and a **10K+ holdout** for more reliable results.
### After a successful test: scaling
* **Recommended:** Run a 50/50 account-level A/B test to scale with confidence.
* **Minimum:** Move at least **20% of budget to Custom Attribution for at least two weeks** before drawing conclusions.
### Avoid running Custom Attribution at a very small budget share (1–3%).
The model learns from the traffic it generates — at low budget it doesn't get enough signal to improve, results will be misleading, and you'll underrealize the gains even if the A/B test already showed it wins.
***
Please reach out to your Customer Success Manager, Media Strategist, or [Support](https://www.northbeam.io/submit-a-support-ticket) if you have any questions.
# Enable Apex for Meta
Source: https://docs.northbeam.io/docs/setting-up-apex
Prepare your Meta account for Custom Attribution.
### Note: Enabling Apex is step 1 of a 2-step process.
Northbeam handles the setup (Custom Attribution Source, CAPI dataset, passback pixel) automatically on your behalf.
Once your Custom Attribution Source is ready, step 2 is [setting up a new campaign](/docs/setting-up-a-meta-custom-attribution-campaign) in Meta Ads Manager to begin optimizing your ads with Northbeam data.
***
## How to enable Apex for Meta
## Before you start
Before setting up Apex for Meta, make sure you have the following ready:
* **Northbeam Access** — any user on the account can enable Apex, so you don't need to be the account owner.
* **Meta Business Manager admin permissions** — the Meta Ads connection in Northbeam must have been made with a login that has `business_management` permission for every business whose pixels you want to use. Agency-managed accounts typically only have `ads_management` and will need the brand to reconnect with the correct login.
* **An active Meta pixel** — at least one pixel must have been receiving Purchase events in the last 28 days. This is Meta's eligibility check and cannot be bypassed.
* **Your North Star metric** — have a decision made (or be ready to decide) on your revenue type, attribution model, attribution window, and accounting mode before starting setup.
## Step 1 — Configure your North Star and enable Meta consent
In [**Settings → Apex**](https://dashboard.northbeam.io/settings/apex):
**Define your North Star metric** — attribution model, attribution window, and accounting mode are the three settings that directly drive Meta's auction.
**Your North Star tells Meta what to optimize toward based on Northbeam's attribution data**, not Meta's. For example, if you set it to 1st time revenue, Meta trains against Northbeam's revenue from new customers — not Meta's own definition of a new customer.
Any user on your Northbeam account can complete this step — it does not require the account owner.
Note: **Meta's Custom Attribution does not currently support C+DV**.
To run a Custom Attribution test today, set your North Star to Clicks-only. If you switch from C+DV to Clicks-only, wait at least 10 days after the change before starting the test, and evaluate results under the Clicks-only model.
Recommended: \*\*Use Accrual as your accounting mode. \*\*
We've consistently seen better performance with Accrual as the North Star. The reason: Meta has no native visibility into accrual-based revenue, which means you're giving its algorithm two genuinely new signals at once — MTA attribution and accrual revenue. This setting is independent of how you report internally, so you can keep making decisions on Cash while Apex trains on Accrual — and better accrual performance drives cash.
## Step 2 — Connect, Configure, and Validate
Toggling on consent launches a three-step in-app wizard. You can return to it from the Apex page if you don't finish in one session.
The user completing this step must have **Meta Business Manager admin** permissions.
Agency-managed accounts typically only have ads management permission and will need a brand-side user to complete this step.
### 1. Connect your Ad Account(s)
Northbeam lists every Meta ad account connected to your dashboard and flags whether the active connection has `business_management` permission for the owning business. Accounts with the correct permission are ready to proceed; accounts without it show a reconnect prompt.
### 2. Configure Pixel(s)
For each account with the right permission, Northbeam displays the pixels available in that business. Pixels currently in use by active ad sets are pre-selected. Choose which pixels to enable for Apex.
### 3. Validate Events
Northbeam runs the per-pixel setup with Meta and surfaces any errors inline. The most common issue: a pixel with no Purchase events in the last 28 days will fail Meta's eligibility check. You can de-select failing pixels and proceed with the ones that pass.
### Validation failing with "Configuration failed."?
Your North Star hasn't been saved. On the Apex page, the **North Star Metric** dropdowns will show empty **"Select.."** placeholders when nothing is configured — make your selections and click **Save**, then re-run validation.
## Step 3 — Verify
After setup, verify your Enhanced Apex configuration using the following three checks:
### 1. Northbeam UI verification
You'll see a badge in [Apex](https://dashboard.northbeam.io/settings/apex) and [Connections](https://dashboard.northbeam.io/settings/connections) confirming how many pixels are configured.
*Note: *Some early Enhanced Apex customers are on our legacy setup flow and may see the legacy **Enhanced Apex badge**. If this applies to you, your Apex setup is still** working as expected\*\*.
### 2. Meta connection verification
Within **48 hours**, a new Custom Attribution experience will appear in Meta Events Manager on your dataset.
You'll see a test event called **NorthbeamApexConnectionTest** (or **NorthbeamTestEvent**) in Events Manager — this is expected and confirms the connection. No action required.
### 3. Meta readiness verification
A readiness indicator on the Custom Attribution quality page will climb toward **High** over approximately **10 days**. The campaign creation option in Ads Manager is grayed out until this training period completes. During that time, you can prepare your test campaign, but you cannot launch it yet.
In Events Manager, your Custom attribution source carries a status badge that reflects where Meta is in the training process. It moves through two states:
* `In training` — Meta is still warming up the model on your Apex data. This is the expected state for approximately the first **10 days** after setup. The campaign creation option in Ads Manager is grayed out during this period — you can prepare your test campaign, but you cannot launch it yet.
* `Ready to use` — training is complete and Custom Attribution is selectable in Ads Manager.
***
Please reach out to your Customer Success Manager, Media Strategist, or [Support](https://www.northbeam.io/submit-a-support-ticket) if you have any questions.
# Custom Goals
Source: https://docs.northbeam.io/docs/setting-up-custom-goals
Track other actions on your site, like sign-ups, add-to-carts, or form submissions.
Custom Goals let you track actions that happen on your website, beyond page views and purchases. For example:
* Email or SMS sign-ups
* Add-to-carts
* Checkout starts
* Quiz or lead form submissions
Each goal shows up as a metric on your Sales page. Custom goals count how many times an action happens. They don't record revenue or other values.
## Which setup you need
Custom Goals work the same way on Shopify and custom stores. You add a short script wherever the action happens, then register the goal in your dashboard.
**Custom goals must happen in the browser.** The script has to run on your website, on the same domain as the Northbeam Pixel, while the visitor is on the page.
| Works | Doesn't work |
| :- | :- |
| Button clicks | Backend or webhook events |
| Form and quiz submissions | Server-side API calls |
| Add-to-carts and checkout starts | Offline or CRM-triggered events |
***
## Set up a custom goal
The [Northbeam Pixel](/docs/add-pixel) must be running on the page where the action happens, and it must load first. Custom goals won't track without it.
Add this script so it runs **when the action happens**, for example after a form submits successfully or after an add-to-cart click:
```javascript theme={null}
```
Replace `your_goal_id` with your own Goal ID. You can add the script through Google Tag Manager (easiest for most stores) or directly in your site's code.
Go to [Settings → Custom Goals](https://dashboard.northbeam.io/settings/custom-goals) and click **Add Custom Goal**. Fill in:
* **Goal ID:** the exact Goal ID from your script. If it doesn't match exactly, the goal won't show up.
* **Display Name:** the metric name you'll see in your dashboard (for example, `SMS Sign Up`).
Then click **Add**. New or changed goals take effect after the next data processing run.
After the goal fires at least once, it's available as a metric. On the [Sales page](https://dashboard.northbeam.io/sales), click **Customize Table**.
Click **Custom goals**, select your goal's metrics, then click **Apply**.
## Goal ID rules
* Use **lowercase letters, numbers, and underscores** only. Hyphens or spaces stop the goal from showing up in your dashboard.
* The Goal ID in your script and in your dashboard must **match exactly**.
Good examples: `sms_signup`, `email_signup`, `add_to_cart`, `quiz_submit`, `initiate_checkout`.
## Troubleshooting
If a goal isn't showing up, check that:
* The Northbeam Pixel is running on the page where the action happens
* The Goal ID in your dashboard matches the script exactly
* The script runs when the action happens, not on page load or on the wrong trigger
* The action happens on the same domain as the Northbeam Pixel
* At least one processing run has finished since you added the goal
# SFTP Orders Upload
Source: https://docs.northbeam.io/docs/sftp-orders-upload
This document is for new or current Northbeam customers who wish to send Orders to Northbeam without using our Orders API or native Shopify connector. Common use cases include historical order backfills and recurring order uploads from systems without API integration resources.
Under the hood, this service takes your CSV file, validates it, splits it into batches, and uploads it through our standard Orders API.
***
## Step 1. Request Access
[Submit a support ticket](https://www.northbeam.io/submit-a-support-ticket) to request SFTP access. Northbeam will assign you a User and Password.
**Host:** sftp.robot.northbeam.io
**User:** XXX\_orders
**Password:** XXX
**Port:** 22
Using your preferred SFTP client, connect to your Northbeam SFTP instance with the details provided.
***
## Step 2. Format Your CSV
Each file must follow this template exactly or the upload will fail:
📄 [SFTP Orders Upload Template](https://docs.google.com/spreadsheets/d/193PYzhk2DamT6DTdiZMrY8U3nWJ03LLlTh9cPE_XASI/edit?usp=sharing)
### Formatting Rules
These rules are strict — most failed uploads are caused by one of the following:
1. **Required columns must be present in your file.** Optional columns may be omitted entirely if you have no data for them.
2. **Field names are case-sensitive** and must match the template exactly.
3. **Product fields are pluralized**: `products_id`, `products_name`, `products_quantity`, `products_price`. Singular field names (`product_id`, `product_name`, etc.) will fail validation.
4. `tax`** and **`shipping_cost`** cannot be empty.** Pass `0` if there is no value to report.
5. `time_of_purchase`** must use the ISO-8601 standard** (e.g. `2026-03-08T09:23:45.000Z`).
6. **Orders with multiple products use one row per product**, repeating the same order-level values (order\_id, totals, etc.) on each row. Our system consolidates rows with the same `order_id` into a single order.
### Field Reference
| Field | Required | Notes |
| - | - | - |
| `order_id` | Yes | Unique ID per order. Must not be the customer ID. Must match the ID sent via `firePurchaseEvent` if a live Pixel is running. |
| `customer_id` | Yes | Unique ID per customer, reused for returning customers. Must not be the order ID or an email. |
| `time_of_purchase` | Yes | When the customer placed the order, in ISO-8601 (`2026-03-08T09:23:45.000Z`). |
| `order_tags` | No | Comma-separated, no spaces between tags. Used for subscriptions, customer stage, and exclusions. |
| `discount_codes` | No | Comma-separated, no spaces between codes. |
| `currency` | Yes | 3-digit ISO-4217 code (e.g. `USD`). All monetary fields are assumed to be in this currency. |
| `tax` | Yes | Cannot be empty — use `0` if no tax. |
| `purchase_total` | Yes | Total collected from the customer, including taxes, shipping, and fees. |
| `shipping_cost` | Yes | Cannot be empty — use `0` if no shipping. |
| `customer_email` | No | Email associated with the customer. |
| `customer_phone_number` | No | Phone number associated with the customer. |
| `hashed_customer_email` | No | Hashed email associated with the customer. See [Hashing Customer Data](/docs/hashing-customer-data) for format requirements. |
| `hashed_customer_phone_number` | No | Hashed phone number associated with the customer. See [Hashing Customer Data](/docs/hashing-customer-data) for format requirements. |
| `discount_amount` | No | Amount discounted via discount codes. |
| `products_id` | Yes | Unique product identifier. Must not be the order\_id. |
| `products_name` | Yes | Product name. |
| `products_quantity` | Yes | Quantity of this product in the order. |
| `products_price` | Yes | Product price in the order's currency. |
| `customer_shipping_address_address1` | No | Street address. |
| `customer_shipping_address_address2` | No | Additional street address field. |
| `customer_shipping_address_city` | No | City or locality. |
| `customer_shipping_address_state` | No | State or region. |
| `customer_shipping_address_zip_code` | No | Postal code. |
| `customer_shipping_address_country_code` | No | ISO-3166 country code. |
| `refunds_product_id` | No | Product identifier for the refunded product (must also appear in the products fields). |
| `refunds_quantity` | No | Number of units refunded. |
| `refunds_amount` | No | Total amount refunded to the customer. |
| `refunds_refund_cost` | No | Estimated total cost of the refund, including overhead (shipping, fees). |
| `refunds_refund_made_at` | No | When the refund was fulfilled, in ISO-8601. |
***
## Step 3. Upload Your File
Place your .CSV file in your SFTP directory. Processing begins automatically — no additional ingestion step is required on your end.
**Limits:**
* Each file must not exceed **200 MB** (approximately 1 million records, depending on your data).
* For larger datasets, split your data into multiple files.
***
## Step 4. Confirm Success or Troubleshoot Errors
Once you upload a file, our automation will process it within a few moments and move it to one of two folders:
**Validation is all-or-nothing.**
If any row in your file fails validation, the entire file is rejected and moved to `/invalid_files`. Fix all errors in the error report before re-uploading.
* `/processed_files` — the file was processed successfully and orders will be available after the next data processing cycle.
* `/invalid_files` — the file contained validation errors. An error report (`_errors.txt`) will be created alongside it with row-level details for debugging.
If your file lands in `/invalid_files`, review the error report, fix the issues, and re-upload the corrected file.
Example error report:
```
Validation Error Report
File: orders_uploads/925160f8-ecc3-4457-8c3e-b75fe5dbf0ac/broken_file_sample.csv
Client ID: 925160f8-ecc3-4457-8c3e-b75fe5dbf0ac
Timestamp: 2026-01-30T18:10:18.917640Z
Total Invalid Orders: 3
================================================================================
Row 1:
Order ID: O12345
Customer ID:
Validation Errors:
- Field: customer_id
Type: string_too_short
Message: String should have at least 1 character
Row 3:
Order ID: O726883481
Customer ID: 815186642
Validation Errors:
- Field: time_of_purchase
Type: value_error
Message: Value error, Invalid ISO TS
Row 4:
Order ID: O7292339997
Customer ID: 812197138
Validation Errors:
- Field: currency
Type: string_too_short
Message: String should have at least 3 characters
```
### Common Errors and Fixes
| Error | Cause | Fix |
| - | - | - |
| `tax` / `shipping_cost`: "Input should be a valid number" | Field passed as empty | Set value to `0` instead of leaving blank |
| Errors on optional fields (e.g. `customer_email`, `discount_amount`, shipping address, refund fields) | Column headers missing from file | Optional columns can be omitted entirely — only required columns must be present |
| Product field errors | Singular field names used | Use pluralized names: `products_id`, `products_name`, `products_quantity`, `products_price` |
| "Invalid ISO TS" | Timestamp not in ISO-8601 format | Use `YYYY-MM-DDTHH:MM:SS.000Z` (UTC) or include a timezone offset |
| "String should have at least 3 characters" on `currency` | Missing or invalid currency code | Use a 3-digit ISO-4217 code (e.g. `USD`) |
After fixing errors, simply re-upload the corrected file to the same directory.
# Shopify + Custom
Source: https://docs.northbeam.io/docs/shopify-custom-backend
For stores with a Shopify front end and checkout, but a custom backend that sends orders to Northbeam.
Use this page if your **front end is Shopify** but your **backend is custom**:
* **Front end (Shopify):** your storefront and checkout both run on Shopify.
* **Backend (custom):** your own system, such as an external order management system (OMS), sends orders to Northbeam through the [Orders API](/docs/orders-api). You don't use the [Shopify connector](/docs/shopify-order-sync).
Most Shopify stores don't need this page.
Because your checkout runs on Shopify, you still install tracking with the [Shopify guide](/docs/shopify-installation), not the Custom guide. The only difference is one line in the Custom Pixel.
## Why you'd have this setup
A common reason is keeping one customer ID across every system. For example, you might:
1. Import your Shopify orders into your OMS.
2. Replace the Shopify customer ID with your OMS customer ID.
3. Send all orders to Northbeam through the Orders API, including your Shopify orders.
## Why the pixel needs a change
The Northbeam Custom Pixel sends a purchase event to Northbeam when a customer checks out. Northbeam then matches that event to the real order.
* **With the Shopify connector**, Northbeam matches them using Shopify's **checkout token**. That's what the standard pixel sends.
* **With a custom backend**, Northbeam matches them using the **order ID** you send through the Orders API. The checkout token won't match anything, so the pixel needs to send the Shopify order ID instead.
## Update the Custom Pixel
Set up the Custom Pixel as usual by following [step 2 of the Shopify guide](/docs/shopify-installation#2-set-up-the-northbeam-custom-pixel). Before you click **Save**, change one line in the script.
In the **firePurchaseEvent** script, find the `// Subscription Hook` section. The first line inside `firePurchaseEvent` sets the `id`:
```javascript theme={null}
id: event.data.checkout.token,
```
Replace that line with:
```javascript theme={null}
id: event.data.checkout.order.id,
```
Leave the rest of the script as it is. The section should now look like this:
```javascript {4} theme={null}
// Subscription Hook
analytics.subscribe("checkout_completed", (event) => {
window.Northbeam.firePurchaseEvent({
id: event.data.checkout.order.id,
totalPrice: event.data.checkout.totalPrice.amount,
shippingPrice: event.data.checkout.shippingLine.price.amount || 0,
taxPrice: event.data.checkout.totalTax.amount || 0,
// ...the rest of the script stays the same
});
});
```
Click **Save**, then finish the rest of [the Shopify guide](/docs/shopify-installation#2-set-up-the-northbeam-custom-pixel) as normal.
**The IDs must match exactly.** The `order_id` your backend sends through the Orders API must be the same Shopify order ID the pixel sends. If your OMS sends a different ID (for example, its own order number), Northbeam can't match the purchase to the order, and those orders won't be attributed.
**Already have the Custom Pixel installed?** Go to **Settings → Customer events → Custom pixels**, open **Northbeam Event Tracking**, make the change above, and click **Save**.
# Shopify
Source: https://docs.northbeam.io/docs/shopify-installation
Set up Northbeam tracking on a store that uses Shopify's checkout.
Use this guide if your store uses **Shopify's checkout**. If it doesn't, follow the [Custom](/docs/non-shopify-installation) guide.
**Headless storefront?** Use this guide too. Only [step 1](#1-install-the-northbeam-pixel-and-metadata-script) is different. Pick the **Headless storefront** tab there. Steps 2 to 4 are the same, because checkout still runs on Shopify.
## What you'll set up
| Step | What it tracks | Needed? |
| :- | :- | :- |
| [1. Add the pixel to your storefront](#1-install-the-northbeam-pixel-and-metadata-script) | Visits and page views on your storefront | **Required**. Headless stores: use the Headless tab. |
| [2. Add the Custom Pixel](#2-set-up-the-northbeam-custom-pixel) | Checkout pages and purchases | **Required** |
| [3. Add the post-purchase script](#3-add-post-purchase-tracking-optional) | Post-purchase upsell pages | Only if you use a post-purchase upsell |
| [4. Let Northbeam know](#4-let-northbeam-know) | We finish your setup | **Required** |
## Before you start
Go to [Settings → Northbeam Pixel and Event Tracking](https://dashboard.northbeam.io/settings/tracking-script-tags). Every script in this guide is there, already filled in with your Client ID:
| Script in your dashboard | Where it goes | Step |
| :- | :- | :- |
| **Northbeam Pixel** | `` of your storefront | [1](#1-install-the-northbeam-pixel-and-metadata-script) |
| **Metadata Script** | `` of your storefront, above the pixel | [1](#1-install-the-northbeam-pixel-and-metadata-script) |
| **firePurchaseEvent** | Shopify **Customer events** (as a Custom Pixel) | [2](#2-set-up-the-northbeam-custom-pixel) |
| **Post-purchase upsell page** | Shopify **Settings → Checkout**. Optional. | [3](#3-add-post-purchase-tracking-optional) |
***
## 1. Install the Northbeam Pixel and Metadata Script
These scripts run on every page of your storefront. The **Northbeam Pixel** records visits, where visitors came from, and the pages they view. The **Metadata Script** records your store's region and currency.
Where they go depends on your storefront:
In Shopify, go to **Online Store → Themes**. Click **⋮ → Edit code**.
Open **Layout → theme.liquid** and find the `` section. Paste the **Metadata Script** first, then the **Northbeam Pixel** directly below it.
Click **Save**.
A headless storefront doesn't use `theme.liquid`. Add the scripts to your storefront's own code instead.
Add the **Metadata Script** first, then the **Northbeam Pixel** directly below it, in the `` of every page on your storefront. You can do this in your site's code or through Google Tag Manager. See [Custom, step 1](/docs/non-shopify-installation#1-install-the-northbeam-pixel) for how.
Deploy your storefront, or publish your Google Tag Manager container.
**Is your storefront a single-page app?** Some headless storefronts change pages without a full reload (for example, Hydrogen). If yours does, the pixel only records the first page view. Also set up [Page View Events](/docs/page-view-events) to track the rest.
Not sure? Ask your developer. Many headless storefronts aren't single-page apps and don't need this.
Steps 2 to 4 below are the same for headless stores, because checkout still runs on Shopify.
***
## 2. Set up the Northbeam Custom Pixel
Shopify's checkout doesn't run your theme, so the pixel from step 1 can't see it. The Custom Pixel covers checkout instead. It records the checkout pages customers view and **tracks completed purchases** using Shopify's `checkout_completed` event.
In Shopify, go to **Settings → Customer events**. Open the **Custom pixels** tab and click **Add custom pixel**.
Name the pixel **Northbeam Event Tracking**, then click **Add pixel**.
Set **Permission** to **Data collected does not qualify as data sale**. Paste the **firePurchaseEvent** script from Northbeam into the code editor, then click **Save**.
Click **Connect**, then click **Connect** again to confirm.
Go to **Settings → Customer privacy** and confirm a cookie consent banner is turned on. Without one, customers can't opt in to tracking, and the Custom Pixel may not run.
***
## 3. Add post-purchase tracking (optional)
**Skip this step** unless your store shows a post-purchase upsell page after checkout. This script lets Northbeam attribute those extra purchases.
In Shopify, go to **Settings → Checkout**.
Scroll to **Post-purchase page**. Paste the Northbeam post-purchase script into **Additional scripts**, then click **Save**.
***
## 4. Let Northbeam know
When your scripts are installed, [submit a support ticket](https://www.northbeam.io/submit-a-support-ticket) to tell our team. We'll finish your setup so page views are tracked correctly.
**Don't skip this step.** If we don't hear from you, page view tracking may be incorrect. Page views are the foundation of Northbeam's tracking, so attribution can be incomplete without them.
***
## Test your setup
Check that you have:
* The **Metadata Script** and **Northbeam Pixel** in the `` of your storefront, in that order (in `theme.liquid` for standard themes)
* The **Northbeam Custom Pixel** connected under **Customer events → Custom pixels**
* The **post-purchase script** in your checkout settings (only if you use a post-purchase upsell)
Then [test that the pixel is firing](/docs/add-pixel#how-to-test-for-the-northbeam-pixel).
## Optional tracking
Add these only if they apply to your store.
Track other actions, like sign-ups, add-to-carts, or form submissions.
Only for headless storefronts that are single-page apps (for example, Hydrogen). Most stores don't need this.
## FAQ
After setup, you'll see **two Northbeam entries** under **Settings → Customer events**. This is expected. They're not duplicates, and **you need both**.
| Pixel | Where it appears | How it's added |
| :- | :- | :- |
| **Custom Pixel** | Customer events → **Custom pixels** | You create it in step 2 |
| **App Pixel** | Customer events → **App pixels** | Added automatically when you connect Shopify |
Don't delete either one. You don't need to change any settings on the App Pixel.
Check both tabs under **Settings → Customer events**.
* **Custom Pixel missing:** complete [step 2](#2-set-up-the-northbeam-custom-pixel).
* **App Pixel missing:** connect your store using the [Shopify Order Sync guide](/docs/shopify-order-sync).
For example, an external order management system sends your orders to Northbeam through the [Orders API](/docs/orders-api) instead of the Shopify connector. Follow this guide as normal, but change one line in the Custom Pixel. See [Shopify + Custom](/docs/shopify-custom-backend).
**Standard Shopify themes:** no. Install the scripts directly in Shopify using the steps above.
**Headless storefronts:** you can add the Northbeam Pixel to your storefront through Google Tag Manager (see the Headless tab in step 1). Steps 2 and 3 are always done in Shopify.
# Shopify Migration: Preserving Customer Stages
Source: https://docs.northbeam.io/docs/shopify-migration-preserving-customer-stages
**This guide is for existing Northbeam customers migrating from a custom order management system using Orders API to Shopify.**
It covers one specific task: preserving your historical Customer IDs so Northbeam can continue accurately classifying customers as **New** or **Returning** after migration.
> This guide does not cover full order or customer data migration into Shopify..
***
## Why this matters
Shopify generates its own unique Customer IDs when customer records are imported. Northbeam relies on consistent Customer IDs to determine whether a customer is New or Returning.
Without this step, every existing customer will appear as a **New customer** in Northbeam — because Shopify-generated IDs have never been seen before.
To prevent this, you'll store your historical Customer IDs in a Shopify customer **metafield**, which Northbeam's engineering team will then map to your existing customer records.
***
## Before You Start
Make sure you have:
* Access to your Shopify admin
* A customer export from your previous system with **Customer IDs and email addresses intact**
* Your Northbeam pixel still active on your storefront
**Important:** Do not remove the Northbeam pixel until your Shopify integration is fully verified. Running both systems in parallel during the transition prevents gaps in attribution data.
***
## Step 1: Create a Customer Metafield in Shopify
Do this **before** starting your migration.
1. **Login to your Shopify store** at [shopify.com](https://www.shopify.com) if you haven't already
2. **Click on Settings** — find this in your Shopify homepage on the bottom left corner
3. **Click on Customers**
4. **Click Add definition** If you haven't added one before, this button will be center-stage!
5. **Customer Metafield Details**
1. Name: `legacy_customer_id` — note this name exactly, you'll need it later.
2. Type: **Single line text**
3. Validation: minimum of **1** and max of **256**
6. Click **Save**
The metafield namespace will default to `custom`, making the full field key `customer.metafields.custom.legacy_customer_id`
This is the column header you'll use in your CSV import.
***
## Step 2: Export customer data from your current system
Before disconnecting your old system, export your customer list. At minimum, your export must include:
* **Customer ID** (from your legacy system)
* **Email address**
Store this export securely — you'll use it to populate the import file in Step 3 and to verify your data in Step 4.
***
Do not remove the Northbeam pixel from your website until your Shopify integration is fully verified. Running both in parallel during the transition prevents gaps in attribution data.
***
## Step 3: Format Your Customer List for Shopify
Use the [Northbam Shopify Import Template](https://docs.google.com/spreadsheets/d/1x17iJWc7gx8f13ML5hq15MeCo4D5tqg3Sb4T-9vpKa8/edit?usp=sharing) to format your data
The most common formatting mistake is getting the metafield column name wrong. It must be **exactly**:
`customer.metafields.custom.legacy_customer_id`
***
## Step 4: Import your Customers into Shopify
Proceed to your **Customers** page in Shopify.
1. In the top left corner, click Import:
2. Import your CSV files!
*We recommend following the [following template](https://docs.google.com/spreadsheets/d/1x17iJWc7gx8f13ML5hq15MeCo4D5tqg3Sb4T-9vpKa8/edit?usp=sharing) for guidance -- as the template that Shopify provides does not account for Customer metafields*
***
## Step 5: Notify your CSM at Northbeam
Once your data has been uploaded, inform your CSM at Northbeam along with the name of your **legacy customer\_id** field. Once we have this, the Northbeam engineering Team can map your old Customer IDs into your dashboard, preserving customer stages.
# Shopify
Source: https://docs.northbeam.io/docs/shopify-order-sync
Connect your Shopify orders data to your Northbeam dashboard
Under step 8 in the onboarding flow, select 'Shopify Storefront' as your source of truth for Orders:
**Step 8a** - Connect your Shopify store
If you are not logged in to your Shopify store, you will be redirected to the Shopify App store to [download the Northbeam App](https://apps.shopify.com/north-beam)
You'll be prompted to login to your Shopify store
Select your Shopify store from the menu
Once connected you will be redirected back to the Northbeam onboarding flow where you will see your Shopify store name and you can move forward with the remaining steps in step 8.
# Spend API
Source: https://docs.northbeam.io/docs/spend-api
This page describes the usage of our Spend API
## What is the Spend API?
The Spend API enables our customers to programmatically upload daily spend, clicks, and impressions metrics at the ad level of their choice (Campaign, Adset, Ad) for Ad platform integrations that we do not natively support. A common example is an email marketing platform (e.g. Mailchimp, SendGrid).
## Functionality
The Spend API allows for
* upload of new entries,
* updating of existing entries,
* deletion of existing entries,
* listing of uploaded entries
With this flexibility, our customers can programmatically modify their spend data for platforms we do not yet natively support!
## Spend Attributes
Each spend entry has a set of **required** attributes as well as *optional* attributes that can be submitted for each spend entry. These fields are also documented in the [API Reference](/reference/post_spend), albeit in much more detail here.
### Day by Day Data
Most users will only need day-by-day data for their custom spend. This will spread out the data across the entire day linearly (For example, if you send \$240 for a day, it will be attributed as 10 dollars for every hour of the day).
### Required Attributes
Certain metadata is required for a spend entry to be submitted. Without these fields, an API call will return an error as part of our validation check to make sure the spend entries contained in an API call pass muster. The following attributes are required:
* `date` - The date the spend was committed, in a `YYYY-MM-DD` fashion.
* `platform_name` - This field denotes the platform name the spend object will appear under in the dashboard. This must be supplied as a non-empty string.
* `campaign_id` - While the ad hierarchies of each ad platform are different, each platform has a least one level of ads to enumerate over. Within Northbeam, we consider campaigns to be the highest-level ad object. Use this field to capture the ID of the ad object you are spending on
* `campaign_name` - This field denotes the campaign name the spend object will appear under in the dashboard.
* `spend` - This captures how much was spent on an ad object on a given day. If no spend was made on an ab object, consider not sending an entry for that ad object.
* `spend_currency` - This field captures the currency that was used for the spend, per ISO-4217 standards (a 3 letter denomination)
### Optional Attributes
The following spend attributes are optional:
* `platform_account_id` - Each Ad Platform has an account ID. In the event that a customer has multiple account IDs associated with a particular ad platform, this is useful for segregating which ad platform spend was made on. If only using one account and the account ID is unknown, use a number of your choosing, but please remain consistent in using that number!
* `adset_id` - This field denotes the adset ID for the ad object spend was made (if applicable). If not supplied, the default will be set to `""`(Blank string)
* `adset_name`- This field denotes the adset name the spend object will appear under in the dashboard. If not supplied, the default will be set to"" (Blank string)
* `ad_id` - This field denotes the ad ID for the ad object spend was made (if applicable). If not supplied, the default will be set to `""` (Blank string)
* `ad_name`- This field denotes the ad name the spend object will appear under in the dashboard. If not supplied, the default will be set to"" (Blank string)
* `impressions`- Along with Spend, the Spend API can track additional metrics that can be gathered from the ad platform, such as impressions; these will default to `0` if not specified
* `clicks`- Along with Spend, the Spend API can track additional metrics that can be gathered from the ad platform, such as clicks; these will default to `0` if not specified.
## Notes
One of the motivations for the development of this API was to avoid using Spend sheets. Spend sheets exist at Northbeam to allow Northbeam to capture spend that we do not have native connections for. This can be rather cumbersome when there are either (i) a lot of ad platforms to support via Spend sheets, or (ii) a lot of campaigns (deeper levels) of hierarchy per platform. Consider using the Spend API if developer resources are available and the time spent using the sheets is burdensome and can be leveraged otherwise!
## Further Help
If you have any questions, please submit a [Support](https://www.northbeam.io/submit-a-support-ticket) ticket.
# Best Practices and Limits
Source: https://docs.northbeam.io/docs/spend-api-best-practices-and-limits
This page describes the Best Practices and Limitations of our Spend API
## Best Practices
In a world absent of any logistical constraints, our customers would send us a spend record as soon as it is available in the ad manager. This would enable the most realtime spend data within Northbeam, and would become available for analysis by our customers following their next data pipeline run.
While this is not often feasible, we generally advise you to sync as much spend data as possible with a cadence of at least 2x faster than the number of times a day your pipeline runs per your services agreement.
Note that if you have a data pipeline that runs hourly, and you send spend data once a day, it is likely that on any given present day, you will not be able to make best use of our data in real-time as it pertains to the spend committed on platforms we do not yet natively support (however for metrics on a basis older than the current day, the experience will be unaffected)
## Tying Spend Submitted via the API to Website Events Received via Pixel
The spend submitted via this API has the ability to be tied to the events that Northbeam receives from your website. In order for this to work, the following fields on the API calls have to match the corresponding fields in the ad object tagging:
* `platform_name`
* `campaign_id`
* `adset_id`
* `ad_id`
It is not always the case that all platforms will support the full campaign/adset/ad hierarchy - for those that do not, feel free to leave the appropriate fields empty.
## Limitations
Our current API accepts spend entries in batches of up to 1000 per API call. If your volume of spend records exceeds this batch size, it is best to break up the calls to not exceed this limit. There are no concurrency or daily/hourly limits in place.
## Further Help
If you have any questions, reach out to Customer Success by [submitting a ticket](https://www.northbeam.io/submit-a-support-ticket).
# Subscription Analytics
Source: https://docs.northbeam.io/docs/subscription-analytics
### Subscription Analytics offers powerful insights that will help you optimize campaigns to capture subscribers and increase revenue for faster, sustained growth.
You can now:
* Optimize marketing campaigns for New Subscriptions and see associated efficacy metrics
* Understand your Take Rate, or "% of customers that convert into New Subscriptions"
* Distinguish between your Subscriptions and One-Time Orders
## How do I set up my Subscription Analytics?
Order Tags are the most important part of setup.
Tags allow us to understand which orders are First-Time Subscriptions and Recurring Subscriptions -- which ultimately inform our Subscription metrics.
***
## Step 1: Preparing your Order Tags
**Two order tags are needed:**
1. Order Tag for First-Time Subscription Orders
2. Order Tag for Recurring Subscription Orders
The process in which Order Tags are set up depends on your eCommerce platform.
For Shopify Stores
**Many subscription apps (ex. Recharge) automatically tag your First Time and Recurring Subscriptions.**
How to double check your tags:
* In Shopify: Find a Subscription Order and check the [order tags](https://help.shopify.com/en/manual/shopify-admin/productivity-tools/using-tags) for First Time and Recurring tags.
* In Northbeam: On the [Orders page](https://dashboard.northbeam.io/orders), use the Order Tag filter and check for First Time and Recurring tags (see the video for a walkthrough).
**If order tags are missing, please make sure tags are set up. Many customers use automation apps like[Shopify Flow](https://apps.shopify.com/flow) or [SC Order Tags & Flows](https://apps.shopify.com/ordertagger) to do so**
### For Custom Stores
**Order tags will need to be sent through`order_tags` field using the [Orders API](https://northbeam-orders-api.readme.io/reference/post_orders)**
Once sent, verify them on the [Orders page](https://dashboard.northbeam.io/orders) using the Order Tag filter.
**Please use unified order tags for your First Time and Recurring Subscriptions.**
| Order Tag Method | Pass / Fail |
| :- | :- |
| All First Time Subscriptions tagged with "First Time Subscription" | ✅ |
| All Recurring Subscriptions tagged with "Recurring Subscription" | ✅ |
| Different tags are used: "First Time #1001"; "First Time #1002", "First Time #1003" | ❌ |
| Different tags are used: "First Time"; "First Time Sub"; "First Time Subscription" | ❌ |
***
## Step 2: Assigning the Tags
1. Click **Settings** in the bottom left corner
2. Click **Subscription Order Tags**
3. Please ensure:
1. Your **First Time tag is assigned to the First Time subscription category**
2. Your **Recurring tag is assigned to the Recurring subscription category**
Note: We pre-populate all dashboards with the tag assignments:
* First Time: "Subscription First Order"
* Recurring: "Subscription Recurring"
* Other: "Subscription"
We've found that these are the most common Order Tags created by common Shopify Subscription apps.
***
## Step 3: Set up your Subscription Analytics
You're all set! Find your Subscription Metrics metrics under **Subscriptions** in the Customize Table pop-out.
First Time vs Other vs Recurring
We offer 3 types of every Subscription Metric:
* First Time
* Other
* Recurring
These correspond to the order tags from Step 2.
### Want to calculate your Take Rate?
Take Rate refers to the percentage of customers that convert into new subscriptions. This is a useful metric to understand channels driving incremental growth for your business.
We could create Take Rate using a **Custom Metric**.
1. Open the [Sales page](https://dashboard.northbeam.io/sales).
2. On the right side, click **Custom Metrics**
3. Click **Create New Metric**
4. Enter the following formula: **Subscription Transactions (1d, 1st time) ÷ Transactions**
5. Click **Save**
# Subscription Metrics
Source: https://docs.northbeam.io/docs/subscription-metrics
Our Subscription Metrics are based on Order tags. To learn more about how this works, reference [Subscription Analytics](https://docs.northbeam.io/docs/subscription-analytics), under the MTA Onboarding->**Add Orders** section.
| Metric Name | Definition | Formula |
| :- | :- | :- |
| Subscription Transactions | All Subscription Transactions | Orders with tags mapped to any subscription category |
| Subscription Transactions (1st Time) | First-Time Subscription Transactions | Orders with tags mapped to the "First Time" subscription category |
| Subscription Transactions (Recurring) | Recurring Subscription Transactions | Orders with tags mapped to the "Recurring" subscription category |
| Subscription Transactions (Other) | Other Subscription Transactions | Orders with tags mapped to the "Other" subscription category |
| Subscription Revenue | All Subscription Revenue | Revenue from Orders with tags mapped to any subscription category |
| Subscription Revenue (1st Time) | First-Time Subscription Revenue | Revenue from Orders with tags mapped to the "First Time" subscription category |
| Subscription Revenue (Recurring) | Recurring Subscription Revenue | Revenue from Orders with tags mapped to the "Recurring" subscription category |
| Subscription Revenue (Other) | Other Subscription Revenue | Revenue from Orders with tags mapped to the "Other" subscription category |
| Subscription Refunds | All Subscription Refunds | Refunds from Orders with tags mapped to any subscription category |
| Subscription Refunds (1st Time) | First-Time Subscription Refunds | Refunds from Orders with tags mapped to the "First Time" subscription category |
| Subscription Refunds (Recurring) | Recurring Subscription Refunds | Refunds from Orders with tags mapped to the "Recurring" subscription category |
| Subscription Refunds (Other) | Other Subscription Refunds | Refunds from Orders with tags mapped to the "Other" subscription category |
| Subscription Shipping | All Subscription Shipping | Shipping from Orders with tags mapped to any subscription category |
| Subscription Shipping (1st Time) | First-Time Subscription Shipping | Shipping from Orders with tags mapped to the "First Time" subscription category |
| Subscription Shipping (Recurring) | Recurring Subscription Shipping | Shipping from Orders with tags mapped to the "Recurring" subscription category |
| Subscription Shipping (Other) | Other Subscription Shipping | Shipping from Orders with tags mapped to the "Other" subscription category |
| Subscription Tax | All Subscription Tax | Tax from Orders with tags mapped to any subscription category |
| Subscription Tax (1st Time) | First-Time Subscription Tax | Tax from Orders with tags mapped to the "First Time" subscription category |
| Subscription Tax (Recurring) | Recurring Subscription Tax | Tax from Orders with tags mapped to the "Recurring" subscription category |
| Subscription Tax (Other) | Other Subscription Tax | Tax from Orders with tags mapped to the "Other" subscription category |
| Subscription Discounts | All Subscription Discounts | Discounts from Orders with tags mapped to any subscription category |
| Subscription Discounts (1st Time) | First-Time Subscription Discounts | Discounts from Orders with tags mapped to the "First Time" subscription category |
| Subscription Discounts (Recurring) | Recurring Subscription Discounts | Discounts from Orders with tags mapped to the "Recurring" subscription category |
| Subscription Discounts (Other) | Other Subscription Discounts | Discounts from Orders with tags mapped to the "Other" subscription category |
# The Media Buyer Newsletter
Source: https://docs.northbeam.io/docs/the-media-buyer-newsletter
Sign up for free performance benchmarks in your inbox every week. Meta, TikTok, Applovin and more!
[Click here](https://themediabuyer.northbeam.io) to sign up for our free newsletter! [themediabuyer.northbeam.io](http://themediabuyer.northbeam.io)
# Technical Documentation
The data presented in The Media Buyer Index is aggregate performance across all brands using Northbeam, with specific brand outliers removed at the top and bottom of each metric range.
Northbeam tracks tens of billions of dollars in ad spend. However, this data is not representative of the entire advertising market - only brands who use Northbeam are tracked in the data. In that respect, this Index is best understood as a measure of week-by-week performance of brands using Northbeam for their marketing.
### How this data is calculated
For each metric, for each brand using Northbeam, we calculate average daily performance over a time period, removing outliers caused by irregularities related to ad budgets, glitches in ad platforms, massive or miniscule ad budgets, and more.
A second average is created across all Northbeam-empowered brands, then those averages are compared over time periods, giving the visual you see in the newsletter.
For example: it's not that CPMs have increased by a total of 4%, it's that the average CPM has increased 4% week over week. This could result in tiny, hundredth-of-a-degree decimal point changes in the data appearing as +200% week over week changes.
Because of the variability in individual performance seen across brands, we didn't want to show absolute numbers for performance as that would be misleading.
Instead, you can look at your week-over-week performance changes in your own data and compare them to this index. That allows you to understand if you're getting hit with market-wide seasonality or algorithmic changes, giving you peace of mind that your ad performance is in line with the wider trend.
Please direct all questions to [bryan@northbeam.io](mailto:bryan@northbeam.io)
# Identify Events
Source: https://docs.northbeam.io/docs/third-party-checkouts
Link a visitor to their email so orders can be attributed when the order ID isn't available in the browser.
`identify` links a visitor's browser session to their **email address**. When the order reaches Northbeam from your backend, Northbeam matches it to that session by email, instead of by order ID.
Use it when your checkout can't give the order ID to the browser. The most common case is a **third-party checkout provider**, such as CheckoutChamp, CartHook, or Purple Dot.
## Which setup you need
Most stores track purchases with a [purchase event](/docs/purchase-pixel), which sends the order ID from the confirmation page. If your checkout can't do that, those orders show as **unattributed**. `identify` fixes this.
| Your checkout | What to use |
| :- | :- |
| Passes the order ID to the confirmation page | [Purchase Events](/docs/purchase-pixel). You don't need this page. |
| Can't pass the order ID (most third-party checkouts) | `identify`. **Follow this page.** |
`identify` works the same way on Shopify and custom stores.
## Requirements
Before you start, confirm that:
* The [Northbeam Pixel](/docs/add-pixel) is on every page, **including your checkout pages**.
* Your checkout is on the **same root domain** as your store. For example, `checkout.yourstore.com` works. A completely different domain does not.
* Every order sent to Northbeam includes `customer_email`.
* You can add scripts to the checkout pages, either in code or through Google Tag Manager.
***
## Set up identify
### Step 1: Add the pixel to your checkout pages
The Northbeam Pixel must run on **every page**, including pages served by your checkout provider. Without it, there's no session for `identify` to attach to.
If your checkout runs on a subdomain (for example, `checkout.yourstore.com`), install the pixel there too. Use the same script and steps from your [platform guide](/docs/add-pixel#which-setup-you-need), and confirm your Content Security Policy allows traffic to your `i.` subdomain.
### Step 2: Call identify when the email is known
Call `identify` on the checkout step where the customer first enters their email, usually the contact or information step. The earlier it fires, the more orders Northbeam can match.
```javascript theme={null}
window.Northbeam.identify("email", "customer@example.com");
```
Replace `customer@example.com` with the customer's email. It usually comes from a template variable or the data layer.
**In your site's code**, use your platform's template variable:
```html theme={null}
```
**In Google Tag Manager:**
1. Create a **Data Layer Variable** for the customer's email (for example, `dlv - customer_email`).
2. Create a **Custom HTML** tag with this script:
```javascript theme={null}
window.Northbeam.identify("email", "{{dlv - customer_email}}");
```
3. Set the trigger to fire on the checkout page where the email is entered.
4. **Publish** the container.
### Step 3: Send customer\_email with every order
Northbeam matches by email, so `customer_email` is **required** on every order.
* **Custom (Orders API):** include `customer_email` in the payload.
```json theme={null}
{
"id": "12345",
"customer_email": "customer@example.com",
"total_price": 99.00,
"currency": "USD"
}
```
* **Shopify:** Northbeam pulls the email from the Shopify order. Check that orders in your Shopify admin have an email.
***
## `identify` reference
You can send the email as plain text or as a SHA-256 hash.
```javascript theme={null}
// Plain-text email
window.Northbeam.identify("email", "john.smith@gmail.com")
// Hashed email
window.Northbeam.identify(
"hashed_email",
"1bb931a0c4488a629e0eb571988b87811c27338ad90888376567c7bce0419e5a"
);
```
| Argument | | Type | Description |
| :- | :- | :- | :- |
| 1 | *required* | String | `"email"` or `"hashed_email"` |
| 2 | *required* | String | The email address, or the SHA-256 hash of the normalized email (64 lowercase hex characters) |
**Use plain-text `"email"` when you can.** We normalize and hash it for you. Use `"hashed_email"` only if your privacy policy doesn't allow sending plain-text emails to third parties.
If you hash the email yourself, trim spaces and lowercase it first. Following the full [normalization guidelines](/docs/hashing-customer-data) improves match rates.
## `identifyCustomerId`
If you'd rather not send email addresses, use `identifyCustomerId`. It links the session to the customer's ID from your order management system, with no personal information shared.
```javascript theme={null}
window.Northbeam.identifyCustomerId("custom", "1234567890");
```
| Argument | | Type | Description |
| :- | :- | :- | :- |
| 1 | *required* | String | Where the ID comes from. Use `"custom"` for the Orders API, or `"shopify"` for Shopify. |
| 2 | *required* | String | The customer ID. Must exactly match the `customer_id` on your Northbeam orders. |
The ID must **exactly match** the `customer_id` on the order. If it doesn't, the match fails.
***
## Troubleshooting
| Problem | Likely cause | Fix |
| :- | :- | :- |
| Third-party checkout orders still unattributed | `identify` isn't firing, or `customer_email` is missing from the order | Confirm `identify` fires before checkout completes, and that orders include `customer_email` |
| `identify` fires but orders don't match | The email in the browser doesn't match the email on the order | Make sure both use the same email |
| Pixel not found on checkout pages | The pixel isn't installed on the checkout domain or subdomain | Install the pixel on the checkout pages |
## Related
* [Purchase Events](/docs/purchase-pixel): tracking purchases when the order ID is available
* [Order Definition (Orders API)](/docs/order-definition): every order field, including `customer_email`
* [Troubleshooting Pixel Tracking](/docs/guide-to-troubleshooting-pixel-tracking)
* [Data Appears as Organic, Other, or Unattributed](/docs/differences-in-unattributed-data)
# Touchpoints Export
Source: https://docs.northbeam.io/docs/touchpoints-export
A step-by-step guide to our touchpoints export.
## Interested in the Touchpoints Export?
The Touchpoints Export feature is available for select service plans. To explore access options for your account, **please contact your Customer Success Manager**.
If you don’t have a representative assigned, please [reach out to our Support Team](https://www.northbeam.io/submit-a-support-ticket) for assistance.
***
## What is the Touchpoints Export?
The **Touchpoints Export** provides a detailed, row-level view of every marketing touchpoint contributing to an order.
Each row represents a single touchpoint and includes attribution credit, order and customer identifiers, and campaign metadata such as platform, category, campaign, ad set, and ad.
It also shows the transactional and revenue credit assigned to that touchpoint across every click-based attribution model.
This export is designed for teams that want to analyze customer journeys, measure channel performance, or feed attribution data directly into their warehouse or BI environment.
If you want aggregated performance data rather than individual touchpoints, use the [Sales page export](/docs/sales-page-export) or the [Data Export API](/docs/northbeam-api-data-export-1). See [Which export should I use?](/docs/exporting-data) to compare all options.
***
## How to Create a Touchpoints Export
Creating a Touchpoints Export takes just a couple minutes.
1. Click **Settings**
2. Click **Manage Exports**
3. Click **Create Scheduled Exports**
***
### Step 1: Select Report Type
**Report type:** `Touchpoints`
(Currently the only available option — more to come soon!)
**Select period:**
You can choose from a variety of date presets such as:
* Today / Yesterday
* Last 7, 14, 30, or 60 days
* This Month / Last Month
* Custom date range
This defines the time range of data included in your export.
***
### Step 2: Select Destination
Choose where the export file will be delivered.
**Supported destinations:**
* **Google Cloud Storage (GCS)**
* Grant **Storage Object Admin** to this service account:
`nb-data-export@north-beam-io.iam.gserviceaccount.com`
* **Amazon S3**
* Create a role that allows Northbeam to write to your bucket.
* The export setup UI displays the exact trust policy, role permissions, and Northbeam principal to use — follow those on-screen values rather than copying them from elsewhere in these docs.
All exports are delivered in **CSV format**.
***
### Step 3: Select Frequency
Choose when your export should run.
You can run exports **once** (one-time) or **on a schedule**:
* **One-time export:** Ideal for historical backfills.
* **Scheduled export:** Choose:
* **Frequency:** Daily, Weekly, or Monthly
* **Time:** Any hour (in your account’s time zone)
This is helpful for seeding your warehouse or rebuilding full historical journeys.
***
## Available Attribution Models
Touchpoints exports include all **click-based attribution models** available in your account.
* First Touch
* Last Touch
* Last Non-Direct Touch
* Linear
* Clicks-Only
***
## **Touchpoints Export – Field Reference**
| **Field** | **Description** |
| - | - |
| **order\_source** | E-commerce platform where the order was placed (e.g., Shopify, Custom). |
| **order\_number** | Unique identifier for the order. |
| **customer\_id** | Unique ID for the customer who placed the order. |
| **lag\_days** | Number of days between the touchpoint and the purchase. |
| **purchase\_time** | Timestamp when the order was completed. |
| **ad\_interaction\_time** | Timestamp when the ad click occurred. |
| **order\_value** | Total value of the order. |
| **platform** | Ad platform (matches *Platform (Northbeam)* in the dashboard). |
| **category** | Campaign category (matches *Category (Northbeam)* in the dashboard). |
| **campaign\_name** | Campaign name. For non-integrated channels, value in `utm_campaign`. |
| **campaign\_id** | Campaign ID. For non-integrated channels, value in `utm_campaign`. |
| **adset\_name** | Ad set name. For non-integrated channels, value in `utm_term`. |
| **adset\_id** | Ad set ID. For non-integrated channels, value in `utm_term`. |
| **ad\_name** | Ad name. For non-integrated channels, value in `utm_content`. |
| **ad\_id** | Ad ID. For non-integrated channels, value in `utm_content`. |
| **attribution\_model** | Attribution model (e.g., First Touch, Last Touch, LNDT, Linear, Clicks-Only). |
| **transaction\_credit** | Transaction credit assigned to this touchpoint. Will be fractional if the attribution model distributes credit (e.g., Linear or Clicks-Only). |
| **revenue\_credit** | Revenue credit assigned to this touchpoint. Will be fractional if the attribution model distributes credit (e.g., Linear or Clicks-Only). |
***
## FAQs
**What data is included?**
* Each export includes every marketing touchpoint that contributed to an order, along with attribution credit, campaign metadata, and customer identifiers. Each row represents a single touchpoint.
**How often can we export?**
* You can run exports daily, weekly, or monthly — scheduled to start at the top of any hour in your time zone.
**Can we backfill history?**
* Yes! Use a one-time export with custom dates for historical data, or set a rolling window (for example, the last 30 days) to keep things automatically up to date.
**Where do the files go?**
* Exports are delivered to **Google Cloud Storage (GCS)** or **Amazon S3**.
If you use **Snowflake**, just land files in GCS or S3 and move them through your existing data pipeline.
**Who needs access to our GCS bucket?**
* Grant **Storage Object Admin** access to `nb-data-export@north-beam-io.iam.gserviceaccount.com`.
Optionally, you can also add `bqdt-runner@nb-bq-adhoc.iam.gserviceaccount.com`.
**Can I manage exports myself?**
* Yes! You can create, edit, and delete exports anytime from the Data Exports UI or API — no engineering help needed.
**What time zone does the export use?**
* All timestamps (like `purchase_time` and `ad_interaction_time`) follow your Northbeam account’s configured time zone *(Settings > Profile)*.
**Does the export include direct traffic?**
* Yes — direct traffic is included when it’s part of a customer journey. Only orders with *no* touchpoints at all (fully unattributed) are excluded.
**Can I include view-based attribution models?**
* Touchpoints Exports currently include **click-based models only**.
**Can I change the file format?**
* Not right now — all exports are delivered as **CSV files**.
**How large can an export be?**
* Exports could include millions of rows depending on your order volume. If you’re working with very large data sets, it’s best to use shorter date ranges and schedule recurring exports instead of one big pull.
**Can I filter by platform or campaign before exporting?**
* Exports include all touchpoints for your selected date range, regardless of platform or campaign. You can still filter or segment by platform, campaign, or other fields directly in the CSV once it’s delivered.
**How can I check if my export ran successfully?**
* You can track export status under **Settings → Manage Exports**.
# Tracking for Bliss Point by Tinuiti
Source: https://docs.northbeam.io/docs/tracking-for-bliss-point-by-tinuiti
This guide will show you how to connect your Bliss Point Media account and pull the following metrics:
* Spend and Impressions, which enables our view-through modeling data
## Setting up Bliss Point by Tinuiti within Northbeam involves two steps
Step 1: Get AWS access keys and S3 Bucket Name
Step 2: Share this information with our Support Team
## Step 1: Get AWS access keys and S3 Bucket Name
Please log into your Bliss Point Media account and find the following:
* AWS Programmatic Access Keys
* S3 Bucket Name
## Step 2: Share with our Support Team
Please [reach out to our Support Team](https://www.northbeam.io/submit-a-support-ticket) with your AWS Keys and S3 Bucket Name.
We'll plug this into our backend and enable our integration!
# Tracking Ads using Off-Domain Sites
Source: https://docs.northbeam.io/docs/tracking-for-off-domain-sites
This guide explains how to track ads that send users to an off-domain site before they reach your main domain.
## What Is an Off-Domain Site?
An **off-domain site** is a webpage hosted on a different root domain from the website connected to Northbeam.
### Common Examples
* Advertorials
* Editorial reviews
* “Top 10” product roundups
* Affiliate or partner landing pages
* Third-party presell pages
### Example
* **Off-domain site:** `https://www.mysubscriptionaddiction.com/northbeam`
* **Main domain:** `https://www.northbeam.io`
Example flow:
**Meta Ad →** `mysubscriptionaddiction.com` **→** `northbeam.io`
Without the correct setup, Northbeam may record the final visit as a referral from the off-domain site instead of connecting it to the original ad.
> **Tracking requirement:** Northbeam must be able to capture the original ad information before or when the visitor reaches a page where the Northbeam Pixel fires.
***
## Why Additional Setup Is Required
Northbeam's first-party tracking is tied to your main root domain.
If an ad sends someone directly to another root domain, the original ad session does not automatically carry over when the visitor later reaches your main website.
Without the correct setup, Northbeam may lose the connection to the original:
* Campaign
* Ad set or ad group
* Ad
* Associated ad spend
Northbeam supports two approaches:
1. **Use a Northbeam Redirect Link**
2. **Preserve the Northbeam tracking parameters between domains**
***
## Option 1: Use a Northbeam Redirect Link
**Available for:** Meta, Pinterest, Klaviyo, and Attentive
This is usually the easiest option because it requires less custom development.
### How It Works
The visitor briefly passes through your main domain before being redirected to the off-domain page.
Example:
**Meta Ad →** `northbeam.io` **redirect →** `mysubscriptionaddiction.com` **→** `northbeam.io`
This allows Northbeam to capture the original ad visit before the visitor leaves your main domain.
### Benefits
* Requires less custom development
* Does not require the Northbeam Pixel on the off-domain site
* Does not require you to preserve Northbeam parameters across every CTA
### Limitations
* Redirect Links are only available for supported platforms
* Google Ads and X may block or penalize redirect behavior
* Unsupported platforms, such as TikTok or Taboola, cannot use this method
* Other URL parameters may not automatically carry through to the final landing page
### Important: Other URL Parameters May Not Carry Through
Ad platforms can add parameters dynamically when someone clicks an ad.
For example, Meta may add an `fbclid` parameter.
Northbeam can still capture the visit during the redirect even if `fbclid` does not appear on the final off-domain landing page.
However, this can matter if another analytics or attribution provider needs that parameter.
> If another tool requires parameters such as `fbclid` on the off-domain page, confirm that those parameters are preserved through the redirect. If not, parameter preservation may be a better option.
### Setup Steps
1. Open the **Mini Menu** in Northbeam.
2. Go to **Guides → Redirect URLs Guide**.
3. Enter the final off-domain destination URL.
4. Generate the Redirect Link.
5. Copy the generated URL and tracking parameters into the ad platform.
> **Important:** Redirect Links use a **different tracking parameter structure** from Northbeam's normal platform tracking parameters. Use the exact URL and parameters generated by the Redirect URLs Guide.
***
## Option 2: Preserve Tracking Parameters Between Domains
**Available for:** All platforms
Use this option when:
* Redirect Links are not supported
* You control the off-domain site
* You can update its links or CTAs
* Other tracking parameters need to remain available through the funnel
### How It Works
The ad sends the visitor directly to the off-domain page with Northbeam's tracking parameters.
Those same parameters must then be preserved when the visitor moves to the main domain.
Example:
**Ad + Northbeam parameters → Off-domain site → Main domain + same Northbeam parameters**
When Northbeam records the visit:
* The Northbeam Pixel must fire
* The full Northbeam tracking string must still be available
* The original campaign, ad set or ad group, and ad IDs must be preserved
> **If you can reliably preserve the Northbeam tracking parameters between domains, a Redirect Link is not required.**
### Example
A visitor lands on:
```text theme={null}
https://example-lander.com/article?nbt=abc123&nb_placement=feed
```
The CTA to the main site should preserve the same values:
```text theme={null}
https://yourstore.com/product?nbt=abc123&nb_placement=feed
```
This approach can also help preserve other dynamic parameters, such as `fbclid`, if your funnel needs them.
***
### TikTok Example
Northbeam's TikTok parameters are:
```text theme={null}
nbt=nb:tiktok::__CAMPAIGN_ID__:__AID__:__CID__&nb_platform=tiktok
```
Example off-domain URL:
```text theme={null}
https://www.mysubscriptionaddiction.com/article?nbt=nb:tiktok::123456789:987654321:456789123&nb_platform=tiktok
```
When the visitor reaches the main domain, the same values should still be present:
```text theme={null}
https://www.northbeam.io/product?nbt=nb:tiktok::123456789:987654321:456789123&nb_platform=tiktok
```
In this example:
* `123456789` = campaign ID
* `987654321` = ad group ID
* `456789123` = ad ID
***
### Google Ads Example
Northbeam's Google Ads parameter is:
```text theme={null}
nbt=nb%3Aadwords%3A{network}%3A{campaignid}%3A{adgroupid}%3A{creative}
```
Example off-domain URL:
```text theme={null}
https://www.mysubscriptionaddiction.com/article?nbt=nb%3Aadwords%3Ag%3A123456789%3A987654321%3A456789123
```
The same value should remain when the visitor reaches the main domain:
```text theme={null}
https://www.northbeam.io/product?nbt=nb%3Aadwords%3Ag%3A123456789%3A987654321%3A456789123
```
In this example:
* `g` = Google network
* `123456789` = campaign ID
* `987654321` = ad group ID
* `456789123` = creative ID
> These are dummy values used only to show the expected structure.
***
## Important Technical Considerations
Tracking parameters can be lost as a visitor moves through the off-domain site.
For example:
1. The visitor lands on an article.
2. They navigate to another page.
3. They click a CTA to the main website.
If the original parameters are not preserved, they may disappear before the visitor reaches the main domain.
Your team is responsible for keeping the original Northbeam parameters available throughout the journey.
Common implementation methods include:
* Link rewriting
* Google Tag Manager
* Custom JavaScript
* Cookies
* Local storage
* Custom development
Northbeam does not require one specific method.
> **The goal:** The original Northbeam tracking string and IDs must still be available when the Northbeam Pixel records the visit.
***
## Which Option Should I Use?
| If this is your setup | Use this |
| :- | :- |
| You want the simplest setup and your platform supports Redirect Links | **Northbeam Redirect Link** |
| You cannot edit the off-domain page or its CTAs | **Northbeam Redirect Link** |
| You control the off-domain site and can preserve parameters across links | **Parameter Preservation** |
| Your ad platform does not support Redirect Links | **Parameter Preservation** |
| Another tool needs dynamic parameters such as `fbclid` on the off-domain page | **Parameter Preservation may be a better fit** |
> **Key point:** Neither method is better in every case. The goal is to preserve the original ad information in a way that works with the rest of your tracking stack.
***
## How Do I Confirm the Setup Is Working?
Test the **full customer journey** using a live ad or a test URL with Northbeam tracking parameters.
Confirm that:
1. The visitor follows the expected funnel.
2. The Northbeam Pixel fires where expected.
3. The correct Northbeam tracking information is available when the pixel fires.
4. Northbeam records a Visit under the expected campaign, ad set or ad group, and ad.
### If You Use Parameter Preservation
Confirm that the parameters remain available after each important page transition.
Example:
**Ad → Off-domain page + Northbeam parameters → CTA → Main domain + same parameters**
If the parameters disappear before Northbeam records the visit, attribution may be lost.
### If You Use a Redirect Link
Confirm that Northbeam records the Visit from the redirect flow.
If another provider depends on parameters such as `fbclid`, confirm separately that those parameters reach the page where that provider needs them.
Check **Visit data** in Northbeam.
If Visits appear under the correct campaign, ad set or ad group, and ad, the Northbeam tracking setup is working.
***
## Can I Use Basic UTMs Instead?
You can add standard UTMs to the link from the off-domain site to the main domain, but this will not necessarily connect the visit to the original ad.
Basic UTMs may help Northbeam categorize the traffic, but they may not contain the campaign, ad set, ad, and other IDs needed to connect the visit to the original ad spend.
For paid advertising, use either:
* A Northbeam Redirect Link
* The complete set of required Northbeam tracking parameters preserved between the off-domain site and the main domain
# Tracking for OpenAI
Source: https://docs.northbeam.io/docs/tracking-for-openai-ads
This guide will show you how to set up OpenAI Ads spend and click based attribution tracking in Northbeam.
## Introduction
This guide will show you how to set up OpenAI Ads spend and click based attribution tracking in Northbeam.
Once the account is connected and the required Northbeam tracking parameter is added, Northbeam will receive:
* Spend data from OpenAI Ads
* Platform reported click data from OpenAI Ads
* Campaign, ad group, and ad identifiers used for reconciliation and attribution
OpenAI Ads supports the following Northbeam attribution models:
* Clicks Only
* Last Click
* First Click
* Linear
| Input | Output | If the input is missing |
| - | - | - |
| OpenAI Ads API key | Northbeam can connect to the selected OpenAI Ads account and pull spend and platform reported click data. | OpenAI Ads data will not appear in Northbeam. |
| Northbeam tracking parameter | OpenAI Ads visits can be reconciled to the correct campaign, ad group, and ad. | Visits and attributed results may be missing or assigned incorrectly. |
***
## Before You Start
Make sure you have:
* Access to the correct OpenAI Ads account
* Permission to create an API key in OpenAI Ads Manager
* Access to the correct Northbeam dashboard
* Permission to edit the landing page query parameters for your OpenAI Ads ad groups
***
## Step 1: Create an OpenAI Ads API Key
1. Sign in to [OpenAI Ads Manager](https://ads.openai.com/).
2. Use the account switcher in the bottom left corner to select the ad account you want to connect.
3. Go to **Settings > General >API Keys**.
4. Click **Create New Key**.
5. Enter a recognisable name, such as `Northbeam ingestion`.
6. Copy the API key.
> **Important: An API key is shown only once. Copy it when it is created. If it is lost, you must generate a new key.**
Keep the API key secure. Do not include it in landing page URLs or share it outside the people responsible for the integration.
***
## Step 2: Connect Your OpenAI Ads Account
Open the OpenAI Ads integration in Northbeam:
* **During onboarding:** Go to **I**[**ntegrations and UTMs > OpenAI Ads**](https://dashboard.northbeam.io/onboarding?step=configure-platforms).
* **From the dashboard:** Go to [**Settings > Connections > OpenAI Ads**](https://dashboard.northbeam.io/settings/connections).
1. Paste the API key into the **API Key** field.
2. Confirm that the correct OpenAI Ads account is displayed.
3. Click **Connect**.
After the connection succeeds, the card will display the linked ad account and a green confirmation icon.
***
## Step 3: Add the Northbeam Tracking Parameter
Add the Northbeam tracking parameter to the **Landing page query parameters** field at the campaign level:
```text theme={null}
nbt=nb:openai:openai:{campaign_id}:{ad_group_id}:{ad_id}
```
A campaign level parameter automatically applies to all ad groups and ads within that campaign. The template values are replaced with the relevant campaign, ad group, and ad IDs when the ad is served.
Repeat this process for each active campaign.
### UTM Parameter Priority
> **Important:** Parameters added at a lower level override those added at a higher level. The order of priority is **ad level > ad group level > campaign level**.
>
> If an ad group or ad already has its own query parameters, make sure the Northbeam `nbt` parameter is also included at that level. Otherwise, the campaign level parameter may be overridden and Northbeam tracking could be lost.
## Step 4: Verify the Integration
Complete the following checks:
* The OpenAI Ads connection card shows a green confirmation icon.
* The correct ad account ID and timezone appear on the connection card.
* The NBT parameter is present in every active OpenAI Ads ad group.
* OpenAI Ads spend and platform reported clicks begin appearing in Northbeam.
* OpenAI Ads visits are assigned to the expected campaign, ad group, and ad.
The integration can backfill up to two years of historical spend when an account is first connected.
Historical attribution still depends on whether valid tracking parameters were present on the ads during that period.
***
## OpenAI Ads FAQ
## 1. Does the OpenAI Ads integration support attribution and revenue tracking?
Yes. OpenAI Ads supports click based attribution when the API connection is active and the required NBT parameter is present on the ad group.
## 2. Which Northbeam attribution models are supported?
OpenAI Ads supports:
* Clicks Only
* Last Click
* First Click
* Linear
Clicks + Modeled Views and Clicks + Deterministic Views are not supported for this integration.
## 3. Does OpenAI Ads require UTMs?
The required Northbeam tracking parameter is:
```text theme={null}
nbt=nb:openai:openai:{campaign_id}:{ad_group_id}:{ad_id}
```
This parameter allows Northbeam to reconcile visits with the correct OpenAI Ads campaign, ad group, and ad.
## 4. Does Northbeam pull platform reported clicks?
Yes. Northbeam pulls platform reported click data from OpenAI Ads.
You can compare Northbeam visits with OpenAI Ads clicks to identify possible tracking coverage issues.
## 5. How far does spend backfill?
The integration can backfill up to two years of historical spend when the account is first connected.
## 6. What should I do if I lose the API key?
OpenAI Ads displays an API key only once.
If you lose it, return to **Settings > API Keys**, generate a new key, and update the OpenAI Ads connection in Northbeam.
## 7. Why is OpenAI Ads data missing or incomplete?
Check the following:
* Go to **Settings > Connections** and confirm that the OpenAI Ads connection is green.
* Confirm that the correct OpenAI Ads account is linked.
* Generate a new API key and reconnect if the existing key is no longer valid.
* Confirm that every active ad group contains the exact Northbeam tracking parameter.
* Check that the landing page preserves the NBT parameter after redirects.
# Tracking for Non-Integrated Channels
Source: https://docs.northbeam.io/docs/tracking-for-other-platforms
This guide will show you how to set up tracking for any Non-Integrated Channels.
What is a Non-Integrated Channel?
A **Non-Integrated Channel** is any marketing platform not natively connected to Northbeam. Typically, these are platforms not listed under [Connections](https://dashboard.northbeam.io/settings/connections).
**Common examples:**
* Email/SMS Platforms (e.g., Yotpo, Omnisend, GetResponse, Sendlane, Mailchimp)
* Note: Klaviyo and Attentive have their own setup guides, but spend still needs to be uploaded manually.
* Influencer Marketing
* Podcasts
* Direct Mail
* ShareASale
* StackAdapt
* PepperJam
* Parternize
* Taboola
* Commission Junction
* DV360
## How to track Non-Integrated Channels
Metrics
How does Northbeam track?
Notes
Visits, Revenue, Transactions
Standard UTMs
*(ex. utm\_source, medium, campaign)*
Our pixel captures standard UTM parameters (commonly used with Google Analytics) to track visit and conversion data from any platforms that are not directly integrated.
The standard UTM parameters include:
utm\_source\
utm\_medium\
utm\_campaign
You have the flexibility to assign any values you prefer.
For example, if you wanted to track performance on Criteo, you might use:
utm\_source=paid\
utm\_medium=criteo\
utm\_campaign=prospecting\_campaign
Spend
Spendsheet or Spend API
Costs are normally pulled through our native integrations. However, for any costs from platforms that don't natively integrate with Northbeam, you could use a Spendsheet or the Spend API.
***
## Step 1: Add UTMs to Track Visits, Revenue, and Transactions
UTMs are key important here. We can ingest any Google Analytics UTMs (source, medium, campaign, content, term) as a fallback in the event Northbeam UTMs unavailable. Think of UTMs like name tags. Without them, we'll see the traffic, but won't know what campaigns, adsets, or ads drove the session, along with anything that happens inside the session, like a conversion. UTMs enable the granularity that is important for decision making.
#### If your platform is in our UTM Guide, use the recommended parameters
To find the guide:
1. Open the [UTM Guide](https://dashboard.northbeam.io/settings/utm-guide).
#### If your platform is not listed, use Google Analytics UTM parameters
* utm\_source
* utm\_medium
* utm\_campaign
* utm\_term (optional)
* utm\_content (optional)
### What Values Should I Use?
You can use any values for these parameters—just make sure they’re consistent with how you want to view the data in your dashboard.
| UTM Parameter | Where it pulls in Northbeam |
| :- | :- |
| utm\_source | Campaign Level |
| utm\_medium | Campaign Level |
| utm\_campaign | Campaign Level (line item) |
| utm\_term | Adset Level (line item) |
| utm\_content | Ad Level (line item) |
Below is a visual on how utm\_campaign is reported within your Sales page.
### Influencer Example
Let’s say you're running influencer campaigns and want to track each influencer individually.
In this case, place the influencer’s name in utm\_campaign. This will segment campaign rows by influencer in the dashboard.
If you'd also like to track the offer used, you can place that value in utm\_term. This will segment the ad-level rows by the offer.
Example URL:\
[https://mystore.com?utm\_campaign=influencer-name\&utm\_term=offer](https://mystore.com?utm_campaign=influencer-name\&utm_term=offer)
## Step 2: Upload Costs via Custom Spend
This step is optional. This is only if you wish to upload associated costs. If you skip this step, Northbeam will still track Visits, Revenue, and Orders—as UTM parameters are used. However, costs will not be displayed in your dashboard.
#### There are two ways to upload Custom Spend
| Method | Description | Notes |
| :- | :- | :- |
| Spend API | Send spend data directly to your dashboard in an automated fashion through Spend API. | Data needs to live in an internal database (ex. AWS, Snowflake, Databricks, Azure, Domo, etc.) and will need a Reverse ETL to move it out. |
| Spend Sheet | Enter your data into a Spend Sheet (gSheet), which will be connected to your dashboard. | Less technical method, but will require manual input. |
### How do I set up a Spend API or Spend Sheet?
Learn about both methods and how to set them up [here](/docs/add-spend).
***
## Non-Integrated Channels FAQ
### 1. I uploaded my spend numbers, but I can't find them.
Please be sure to look in the 'Other' platform group. If you'd like to group together the spend and revenue, you could use a Label.
### 2. How do I track audio or video platforms where it may be difficult to get UTMs on links?
We understand it's challenging to embed UTMs on all links - especially from channels that often utilize discount codes -- like Influencers, Affiliates, and Podcasts.
As a workaround, we've seen our customers find success with **Vanity Links**. Vanity links can be used to **redirect** users to a UTM-embedded URL, but tend to be more shareable.
Ex) **mystore.com/influencer1** redirects to **mystore.com?utm\_source=influencer\&utm\_campaign=influencer1**
**mystore.com/influencer1** is likely more easily shared than **mystore.com?utm\_source=influencer\&utm\_campaign=influencer1**
If you're on Shopify, \[here's an article on how to create redirects.]\([https://help.shopify.com/en/manual/online-store/menus-and-links/url-redirect](https://help.shopify.com/en/manual/online-store/menus-and-links/url-redirect)
### 3. Can I use Northbeam UTM parameters on my ads?
We only support the Northbeam parameters on our UTM Guide. If you don't see your platform on your guide, please refrain from using Nortbeam parameters as they will not do anything -- as they are not mapped in our backend.
Instead, please use Standard UTM Parameters, listed above in "Step 1".
Standard UTM Parameters will not a negative impact on tracking. They track just as well as Northbeam UTM Parameters.
### 4. Can I track using Discount Codes?
Currently, all the data we pull into the Sales page are primarily segmented by UTM parameters and not Discount Codes. However, we are working on a solution for Discount Code tracking yet no timeline at the moment.
In the meantime, you can reference Discount Codes on the [Customer LTV](https://dashboard.northbeam.io/customers) page, which reflects the average lifetime value of each code.
Vanity Links could be used as a workaround. See under "Step 1".
### 5. Why do I see a data discrepancy?
**Discrepancies in Revenue, Orders, and Visits are expected.** The reason for this lies in the differences between Northbeam's attribution model and the corresponding platform's attribution model. Each attribution model has a unique method of allocating credit.
For example, Northbeam's Clicks-Only model divides credit across all touchpoints and tries to push credit to your upper funnel channels. Let's say your in-platform model uses Last Click, which gives credit to the last touchpoint in the journey. This is going to cause a discrepancy.
To take it one step further, let's say both Northbeam and in-platform are using Last Click. Northbeam is unique in that we recognize all touchpoints from every single channel. Whereas most platforms only recognize touchpoints from that same platform.
In addition, there's often a difference in the attribution window. By default, Northbeam leverages a 1-Day window, which is different than many other platforms' default.
To get the most apples to apples comparison, be sure to compare data using same Attribution Model and Attribution Window. But keep in mind, it will never be exact.
#### If you suspect a tracking issue, please review the following checklist
* **UTMs**: Ensure all your ads contain Northbeam UTMs, listed above under Step 2.
* **Northbeam Pixel**: Ensure the Northbeam Pixel is firing on your landing page. Note that some site themes may not automatically transfer to landing pages on certain third-party apps, necessitating manual pixel placement.
* **Purchase Pixel:** Confirm that the Purchase Pixel is firing on your checkout page.
* **A-Record Setup:** Verify that the A-Record is correctly configured in your DNS Settings.
# Tracking for Paramount
Source: https://docs.northbeam.io/docs/tracking-for-paramount
This guide will show you how to set up Paramount Ads spend tracking and deterministic view attribution in Northbeam.
## Introduction
This guide will show you how to set up Paramount Ads spend tracking and deterministic view attribution in Northbeam.
Once the Paramount pixel is installed and the account is connected, Northbeam will receive:
* Spend data from Paramount Ads
* Deterministic impression and view data used for Clicks + Deterministic Views attribution
* Paramount revenue and ROAS reporting when eligible views can be matched to orders
Paramount Ads is a TV platform and does not provide clicks for this integration. As a result, Paramount does not use UTMs or NBT parameters and is not supported in click based attribution models.
| Input | Output | If the input is missing |
| - | - | - |
| Paramount pixel | Deterministic impression and view data can be matched to orders for Clicks + Deterministic Views attribution. | Paramount view based revenue and conversion attribution will not be available. |
| Paramount Ads connection | Paramount spend and view data appears in Northbeam reporting. | Paramount data will not appear in Northbeam. |
***
## Step 1: Install the Paramount Pixel
Before connecting the integration, install the Paramount pixel on the website where customers place orders.
The pixel is required for Paramount view data to be matched to Shopify orders.
[Open the Paramount Ads Manager pixel setup page](https://adsmanager-us.paramount.com/pixel/manual?utm_source=Grid\&utm_content=Pixel)
> **Sign in required:** You must be signed in to Paramount Ads Manager to open the pixel setup page.
***
## Step 2: Connect Your Paramount Ads Account
Northbeam connects to Paramount Ads through an authorization flow.
* **Onboarding:** Go to **Integrations → Paramount Ads**.
* **Dashboard:** Open [Connections](https://dashboard.northbeam.io/settings/connections) and select **Paramount Ads**.
1. Click **Connect** on the Paramount Ads integration card.
2. Sign in using your Paramount Ads Manager email address and password.
3. Review the requested permissions and click **Allow Access**.
4. After you are redirected to Northbeam, confirm that the correct ad account appears under **Linked accounts**.
A green check confirms that the Paramount Ads account is connected successfully.
> **To connect another account, select Link an additional ad account.**
***
## Step 3: Verify the Integration
Allow up to 24 hours after setup for Paramount spend and view data to appear.
You can then verify the integration from the Sales Attribution or Model Comparison page.
* Select the **Clicks + Deterministic Views** model.
* Confirm that Paramount spend is present for the expected date range.
* Confirm that Paramount revenue and ROAS populate when deterministic views are matched to orders.
***
## Paramount Ads FAQ
## 1. Does the Paramount Ads integration support attribution or revenue tracking?
Yes. Paramount supports Clicks + Deterministic Views attribution when the Paramount pixel is installed and the account is connected.
It does not support click based attribution because Paramount does not provide click data for this TV integration.
## 2. Does Paramount require UTMs or NBT parameters?
No. Paramount is a view based TV platform in this integration, so UTMs and NBT parameters are not required or supported.
## 3. Which Northbeam attribution model should I use for Paramount?
Use **Clicks + Deterministic Views**.
Clicks Only, Last Click, First Click, Linear, and Clicks + Modeled Views are not supported for Paramount attribution.
## 4. How far does Paramount spend backfill?
When the account is first connected, the integration can backfill the full available spend history provided by Paramount.
## 5. Why might Paramount reporting differ from Northbeam?
Paramount uses a 30 day attribution lookback period in its platform reporting and may assign full credit to conversions it attributes to Paramount.
Northbeam uses its own attribution methodology, selected attribution window, and cross channel touchpoint data. Differences between the two platforms are therefore expected.
## 6. Why don't I see Paramount data yet?
Paramount spend and view data may take up to 24 hours to appear after the integration is connected.
If the data is still missing after 24 hours:
* Open [Connections](https://dashboard.northbeam.io/settings/connections) and check the Paramount Ads connection for errors.
* Confirm that the Paramount pixel is installed on the website where orders are placed.
* Reconnect the integration if the authorization has expired.
* Confirm that the correct Paramount Ads account is linked.
## 7. I think there's an issue with my Paramount integration. Please help!
Please reference [Troubleshooting Northbeam Data](/docs/troubleshooting-tracking-issues).
* Connection: Open [Connections](https://dashboard.northbeam.io/settings/connections) and check for any errors on the Paramount Ads connection.
* Authentication: Reconnect the integration if authorization has expired
* Data Sync Timing: Spend data may take some time to appear after connecting, depending on Paramount Ads data sync timing
# Tracking for ShopMy
Source: https://docs.northbeam.io/docs/tracking-for-shopmy
ShopMy manages the Meta ad account used for Spotlight campaigns, so you do not need to connect that Meta ad account directly to Northbeam.
## Introduction
**This guide shows you how to track ShopMy Spotlight spend and revenue in Northbeam.**
ShopMy manages the Meta ad account used for Spotlight campaigns, so you do not need to connect that Meta ad account directly to Northbeam.
Instead:
* ShopMy sends your Spotlight spend to Northbeam automatically.
* ShopMy adds UTMs to your Spotlight campaigns.
* Northbeam uses those UTMs to track visits and attributed revenue.
* Northbeam labels group matching spend and revenue into the same campaign row.
Once set up, you can view Spotlight spend, attributed revenue, and ROAS in Northbeam.
### Do not use [Northbeam's Meta UTMs](/docs/channels/meta/overview#northbeam-utm-parameters) on ShopMy Spotlight campaigns.
ShopMy automatically adds the UTMs needed for Spotlight tracking. Leave these UTMs as provided by ShopMy.
**Using** [**Northbeam's Meta UTMs**](/docs/channels/meta/overview#northbeam-utm-parameters)\*\* will prevent the Spotlight spend and revenue from matching at the campaign level.\*\* You may still be able to group the data under the same platform, but metrics such as **ROAS and CAC by creator** will not consolidate correctly.
***
## Step 1: Connect ShopMy to Northbeam
First, create your Northbeam API credentials.
In Northbeam:
1. Open [API Keys](https://dashboard.northbeam.io/settings/api-keys).
2. Click **Create new API Key**.
3. Copy your **API Key** and **Data Client ID**.
In ShopMy:
1. Go to **Account Settings > Integrations and Tracking**.
2. Find the **Northbeam** connection.
3. Paste in your **API Key** and **Data Client ID**.
4. Save the connection.
That's it. ShopMy will start sending your Spotlight spend to Northbeam on its next daily sync.
You do not need to upload Spotlight spend manually.
***
## Step 2: Set Up Your ShopMy Labels
### This label setup should take about 2 minutes.
If you would like help with this step, contact your Northbeam CSM or [submit a support ticket](https://www.northbeam.io/submit-a-support-ticket).
Next, set up two labels so your Spotlight spend and attributed revenue appear together in Northbeam:
1. Group ShopMy Spotlight spend and revenue under the same platform.
2. Consolidate matching campaign rows.
## Part 1: Create the ShopMy Platform Label
First, group your ShopMy Spotlight spend and revenue under the same platform.
1. Go to the [Breakdowns menu](https://dashboard.northbeam.io/breakdowns).
2. Look for an existing breakdown called `Platform (Northbeam)`.
3. If it does not exist, create a new breakdown called `Platform (Northbeam)`.
> **Important:** Use `Platform (Northbeam)` exactly as written, including capitalization and spacing.
4. Create a new segment called `ShopMy - Spotlights`.
5. Add the rule `Name contains Spotlight`.
6. Click **Save**.
This groups your ShopMy Spotlight spend and revenue under the same platform because both use `Spotlight` in the campaign name.
## Part 2: Create the Consolidation Breakdown
Next, create a breakdown that combines matching spend and revenue rows.
### Create the Breakdown
1. Create a new breakdown, such as `Spend + Rev Consolidation`.
2. Switch to the **Advanced Editor**.
### Add the Consolidation Logic
1. Create a new segment, such as `All Campaigns Consolidation`.
2. Add the rule `Name` `does not contain` `??!!!`.
> **Note:** `??!!!` is just a placeholder used to make this rule apply to all campaigns. You can replace it with any value that would not normally appear in a campaign name.
>
> This also makes the breakdown reusable for other Spend Sheet or Spend API channels that need matching campaign names to consolidate.
3. Set the **Output Label Value** to `{{{data.name}}}`.
4. Click **Add Segment**.
5. Click **Save**.
The **Spend + Rev Consolidation** breakdown and segment names can be changed.
The important part is the **Output Label Value**. `{{{data.name}}}` uses the existing campaign name as the label.
When the ShopMy spend campaign name matches its `utm_campaign`, Northbeam gives both rows the same output label and groups them together.
For example, if both use `Spotlight 1111 - John Doe`, the spend and attributed revenue will appear under the same campaign.
### Optional: Use Raw Code
Instead of creating the segment manually, you can paste the code below into the raw editor.
```json theme={null}
[
{
"name": "All Campaigns Consolidation",
"output": "{{{data.name}}}",
"active": true,
"priority": 10,
"matcher": {
"and": [
{
"!contains": [
{
"var": "name"
},
"??!!!"
]
}
]
},
"createdAt": "2026-08-14T15:43:48.231Z"
}
]
```
1. Create your `Spend + Rev Consolidation` breakdown and click **View Raw**.
2. Paste in the code from above.
3. Scroll down and click **Save**.
***
## Step 3: Validate Your Setup
After your labels are set up:
1. Apply **Platform (Northbeam)** as a breakdown.
2. Add your **Spend + Rev Consolidation** breakdown underneath it.
3. Find **ShopMy - Spotlights**.
4. Add metrics that include both Spend and Session or Conversion data (ex. **Spend, Visits, Cost per Visit, Orders, CPO, Revenue, or ROAS**)
5. Confirm that your Spotlight campaigns show both spend and visits where expected.
Visits are the best first check because they usually appear before orders or revenue. If a campaign has both spend and visits, that is a good sign that the spend and attribution data are connecting correctly.
It is normal for some campaigns to only show spend or visits.
If you expect a campaign to have both, check that the ShopMy campaign name matches the `utm_campaign`.
Look for differences in:
* Spelling
* Spaces
* Capitalization
* Punctuation
* Hyphens
***
## ShopMy Organic Traffic
The setup above is for **ShopMy Spotlights**.
For organic ShopMy traffic, you can use your normal UTM structure.
We recommend using a clear `utm_campaign`, such as `utm_campaign=[campaign name]`, so you can easily identify ShopMy campaigns in Northbeam.
Organic ShopMy traffic does not require the spend consolidation setup above.
***
## ShopMy FAQ
## 1. Does ShopMy automatically send spend to Northbeam?
Yes. Once you add your Northbeam API Key and Data Client ID in ShopMy, ShopMy sends your Spotlight spend to Northbeam during its daily sync.
## 2. Do I need to add UTMs to my Spotlight campaigns?
No. ShopMy automatically adds the required UTMs to Spotlight campaigns.
## 3. Why do I need the labels?
The labels group matching ShopMy spend and Northbeam-attributed revenue together at the campaign level.
This lets you view Spend, Revenue, and ROAS for each Spotlight campaign in one place.
## 4. Why aren't my spend and revenue appearing together?
Check that the ShopMy campaign name matches the corresponding `utm_campaign`.
Look for differences in spelling, spaces, capitalization, punctuation, or hyphens.
If the names match and you still have an issue, contact your Northbeam CSM or submit a support ticket.
## 5. Why are my ShopMy, Meta, and Northbeam numbers different?
ShopMy, Meta, and Northbeam use different attribution methods.
Because of this, revenue, conversions, and ROAS may differ between platforms.
## 6. Does this setup apply to organic ShopMy traffic?
No. This setup is specifically for **ShopMy Spotlights**.
Organic ShopMy traffic can use your normal UTM structure and does not require Spotlight spend consolidation.
## 7. I need help setting up my labels. What should I do?
Contact your Northbeam CSM or [submit a support ticket](https://www.northbeam.io/submit-a-support-ticket) and ask for help setting up your **ShopMy Spotlight labels**.
# Troubleshooting Northbeam Data
Source: https://docs.northbeam.io/docs/troubleshooting-tracking-issues
Find the right checks when visits, orders, spend, attribution, or exports look incorrect.
Start with the symptom you can observe. Each guide explains what to check, what the result means, and when to contact Support.
| What looks wrong? | Start here |
| :- | :- |
| Visits or page views are missing or lower than expected | [Visits Are Missing or Lower Than Expected](/docs/differences-in-visits) |
| Traffic or revenue appears as Organic, Other, or Unattributed | [Data Appears as Organic, Other, or Unattributed](/docs/differences-in-unattributed-data) |
| A purchase or order is missing | [Purchases or Orders Are Missing](/docs/purchases-or-orders-are-missing) |
| Spend or impressions are missing | [Spend or Impressions Are Missing](/docs/differences-in-ad-data) |
| Northbeam does not match another platform | [Why Northbeam Differs From Another Platform](/docs/why-northbeam-differs-from-another-platform) |
| An export does not match the dashboard | [Dashboard and Export Data Don't Match](/docs/dashboard-and-export-data-dont-match) |
## Before you troubleshoot
Confirm these details first:
1. **Account:** Are you in the correct Northbeam account?
2. **Date range and timezone:** Are both sources using the same dates and timezone?
3. **View settings:** Are the attribution model, window, accounting mode, filters, and saved view the same?
4. **Scope:** Is the issue affecting all data or only one page, campaign, order, or export?
5. **Timing:** When did it begin, and what changed immediately beforehand?
If you still need help, [submit a Northbeam Support request](https://www.northbeam.io/submit-a-support-ticket). Include the affected dates and specific example URLs, campaigns, orders, or exports.
# Ask your data questions from Claude
Source: https://docs.northbeam.io/docs/use-cases/ask-your-data-from-claude
Connect Northbeam to Claude over MCP
**Best for:** anyone who'd rather ask a question than build a view.
## The steps
Set up the MCP connection.
[Connect Northbeam to Claude →](/docs/connect-northbeam-to-claude)
Answers are only as good as your grasp of the metrics behind them.
[Metrics 101 →](/docs/northbeam-metrics-101)
## What to expect
Ask in plain English; verify anything decision-critical against the dashboard, the same way you would a teammate's summary.
## Related
[Attribution models](/docs/attribution-models) · [Exporting data](/docs/exporting-data)
# Audit your tracking before a big sale
Source: https://docs.northbeam.io/docs/use-cases/audit-tracking-before-a-big-sale
A pre-flight check for BFCM and launches
**Best for:** teams heading into a high-spend period who want to catch tracking problems before the traffic arrives.
## Before you start
Run this a couple of weeks ahead — some fixes (pixel placement, UTM templates) need time to show clean data.
## The checks
Verify the pixel on your landing pages and checkout.
[Troubleshooting pixel tracking →](/docs/guide-to-troubleshooting-pixel-tracking)
Confirm Northbeam UTMs are present and captured on final URLs.
[Checking UTM tracking →](/docs/checking-utm-tracking)
Every ad platform should show connected and syncing.
[Checking platform connections →](/docs/checking-api-connections)
The catch-all diagnostic, if anything above looked off.
[Troubleshooting Northbeam data →](/docs/troubleshooting-tracking-issues)
## What to expect
A clean audit means attribution holds up when volume spikes. Anything you fix here pays off in every report you pull during the sale.
## Related
[Integrations and UTMs](/docs/integrations-and-utms) · [Gclid, Fbclid, and redirects](/docs/gclid-fbclid-redirects)
# Build a weekly performance report
Source: https://docs.northbeam.io/docs/use-cases/build-a-weekly-report
A repeatable reporting workflow
**Best for:** whoever owns the Monday number.
## The steps
Group channels and campaigns the way your team talks about them.
[Manage breakdowns →](/docs/manage-breakdowns)
Pick the model, window, and accounting mode once — and keep them stable week to week.
[Accounting modes →](/docs/accounting-modes)
Compare your numbers against profitability benchmarks.
[Profitability benchmarks →](/docs/profitability-benchmarks)
Pull the tables you need for your deck or sheet.
[Exporting data →](/docs/exporting-data)
## What to expect
A stable frame is what makes week-over-week movement meaningful — change the model or window and you've changed the story.
## Related
[Touchpoints export](/docs/touchpoints-export) · [Subscription analytics](/docs/subscription-analytics)
# Choose an attribution model for the decision
Source: https://docs.northbeam.io/docs/use-cases/choose-an-attribution-model
Match the model to the question you're answering
**Best for:** deciding which model to read before a budget or creative decision.
## Before you start
There is no single correct model — each answers a different question. Know what you're deciding before you pick.
## The steps
Simple models give all credit to one touchpoint; multi-touch models divide it.
[Attribution models →](/docs/attribution-models)
Run the Model Comparison tool to see every model side by side.
[Model Comparison tool →](/docs/what-is-northbeam-model-comparison-tool)
Short windows for fast feedback, long windows for considered purchases.
[Attribution windows →](/docs/attribution-windows)
See exactly how credit allocation changes what each model reports.
[Credit allocation examples →](/docs/credit-allocation-examples)
## What to expect
Comparing against an ad platform? Remember most platforms report on last non-direct touch — pick the same model on both sides before drawing conclusions.
## Related
[Lookback windows](/docs/lookback-windows) · [Metrics 101](/docs/northbeam-metrics-101)
# Compare channels on equal footing
Source: https://docs.northbeam.io/docs/use-cases/compare-channels-fairly
Read click and non-click channels without fooling yourself
**Best for:** budget reviews that span search, social, email, and TV-style channels.
## Before you start
Different channel types produce different signals — a click-heavy channel and a view-heavy channel can't be read with the same glance.
## The steps
Hold all three constant across every channel you're comparing.
[Attribution models →](/docs/attribution-models) · [Attribution windows →](/docs/attribution-windows) · [Accounting modes →](/docs/accounting-modes)
How to interpret channels that don't produce clean click trails.
[Interpreting non-click channels →](/docs/how-do-i-correctly-confidently-interpret-non-click-channels)
Organize channels, campaigns, and ads into comparable groups.
[Manage breakdowns →](/docs/manage-breakdowns)
What counts as a good or bad number in context.
[Good vs. bad numbers →](/docs/what-is-a-good-bad-number-in-northbeam)
## What to expect
The goal isn't identical metrics across channels — it's knowing which differences are measurement artifacts and which are real performance.
## Related
[Organic vs. unattributed](/docs/whats-the-difference-between-organic-vs-unattributed) · [Profitability benchmarks](/docs/profitability-benchmarks)
# Diagnose a ROAS drop
Source: https://docs.northbeam.io/docs/use-cases/diagnose-a-roas-drop
Six checks, in order of likelihood
**Best for:** anyone whose ROAS moved and needs to know whether it's the data or the marketing.
## Before you start
Note which surface you're comparing against (Meta Ads Manager, Google Ads, Shopify) and make sure both sides use a matching [attribution model](/docs/attribution-models) and [attribution window](/docs/attribution-windows) — most gaps close right there.
## The checks
Work downward. Stop when your numbers match.
The most common cause: Northbeam and the platform measure with different models and see different touchpoints.
[Differences in ad performance →](/docs/differences-ad-performance)
Check how and when spend syncs from the platform.
[Spend or impressions are missing →](/docs/differences-in-ad-data)
Confirm what's counted as unattributed vs. organic.
[Data appears as Organic, Other, or Unattributed →](/docs/differences-in-unattributed-data) · [Organic vs. unattributed →](/docs/whats-the-difference-between-organic-vs-unattributed)
How visits and journeys are counted.
[Visits are missing or lower than expected →](/docs/differences-in-visits)
Compare against a Shopify Orders export — not a Shopify report.
[Northbeam vs. Shopify →](/docs/why-doesnt-northbeam-match-my-shopify-reporting)
Platform-reported ROAS vs. multi-touch attribution.
[Why is my FB ROAS lower? →](/docs/why-is-my-fb-roas-so-much-lower-in-northbeam)
## What to expect
Most investigations end at the first or second check. If you walk all six and something still doesn't add up, [submit a support ticket](https://www.northbeam.io/submit-a-support-ticket) with the checks you ran.
## Related
[Attribution models](/docs/attribution-models) · [Attribution windows](/docs/attribution-windows) · [Accounting modes](/docs/accounting-modes)
# Evaluate creative performance
Source: https://docs.northbeam.io/docs/use-cases/evaluate-creative
Find the ads that actually convert
**Best for:** creative and growth teams deciding what to iterate, scale, or kill.
## The steps
Performance by creative, across your channels.
[Creative Analytics →](/docs/creative-analytics)
Same model, window, and accounting mode across every creative you compare.
[Attribution windows →](/docs/attribution-windows)
Low-spend creatives produce noisy numbers — read them accordingly.
[Good vs. bad numbers →](/docs/what-is-a-good-bad-number-in-northbeam)
## What to expect
Creative decisions compound: small, consistent evaluation beats occasional deep dives.
## Related
[Manage breakdowns](/docs/manage-breakdowns) · [Metrics 101](/docs/northbeam-metrics-101)
# Pull Northbeam data into your warehouse
Source: https://docs.northbeam.io/docs/use-cases/pull-data-into-your-warehouse
Data Export API to GCS or S3
**Best for:** data teams joining Northbeam metrics with internal data.
## Before you start
You'll need API credentials from **Settings → API keys**. See [Authentication](/docs/authentication) and [Environments](/docs/environments).
## The steps
What you can export and how the flow works.
[Data Export API →](/docs/northbeam-api-data-export-1)
Export to Google Cloud Storage or Amazon S3.
[GCS export →](/docs/northbeam-api-data-export-gcs-export-1) · [S3 export →](/docs/northbeam-api-data-export-s3-export-1)
Schedule exports within the documented limits.
[Rate limits →](/docs/northbeam-api-data-export-rate-limits-1)
## What to expect
Exports land as files in your bucket on your schedule — from there, loading into your warehouse is standard ELT.
## Related
[Using the API](/docs/using-the-api) · [Errors](/docs/errors)
# Reconcile Northbeam vs. Shopify revenue
Source: https://docs.northbeam.io/docs/use-cases/reconcile-northbeam-vs-shopify
The apples-to-apples comparison method
**Best for:** finance or ops checking Northbeam's revenue and order counts against Shopify.
## Before you start
Small differences between Northbeam and Shopify reports are normal and expected. The only apples-to-apples comparison is an export from your **Shopify Orders page** — not a Shopify report, which applies its own report-only logic.
## The steps
Cash and accrual count the same order on different dates.
[Accounting modes →](/docs/accounting-modes)
Follow the comparison method in the reconciliation guide.
[Northbeam vs. Shopify reporting →](/docs/why-doesnt-northbeam-match-my-shopify-reporting)
Confirm the same order sources are included on both sides.
[Order exclusions →](/docs/8d-configure-northbeam-order-exclusions-optional)
## What to expect
After matching accounting mode, revenue formula, order sources, filters, timezone, and data freshness, remaining differences should be small. If your Orders-page export still doesn't line up, that's when a support ticket is worth it.
## Related
[Case scenario: cash vs. accrual](/docs/case-scenario-cash-vs-accrual) · [Add orders](/docs/add-orders)
# Report across multiple stores or regions
Source: https://docs.northbeam.io/docs/use-cases/report-across-stores
One brand, several storefronts, coherent numbers
**Best for:** brands running more than one storefront, region, or currency.
## The steps
Set up a dashboard per storefront or region.
[Adding a store or dashboard →](/docs/adding-a-store-or-dashboard)
Use configurators to control what each dashboard shows.
[Multi-dashboard setup with configurators →](/docs/multi-dashboard-setup-with-configurators)
Each storefront needs its own complete pixel and UTM setup.
[Quickstart →](/docs/quickstart)
## What to expect
Per-store dashboards keep attribution clean; cross-store comparisons work when every store's tracking is equally complete.
## Related
[Currency](/docs/currency) · [Business information](/docs/business-information)
# Send Northbeam attribution to Meta
Source: https://docs.northbeam.io/docs/use-cases/send-attribution-to-meta
Set up Apex custom attribution
**Best for:** teams who want Meta optimizing against Northbeam's attribution instead of Meta's own.
## The steps
What Apex does and how the integration works.
[Northbeam Apex →](/docs/northbeam-apex)
Turn on the integration for your account.
[Setting up Apex →](/docs/setting-up-apex)
Configure custom attribution at the ad-set level in Meta Ads Manager.
[Meta custom attribution campaign →](/docs/setting-up-a-meta-custom-attribution-campaign)
## What to expect
Check the FAQ for rollout status and common questions.
[Apex FAQs →](/docs/apex-faqs)
## Related
[Tracking for Meta Ads](/docs/setting-up-facebook-ads-tracking)
# Validate a channel with an incrementality test
Source: https://docs.northbeam.io/docs/use-cases/validate-with-incrementality
Measure causal lift, not just credited revenue
**Best for:** confirming whether a channel actually causes revenue before scaling or cutting it.
## Before you start
Attribution measures correlation. If the question is "would these customers have bought anyway?", you need an experiment.
## The steps
Test group vs. holdout, and what incremental lift means.
[Incrementality →](/docs/incrementality)
High-spend channels with uncertain attribution (retargeting is the classic case) benefit most.
Use lift results to calibrate how you read MTA and MMM for that channel.
[Mixed Media Modeling →](/docs/mixed-media-modeling)
## What to expect
Tests run for a bounded period and produce a lift estimate you can act on — feeding back into how much you trust each channel's attributed numbers.
## Related
[MTA methodology](/docs/what-is-northbeam-mta-methodology) · [Attribution models](/docs/attribution-models)
# Using the API
Source: https://docs.northbeam.io/docs/using-the-api
Guidance for Using the Northbeam Orders API
## Testing and Development
We offer a testing and development endpoint to give the API a test drive in your own internal testing processes. Each Northbeam instance allows access to a test API with a Base URL `https://api-uat.northbeam.io`
## Production Use
The production API base URL is `https://api.northbeam.io`. Orders sent to this base URL will be used for ad attribution (MTA) and predictive analytics (MMM). See the [API Reference](/reference/post_orders-1) for the exact endpoint paths and payloads.
## Using the API
Head over to our [API Reference](/reference/post_orders-1) to give the API a go! No need to be a full blown developer, the reference features a place where you can insert your API keys and populate an example payload with some sample data (use our example values if unsure) to make an API call to our development or production endpoints. The Reference page also features example code for Shell, Ruby, PHP, Python and my other languages.
# What is a good/bad number in Northbeam?
Source: https://docs.northbeam.io/docs/what-is-a-good-bad-number-in-northbeam
How do I correctly measure my performance?
Whether something is a "good" or "bad" number is entirely based on how your **own** data behaves, not how a platform chooses to represent it. If your performance looks better or worse compared to in-platform ad metrics, know that this is completely **normal**!
Northbeam factionalizes revenue and transactions across all marketing touchpoints to give you the most accurate, multi-channel view of performance data. This approach leads to data that looks materially different from what you are used to seeing in Meta, Google, or other platform dashboards.
It may feel like a shift at first, but this is a more honest, strategic way to make decisions. You can embrace this new world of data by relying on your [Profitability Benchmarks](/docs/profitability-benchmarks). This is tailored to your brand and built to help you scale with confidence.
# What is Northbeam?
Source: https://docs.northbeam.io/docs/what-is-northbeam
How Northbeam works and what you need to get started.
At its core, Northbeam is a data company. Northbeam is a source of truth that makes your advertising profitable by:
* Utilizing first-party data to provide better signals across marketing funnels
* Operating in an unbiased, conservative way to understand your various channels
* Functioning on an indefinite attribution window so you can see your touchpoint data over time
Let's go ahead and get started.
Get acquainted with the different topics below and turbocharge your marketing capabilities.
You'll be able to best leverage Northbeam by getting familiar with the following concepts:
1. [Accounting Modes](/docs/accounting-modes): Northbeam offers two different settings to determine when conversion and revenue credit are given:
1. Cash Snapshot
2. Accrual Performance
2. [Attribution Models](/docs/attribution-models): Northbeam provides six different attribution models to assign credit for conversion events to relevant marketing touchpoints.
1. We analyze which parts of your marketing funnels and customer journeys drive the most impact and revenue.
Other useful information in our **Northbeam Academy**:
1. [Attribution Windows](/docs/attribution-windows): the length of time in which a touchpoint receives credit for a conversion.
1. Attribution Windows are only available using the **Accrual Performance Mode**
2. [Northbeam Metrics 101](/docs/northbeam-metrics-101): the metrics that we provide in our platform such as Attributed Revenue, Transactions (also known as Conversions), Impressions, and Views.
***
### Why do my in-platform metrics look different from Northbeam?
This is one of the most common questions we get — and the short answer is: **the difference is intentional.**
Ad platforms like Meta, Google, and TikTok each attribute conversions in silos. When a customer clicks a Facebook ad, then a Google ad, then converts — both platforms claim full credit. Add up all your in-platform revenue and it will far exceed your actuals. That's the problem Northbeam solves.
Northbeam tracks touchpoints across every channel and distributes credit across the full journey using our default Clicks-Only attribution model. Lower numbers in Northbeam aren't a red flag — they're a more honest picture.
📺 Watch this quick overview:
**TL;DR:**
Northbeam and platform data are built on disparate technology stacks designed for separate goals, and our teams have contrasting philosophies (and end-goals) when it comes to attributing revenue to different marketing touchpoints.
**Why?** Our end-goal goal is to provide you with independent and unbiased data.
* This means that our calculations may result in metrics different than what you see in-platform. We believe that our metrics objectively portray what is actually going on in a customer’s journey before they ultimately convert.
* Differences in reported data are expected. You can see these differences even between your platforms (Facebook, Google, TikTok, Pinterest, Klaviyo, etc).
Northbeam’s aims to give you the most complete and actionable customer journey insights by assigning appropriate credit to any and all marketing touchpoints. Our data will look different to what you see in-platform, and that's a good thing.
***
### How do I know my tracking is working?
Revenue isn't the right signal — it will always look lower in Northbeam because credit is split across touchpoints. **Check Visits instead.**
A visit is recorded when two things happen: the pixel fires on a page load, and UTMs are intact to tie the session to a channel. Compare Northbeam visits against platform-reported clicks — we call this the **Visit-to-Click (VTC)** rate. A healthy range is **30–50%**.
If VTC is well below 30%, first verify UTMs are surviving end-to-end by testing your links manually. If UTMs look fine, check **GA4 sessions** — they're the most accurate external benchmark. If Northbeam and GA4 roughly align but both diverge from platform clicks, the platform is overcounting. If GA4 is significantly higher than Northbeam, [contact support](https://www.northbeam.io/submit-a-support-ticket).
# What is Northbeam's Model Comparison Tool?
Source: https://docs.northbeam.io/docs/what-is-northbeam-model-comparison-tool
How can it measure MTA models as well as data from outside of Northbeam?
Northbeam's [Model Comparison](https://dashboard.northbeam.io/model-comparison) tool is used to evaluate performance more accurately than traditional ad platform reporting.
# Overview Walkthrough Video
## TL;DR
**What is Model Comparison?**
* A tool that allows user to compare Northbeam attribution models (mainly [Clicks Only](/docs/attribution-models#clicks-only) vs. [Last Non-Direct Touch](/docs/attribution-models#last-touch-and-last-non-direct-touch)) to understand how revenue and transactions shift across models.
**Why is this important?**
* These differences will help you spot which campaigns are undervalued or overvalued by the platforms themselves, so you can shift your focus for better results.
**Here is an advanced tip:**
* Export data to CSV and overlay platform data (eg., Google Ads) to analyze differences more deeply in a spreadsheet.
Using our Model Comparison Tools allows you to uncover what's really driving performance with Northbeam's Clicks-Only attribution model. This tool provides an unbiased view of campaign effectiveness compared to other Last-Click models from in-platform reporting.
# What is Northbeam's MTA Methodology?
Source: https://docs.northbeam.io/docs/what-is-northbeam-mta-methodology
What makes Northbeam's MTA unique?
Northbeam is an unbiased multi-touch attribution (MTA) solution. We are not incentivized to attribute to any specific channel, and that is the key difference from most ad platforms.
Here is how we do it:
* Rely on first-party data
* Fractionalizes transactions and revenue across all relevant touchpoints, and
* Show which marketing activities are driving profitable results.
To give you a better understanding of our methodology, here is an **example** of a \$100 purchase journey compared between Other Platforms and Northbeam:
* Most traditional platform-based attribution (like Google, Pinterest, or Facebook) uses Last-Click Attribution where they will independently claim full credit for a single transaction. So here, you can see that Shopify has attributed the credit to Facebook:
* In the image below, Northbeam applies the **Linear Attribution** using a **Click-Based** model in **Accrual Performance** Accounting Mode. Northbeam provides a balanced view of performance that is tracked across all touchpoints:
Our methodology is important to understand because we're focused on first-party data that provides an accurate view of performance. This instills confidence in your data when making decisions, as well as insights into which channels are working to drive conversions.
# What To Expect During Implementation
Source: https://docs.northbeam.io/docs/what-to-expect-during-implementation
Standard Setup
The steps below apply to a **standard setup**: one dashboard, one domain, per brand.
***
If your configuration differs (e.g., one brand with multiple dashboards or multiple domains), additional steps will be required and the process may vary.
***
Below is a practical overview of the three parts of your Northbeam implementation:
1. **Account Setup** – Getting your dashboard, store, tracking, and ad accounts connected so data can flow into Northbeam.
2. **Data Validation** – This is where we double-check that everything is set up correctly. Thanks for being patient — our team will reach out with quick questions and updates as we confirm your data is accurate.
3. **Using the Platform** – Once validation is complete, you’ll learn how to use Northbeam and, if included, work with your Media Strategy team.
***
## 1. Account Setup
This is where you connect your store, place tracking, and link your ad accounts so Northbeam can start collecting data.
* **Dashboard Creation**
* Our team will create your account and provide access to your team.
* **Set up your DNS A-Record**
* Enables first-party tracking. Without it, pixel and event tracking won’t function correctly.
* *Guide: /docs/link-dns*
* **Pixel and Event Setup**
* Add the Northbeam Pixel site-wide and configure conversion tracking (e.g., Purchase Event).
* *Guide: /docs/add-pixel*
* **Upload Order Data**
* **Shopify**: Install our native app.
* *Guide: /docs/shopify-order-sync*
* **Non-Shopify**: Send orders to Northbeam via the Orders API.
* *Guide: /docs/orders-api/*
* *API Ref: /reference/orders*
* **Connect your Ad Accounts**
* Ad account connections are *user-based*. The user connecting must have *admin access* to the account.
* If that user loses admin access, the account will disconnect from Northbeam. An admin will need to reconnect or restore access.
* **Agencies**: Best practice is to have someone from the brand side connect accounts.
* **Multiple Ad Accounts**: The connecting user must have admin access to all accounts.
* **Multiple Google Ads Accounts:** All accounts should be under a Parent MCC, and the connecting user must be an admin on the MCC.
* **TikTok Shops and Meta Shops Setup**
* Orders from TikTok Shop and Meta Shop must flow into your source of truth (Shopify or your custom backend).
* **Shopify Stores**: Make sure TikTok and Meta Shop orders are syncing into your Shopify account so they are included with the rest of your Shopify orders sent to Northbeam.
* **Custom Stores**: Send TikTok and Meta Shop orders to Northbeam via the Orders API, using a unique order tag to distinguish them from other order sources.
* This setup is especially important for **TikTok GMV Max campaigns**, since these transactions are processed through TikTok Shop.
* *Guide: /docs/tracking-for-shops#/*
* **Attach UTM Parameters**
* Required for accurate reporting and attribution — see note below.
**UTM Parameters Are Required**
Northbeam requires specific UTM parameters for proper tracking.
* Adding UTMs may reset ads into a learning phase, but we strongly recommend implementing them immediately.
* For plans that include data reviews and walkthroughs, these will be delayed until UTMs are attached so that we’re working with fully healthy data.
* *Bottom line: The longer UTMs are delayed, the longer your implementation will take.*
* **Additional Spend Data (Optional)**
* Use Custom Spend Sheets or the Spend API for channels without spend integrations (e.g., email, influencer, affiliate, partners).
* *Guide: /docs/add-spend/*
* **Typical Timelines**
* Shopify brands: **2–4 weeks** (light dev work).
* Non-Shopify brands: **4–8 weeks** (depends on dev resources).
* Timeline varies based on the availability of your dev team.
***
## 2. Data Validation
At this stage, we confirm that everything is flowing correctly and matches your source of truth. Expect communication from us with updates and follow-ups.
* **Activation & Validation Period**
* After setup, our team validates your data to confirm orders, pixels, UTMs, and integrations are healthy. We require at least 3 fully tracked days of data before validating to ensure a large enough sample size.
* *During this period, our team checks the following:*
* **Orders Data** – Confirm we’re receiving orders through the Shopify App or Orders API.
* **Pixel Tracking Rate** – We validate that conversion events fire for online orders. The target is 85% of all web orders, with some loss expected from cookie blockers. If a cookie banner blocks pixel events, please provide the acceptance rate, as this will adjust the target.
* **UTMs** – We'll confirm UTM coverage across all integrated channels (e.g., Meta, Google, TikTok, Pinterest, Snapchat).
* **Integrations** – We ensure all ad accounts remain connected with valid permissions.
* **Revenue Reconciliation**
* Northbeam default: `Gross Sales + Shipping + Taxes – Discounts`
***
## 3. Using the Platform (and Media Strategy, if applicable)
Once your data is validated, your implementation and support will depend on your plan.
| Feature | Professional & Enterprise | Starter |
| - | :-: | :-: |
| **Platform walkthrough & training** | ✅ Guided session covering Sales and Overview pages, saving views, and using attribution/accounting modes | ❌ |
| **Customer Success Manager (CSM)** | ✅ Setup, troubleshooting, and operations | ❌ |
| **Support team** | ✅ Ticket Support via [Ticket Submission Form](https://www.northbeam.io/submit-a-support-ticket) | ✅ Ticket Support via [Ticket Submission Form](https://www.northbeam.io/submit-a-support-ticket) |
| **Media Strategy Team** | ✅ Optimization guidance, budget strategy, recurring Data Reviews | ❌ |
| **First Data Review** | ✅ Scheduled session with strategist, leave-behinds (agendas, saved views, best practices), and follow-ups | ❌ |
| **Self-service resources** | ✅ Documentation and training materials | ✅ Documentation and training materials |
# What's the difference between Organic vs Unattributed?
Source: https://docs.northbeam.io/docs/whats-the-difference-between-organic-vs-unattributed
**Organic** traffic typically refers to **direct visits to your site**, such as typing your URL, clicking a bookmark, or visiting through an untagged link. While this traffic can be valuable, it follows specific attribution rules in Northbeam:
* **No credit** if any **upper-funne**l touchpoints (like Paid Ads) exist in the customer's journey
* It **can receive credit if:**
* It is the **only** touchpoint in the journey or
* Other touchpoints are **lower-funnel** (eg, Retargeting Ads).
On the other hand, **Unattributed** refers to website traffic or purchases that cannot be linked to a specific marketing channel, campaign, or traffic source. This means that Northbeam knows that a conversion happened but does not have enough data to determine what drove it.
Here are the common causes of Unattributed data:
* **Recurring subscription** shipments that began before Northbeam tracking
* **Manually created orders** (e.g., Draft orders, Wholesale orders).
* **Third-party checkouts or marketplaces** (e.g. Walmart, CheckoutChamp, Tapcart).
Both Organic and Unattributed data play a role in understanding the complete customer's journey. Northbeam is built to track and attribute as much as possible using first-party data, but certain cases involving legacy systems or external platforms can result in gaps.
As mentioned previously, we monitor the Unattributed data threshold for each account and work closely with you to identify, explain, and minimize these blind spots whenever possible.
# Why Doesn't Northbeam Match My Shopify Reporting?
Source: https://docs.northbeam.io/docs/why-doesnt-northbeam-match-my-shopify-reporting
Learn why Northbeam Total Revenue and Orders may differ from Shopify and how to compare the two using an apples-to-apples Shopify Orders export.
When comparing Northbeam's Total Revenue and Orders to Shopify, it's common to see differences in the data. Use this guide to understand why, and how to make a true apples-to-apples comparison.
**This guide should answer the following question:**
* *"Why is my total revenue/orders in Northbeam different than what Shopify shows?"*
**Start here: Northbeam and Shopify *reports* will rarely match exactly, and that's expected.**
Northbeam pulls your order data directly from **Shopify's API**.
Shopify's standard reports, such as Total Sales, Net Sales, GMV, and Analytics dashboards, apply internal calculations and transformations on top of raw order data. These transformations are **not exposed through the API** and cannot be fully replicated by Northbeam or any third-party platform.
A few examples of report-only logic:
* Gift card purchases are excluded from sales until redeemed
* Deleted and test orders are removed entirely
* Order edits or exchanges can be counted differently
* Refunds may be reported on the date the refund was processed, rather than the original order date
**What this means in practice:**
* Small differences, typically low single-digit %, between Northbeam and Shopify reports are normal.
* **The only apples-to-apples comparison is an export from your [Shopify Orders page](https://admin.shopify.com/orders)**, not a Shopify report.
* If you've matched accounting mode, revenue formula, order sources, filters, timezone, and data freshness, all covered below, and your **Orders page export** still does not line up, that's when it's worth submitting a ticket.
**How each platform produces its number:**
| Source | What the number is based on | Notes |
| :- | :- | :- |
| Northbeam | Raw orders from Shopify's API | Server-side order data, plus your configured revenue formula. |
| Shopify Orders Page | Raw order data | Your **Orders page export** should align closely with Northbeam when using the same revenue formula and filters. |
| Shopify Reports / Analytics | Raw orders **+ report-only transformations** | Applies additional logic on top of raw orders. **Will not fully match Northbeam**. See the common reasons below. |
**My revenue still isn't lining up. What's going on?**
Check these in order:
1. [Accounting Mode](#1-accounting-mode)
2. [Revenue Calculation](#2-revenue-calculation)
3. [Omitted or Additional Order Sources](#3-omitted-or-additional-order-sources)
4. [Orders Labeled as Excluded](#4-orders-labeled-as-excluded)
5. [Timezone](#5-timezone)
6. [Data Freshness & Recent Dates](#6-data-freshness--recent-dates)
***
## 1. Accounting Mode
Be sure to toggle to **Cash** accounting mode. The default view is Accrual.
* **Cash:** revenue is reported on the day the order was placed. **Use this mode when comparing against Shopify**, since Shopify also reports based on time of purchase.
* **Accrual:** revenue is reported on the day(s) the contributory touchpoint(s) occurred.
* *Example: If 3 touchpoints led to a sale, revenue is divided across those touchpoints. If the touchpoints happened on different days, revenue may be split across multiple dates.*
**Tip:** The **Orders page** always shows revenue and orders in Cash terms, so it can be a quicker comparison point than toggling modes on the Overview or Sales pages.
Learn more about our [Accounting Modes](/docs/accounting-modes).
***
## 2. Revenue Calculation
Northbeam calculates revenue differently than Shopify's "Total Sales":
| Platform | Revenue Calculation |
| :- | :- |
| Northbeam, default | Gross Sales + Shipping + Taxes - Discounts |
| Shopify, "Total Sales" | Gross Sales + Shipping + Taxes - Discounts - Refunds |
The key difference is that **Northbeam does not deduct refunds by default**. However, your Northbeam revenue formula can be customized to:
* Exclude Shipping
* Exclude Taxes
* Deduct Refunds
* Add order-level Discounts back into the topline
To request a change, [submit an inquiry here](https://www.northbeam.io/submit-a-support-ticket).
**No single Shopify metric matches Northbeam's default.** Always confirm which Shopify metric you're comparing against:
| Shopify Metric | Formula |
| :- | :- |
| **Gross Sales** | Gross - Discounts |
| **Net Sales** | Gross - Discounts - Refunds *(excludes shipping & taxes)* |
| **Total Sales** | Gross + Shipping + Taxes - Discounts - Refunds |
*Note: In the Shopify Orders export, "Gross Sales" appears as the ****Subtotal**** column.*
### Refunds
Refunds are an order value difference, not an order source difference.
By default, Northbeam does not deduct refunds from revenue. If you want Northbeam revenue to align more closely with Shopify's "Total Sales," you may need to update your revenue formula to deduct refunds.
**Important to Know**
**If refunds are deducted, historical revenue data will update when refunds are processed.**
For example, if an order is placed on January 1 but refunded on February 1, revenue for January 1 will update on February 1 to reflect the refund.
Even when refunds are deducted, Northbeam and Shopify reports may date refunds differently:
* **Northbeam:** Because we use Shopify's API, refunds are tied to the *initial order date*.
* Example: If an order was placed on January 1 and refunded on February 15, the refund is recorded under January 1.
* **Shopify Reports:** In Shopify's standard reports, refunds are tied to the *refund processed date*.
* Example: In the same scenario, the refund is reported on February 15.
This means a refund can affect different dates depending on which platform you're viewing. Over a date range that includes the order but not the refund, or vice versa, totals can diverge. The gap grows with refund volume.
**Which Shopify data source should I compare to Northbeam?**
**Only an export from the Shopify Orders page will align with Northbeam. Shopify reports will not match.**
Shopify's standard reports, such as Total Sales, Net Sales, and GMV, apply internal calculations and transformations that are not available through Shopify's API. Because of this, discrepancies may remain even if you adjust for refunds, taxes, or shipping.
**To export your Orders page:**
1. Log into Shopify
2. Click **Orders**
3. Click **Export**
*When cross-referencing, use the "Order Name" field to match orders in Northbeam.*
***
## 3. Omitted or Additional Order Sources
Some discrepancies happen because Northbeam and Shopify are not looking at the same set of orders. This is different from a revenue formula issue. In these cases, the order itself may be included in one system but not the other.
### Shopify POS and In-Person Orders
By default, Northbeam ingests your **online** Shopify orders. **In-person orders processed through Shopify POS are not included by default. Typically, these are orders where Sales Channel is POS.**
If your store processes in-person or retail transactions through Shopify POS, those orders may appear in Shopify but **not in Northbeam**, making Northbeam lower.
If this applies to your store and you'd like POS orders included, [submit an inquiry here](https://www.northbeam.io/submit-a-support-ticket) and our team can enable POS ingestion.
### Non-Shopify Revenue in Northbeam
Northbeam's Total Revenue includes **all connected revenue sources**, not just Shopify. If you've connected Amazon Seller Central or another sales channel, Northbeam may be higher than Shopify by the value of that additional revenue.
To isolate Shopify revenue in Northbeam:
1. On the [Sales page](https://dashboard.northbeam.io/sales), click **Add Filters**
1. Click **Tile Settings**
2. Click **Add Filters**
3. Filter to your Shopify platform and click **Apply**
2. On the [Overview page](https://dashboard.northbeam.io/overview), click the **3 dots (...)** in any tile
1. Click **Tile Settings**
2. Click **Add Filters**
3. Filter to your Shopify platform and click **Apply**
***
## 4. Orders Labeled as Excluded
Northbeam can label certain orders as **Excluded** based on order tags or other configured rules. However, these orders are not always automatically removed from every Northbeam view.
In many cases, excluded orders are still visible in Northbeam and are simply labeled as **Excluded**. A user would need to intentionally filter them out for those orders to be omitted from the view they are looking at.
Because of this, excluded order tags are usually **not the most common reason** for a Northbeam vs. Shopify discrepancy, but they are worth checking if the numbers still do not line up.
Common examples of orders that may be labeled as excluded include:
* Phone orders and customer-service-placed orders
* Wholesale / B2B orders
* Influencer gifting, replacements, and warranty orders
* 3rd-party retailer orders, such as Amazon, Walmart, Macy's, etc.
These rules are configured either during onboarding or afterward in your dashboard.
**To review your current exclusions:**
1. Open [Excluded Orders](https://dashboard.northbeam.io/settings/excluded-orders).
2. Find the **Exclude Orders by Tag** section
3. Review the list of excluded order tags
If an order tag is listed here, orders with that tag may appear in Northbeam with an **Excluded** label. If you or another user filters excluded orders out of your view, Northbeam may appear lower than Shopify by the value of those filtered orders.
***
## 5. Timezone
Minor differences are often caused by a mismatch between your Northbeam dashboard timezone and your Shopify store timezone. Orders placed near midnight may fall on different days in each system.
To see your Northbeam timezone:
1. Open [Profile](https://dashboard.northbeam.io/settings/profile).
To check your Shopify store timezone, go to **Settings → General → Store details**.
***
## 6. Data Freshness & Recent Dates
Northbeam processes order data on a schedule, so **the most recent day or two may not be finalized**. Comparing today's or yesterday's numbers against Shopify, which updates in real time, may show a temporary gap.
For the most accurate comparison:
* Compare a **closed date range** that ended at least 1-2 days ago.
* Confirm data has processed by hovering over **Last Processed**. See Troubleshooting below.
***
# Troubleshooting
If you've worked through the sections above and still suspect an issue, follow these steps.
## Step 1: Check your Connection
Hover over **Last Processed** to identify broken connections. Under **Revenue**, you'll see the connection for your **Shopify** revenue source. A broken connection displays a red error message.
## Step 2: Compare Northbeam Orders to your Shopify Orders
If the connection looks fine, do an order-level comparison to identify missing orders, extra orders, or revenue discrepancies. You do not need to pull every order. A small subset, such as a single day, is usually enough.
To export your orders from Northbeam:
1. Open [Orders](https://dashboard.northbeam.io/orders).
2. Filter for **E-Commerce Platform = Shopify**
3. Click **Export Data**
Cross-reference against your Shopify **Orders page export**, not Reports or Analytics, using the order number as the identifier. Northbeam's **Order Value** reflects your active revenue formula, so rebuild the equivalent value from the Shopify export columns below and compare:
| Northbeam Metric | Shopify Orders Export Column |
| :- | :- |
| Order Number | **Name** |
| Gross Sales | **Subtotal** |
| Shipping | **Shipping** |
| Taxes | **Taxes** |
| Discounts | **Discount Amount** |
| Refund | **Refunded Amount** |
Apply your revenue formula line-by-line. See [Revenue Calculation](#2-revenue-calculation), sum it, and compare to Northbeam's Order Value. They should match.
# Why is my FB ROAS so much lower in Northbeam?
Source: https://docs.northbeam.io/docs/why-is-my-fb-roas-so-much-lower-in-northbeam
Business metrics will almost always be lower in Northbeam than in-platform, due to the accounting mode, attribution model, and look-back window used.
Below is a real (anonymized) example of a current Northbeam client (accrual, Clicks-Only, 1-day lookback). The Northbeam-reported
* 1-day ROAS is 1.4, while
* Facebook-reported 1-day ROAS is 4.2
The delta is unique to your business and empowers directional decision-making. A low number in Northbeam does not necessarily mean low performance.
What’s important here is correlating your platform/ ad set/ ad level data to your top-line business performance over a given period to determine whether the numbers are “good” or “bad”.
We'd recommend Profitability Benchmarks to understand [what is a good/bad number](/docs/what-is-a-good-bad-number-in-northbeam).
# Why Northbeam Differs From Another Platform
Source: https://docs.northbeam.io/docs/why-northbeam-differs-from-another-platform
Make an apples-to-apples comparison before investigating a reporting discrepancy.
Different totals do not always mean data is missing. First confirm that both sources measure the same thing using the same settings.
## Match the comparison
Use the same:
1. **Date range and timezone**
2. **Metric definition**
3. **Filters and included accounts**
4. **Attribution model and window**
5. **Accounting mode**
6. **Data-generation time**
Then identify the metric that differs.
| Difference | Best next step |
| :- | :- |
| Visits or sessions | [Visits Are Missing or Lower Than Expected](/docs/differences-in-visits) |
| Ad spend or impressions | [Spend or Impressions Are Missing](/docs/differences-in-ad-data) |
| Shopify orders or revenue | [Why Doesn't Northbeam Match My Shopify Reporting?](/docs/why-doesnt-northbeam-match-my-shopify-reporting) |
| Attributed revenue or conversions | Review [Attribution Models](/docs/attribution-models), [Attribution Windows](/docs/attribution-windows), and [Accounting Modes](/docs/accounting-modes). |
| New versus returning customers | Review [First-Time and Returning Data](/docs/new-vs-returning-data-1). |
| Dashboard versus exported data | [Dashboard and Export Data Don't Match](/docs/dashboard-and-export-data-dont-match) |
Ad platforms generally report using their own attribution rules. Northbeam applies the model, window, and accounting mode selected in Northbeam, so attributed results are not expected to match automatically.
If the underlying visits, orders, and spend are present, investigate reporting settings before treating the difference as a tracking failure.
# Interpreting your results
Source: https://docs.northbeam.io/interpreting-your-results
How to read an incrementality test result and turn it into a decision
Once a test finishes collecting data, the results page summarizes what happened in the holdout and what it implies about the channel's real contribution. Reading it well means separating the statistical question (is the effect real?) from the business question (is the effect worth the spend?), and knowing which parts of the summary answer which.
## What it is
A results readout has three layers: a **headline verdict** that classifies the outcome, a set of **key metrics** that quantify it, and a **confidence interval** that bounds it. Together they describe the range of true lift consistent with what the test observed.
The verdict is one of **Significant lift**, **No detectable lift**, or **Inconclusive**. Each is a claim about signal versus noise, not about profitability. A significant result means the exposed and holdout groups differ by more than chance would explain; it does not, on its own, mean the channel clears your efficiency bar.
ScopeApplies to a single channel, in a single test window, at the holdout size the test was designed around. Results do not generalize across channels, geographies, or seasons without re-testing.
## How it works
01The exposed and holdout groups accumulate conversions over the life of the test.
02The gap between them is measured as **incremental conversions** and **incremental revenue**, then expressed as **lift %**, **iROAS**, and **iCAC**.
03A **confidence interval** and **p-value** describe how precisely that gap is known, and the verdict follows from where the interval sits relative to zero.
The time series chart plots cumulative conversions for both groups. Two properties matter: the pre-period should be flat (the lines tracking each other before day zero), and the gap should widen steadily rather than appear on a single day. A flat pre-period confirms balanced assignment; a gradual widening confirms the effect looks like media rather than a promotion, outage, or tracking change.
### Key metrics
| Metric | What it means | How to use it |
| :- | :- | :- |
| Incremental conversions | Orders that would not have happened without the channel | The numerator for every efficiency calculation below |
| Incremental revenue | Revenue attributable to those conversions | Compare against spend in the test window |
| Lift % | Relative difference between exposed and holdout groups | Use for comparing across tests of different sizes |
| iROAS | Incremental revenue divided by incremental spend | The number to hold against your ROAS target |
| iCAC | Incremental spend divided by incremental conversions | Useful when your goal is new customer acquisition |
| Confidence interval | The plausible range for true lift | Plan against the lower bound, not the point estimate |
| p-value | Probability of seeing this result if there were no true lift | Below 0.05 is the conventional threshold |
## How it relates to the verdict
The three verdicts correspond to where the confidence interval sits relative to zero.
| | Significant lift | No detectable lift | Inconclusive |
| - | - | - | - |
| **What the interval looks like** | Entirely above zero | Narrow and centered near zero | Wide, spanning zero |
| **What it means** | The channel produced a measurable effect | The channel did not move conversions meaningfully | The test could not tell signal from noise |
| **What to do next** | Compare iROAS against your marginal target | Reduce or reallocate spend | Redesign, usually with a larger holdout |
An interval entirely below zero is a fourth case: the exposed group underperformed. Before treating that as evidence the channel is harmful, check for assignment or delivery issues.
### When a result is inconclusive
Inconclusive is information, not failure. The usual causes:
1. **Insufficient power.** The holdout was too small, or the window too short, to detect the effect size you care about.
2. **Holdout contamination.** Users in the holdout were reached anyway, through a different placement, a retargeting audience, or cross-device delivery.
3. **Overlapping activity.** A promotion, seasonal spike, or another test running in the same window absorbed the signal.
4. **Effect below the detection floor.** The channel may work, just at a magnitude smaller than the test was designed to see.
Adjust the design before you extend the duration. A larger holdout usually buys more power than extra weeks.
## Why it matters
**A result is a range, not a number.** The point estimate sits in the middle of a confidence interval, and the honest planning number is the lower bound. Teams that treat the point estimate as precise systematically over-forecast the return on the channels they measure.
**One test describes one moment.** Incrementality shifts with saturation, creative, and seasonality. A result from six months ago describes six months ago; ongoing decisions need a re-test cadence, not a single verdict frozen in time.
**Statistical significance is not a spend decision.** A significant lift still has to clear your marginal efficiency target, not your blended average. The results page tells you whether the channel worked; your target tells you whether it worked enough.
### Common pitfalls
**Reading the point estimate as precise.** Plan against the lower bound of the interval.
**Comparing lift across differently designed tests.** Different holdout sizes, geographies, and windows produce numbers that are not directly comparable.
**Stopping early on a promising trend.** Peeking and stopping when results look good inflates false positives. Let the test reach its planned end.
**Treating one test as permanent truth.** Re-test on a cadence to track drift.
## In one sentence
A test result is the range of true lift consistent with what you observed; read the lower bound, compare it to your marginal target, and re-test on a cadence.
# Add aliases to existing orders
Source: https://docs.northbeam.io/reference/addorderaliases
openapi/orders-v2.json POST /orders/aliases
Additively attach alternate order IDs to existing orders. Aliases that already
exist are silently ignored. Orders must already exist.
Additively attach alternate order IDs to existing orders. Aliases that already
exist are silently ignored. Orders must already exist.
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
| `Content-Type` required | `application/json` |
## Body
Field
Type
Description
aliasesrequired
object\[]
Maximum array length: 2500
Field
Type
Description
Example
order\_idrequired
string
The order\_id to attach this alias to Minimum string length: 1
typerequired
string
Alias type identifier Minimum string length: 1
"shopify\_checkout\_token"
idrequired
string
The alternate order ID value Minimum string length: 1
"abc-xyz-123"
## Responses
| Status | Description |
| :- | :- |
| `200` | Aliases accepted |
| `400` | Validation error |
| `404` | One or more order\_ids not found |
# Delete a spend record
Source: https://docs.northbeam.io/reference/delete_spend
openapi/spend-v1.json DELETE /spend
Delete a previously submitted daily spend record, matched on platform and the campaign/adset/ad hierarchy plus date.
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
| `Content-Type` required | `application/json` |
## Body
Field
Type
Description
datarequired
object
Field
Type
Description
Example
daterequired
string (date)
The date of spend entry to delete, required
"1970-01-01"
platform\_account\_id
string
The Ad Platform Account ID to delete, required Default: ""
"12345"
campaign\_idrequired
string
The Ad Platform's Campaign ID to delete, required
"12345"
adset\_id
string
The Ad Platform's Adset ID to delete, defaults to '' if empty Default: ""
"12345"
ad\_id
string
The Ad Platform's Ad ID to delete, defaults to '' if empty Default: ""
"12345"
## Responses
| Status | Description |
| :- | :- |
| `200` | The spend record was successfully deleted. |
| `401` | Authentication failed. |
| `422` | The request body is invalid. |
| `4XX` | An unexpected error occurred. |
| `5XX` | An unexpected error occurred. |
### `200` response body
Field
Type
Description
datarequired
object\[]
Field
Type
Description
Example
daterequired
string (date)
The date of spend entry to upsert, required
"1970-01-01"
platform\_account\_id
string
The Ad Platform Account ID to upsert, used for segregating ad objects per ad platform account Default: ""
"12345"
platform\_namerequired
string
The Ad Platform Name to upsert, required
"Facebook"
campaign\_idrequired
string
The Ad Platform's Campaign ID (utm\_campaign, if known) to upsert, required
"12345"
campaign\_namerequired
string
The Ad Platform Campaign Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as campaign\_id
"Banana Festival Awareness Campaign"
adset\_id
string
The Ad Platform's Adset ID (utm\_term, if known) to upsert, defaults to '' if empty (not all platforms support adsets) Default: ""
"12345"
adset\_name
string
The Ad Platform Adset Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset\_id - defaults to '' if empty Default: ""
"Banana Adset"
ad\_id
string
The Ad Platform's Ad ID (utm\_content, if known) to upsert, defaults to '' if empty (not all platforms support ads) Default: ""
"12345"
ad\_name
string
The Ad Platform Ad Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset\_id - defaults to '' if empty Default: ""
"Banana Ad"
spendrequired
number
Amount (in currency) spent on ad object to upsert, defaults to 0 if empty Required range: x >= 0
"123"
spend\_currencyrequired
string
The Currency of the Spend per ISO 4217 to upsert, required Required string length: 3 - 3
"USD"
impressions
number
The amount of impressions the ad object received on a given date, defaults to 0 if empty Required range: x >= 0 Default: 0
299
clicks
number
The amount of clicks the ad object received on a given date, defaults to 0 if empty Required range: x >= 0 Default: 0
0
created\_atrequired
string (date-time)
updated\_atrequired
string (date-time)
### `401` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
### `422` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
### `4XX` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
### `5XX` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
# Delete a spend record (hourly)
Source: https://docs.northbeam.io/reference/delete_spend-hourly
openapi/spend-v1.json DELETE /spend_hourly
Delete a previously submitted hourly spend record. Same matching behavior as the daily endpoint, at hourly granularity.
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
| `Content-Type` required | `application/json` |
## Body
Field
Type
Description
datarequired
object
Field
Type
Description
Example
hour\_start\_isorequired
string (date-time)
The date of spend entry to delete, required
"1970-01-01T00:00:00-0000"
platform\_account\_id
string
The Ad Platform Account ID to delete, required Default: ""
"12345"
campaign\_idrequired
string
The Ad Platform's Campaign ID to delete, required
"12345"
adset\_id
string
The Ad Platform's Adset ID to delete, defaults to '' if empty Default: ""
"12345"
ad\_id
string
The Ad Platform's Ad ID to delete, defaults to '' if empty Default: ""
"12345"
## Responses
| Status | Description |
| :- | :- |
| `200` | The spend record was successfully deleted. |
| `401` | Authentication failed. |
| `422` | The request body is invalid. |
| `4XX` | An unexpected error occurred. |
| `5XX` | An unexpected error occurred. |
### `200` response body
Field
Type
Description
datarequired
object\[]
Field
Type
Description
Example
hour\_start\_isorequired
string (date-time)
The date-time of spend entry to upsert in UTC, required
"1970-01-01T00:00:00-0000"
platform\_account\_id
string
The Ad Platform Account ID to upsert, used for segregating ad objects per ad platform account Default: ""
"12345"
platform\_namerequired
string
The Ad Platform Name to upsert, required
"Facebook"
campaign\_idrequired
string
The Ad Platform's Campaign ID (utm\_campaign, if known) to upsert, required
"12345"
campaign\_namerequired
string
The Ad Platform Campaign Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as campaign\_id
"Banana Festival Awareness Campaign"
adset\_id
string
The Ad Platform's Adset ID (utm\_term, if known) to upsert, defaults to '' if empty (not all platforms support adsets) Default: ""
"12345"
adset\_name
string
The Ad Platform Adset Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset\_id - defaults to '' if empty Default: ""
"Banana Adset"
ad\_id
string
The Ad Platform's Ad ID (utm\_content, if known) to upsert, defaults to '' if empty (not all platforms support ads) Default: ""
"12345"
ad\_name
string
The Ad Platform Ad Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset\_id - defaults to '' if empty Default: ""
"Banana Ad"
spendrequired
number
Amount (in currency) spent on ad object to upsert, defaults to 0 if empty Required range: x >= 0
123.5
spend\_currencyrequired
string
The Currency of the Spend per ISO 4217 to upsert, required Required string length: 3 - 3
"USD"
impressions
number
The amount of impressions the ad object received on a given date, defaults to 0 if empty Required range: x >= 0 Default: 0
299
clicks
number
The amount of clicks the ad object received on a given date, defaults to 0 if empty Required range: x >= 0 Default: 0
0
created\_atrequired
string (date-time)
updated\_atrequired
string (date-time)
### `401` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
### `422` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
### `4XX` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
### `5XX` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
# Fetch all available attribution models
Source: https://docs.northbeam.io/reference/get_attribution-models-1
openapi/data-export-v1.json GET /attribution-models
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
## Responses
| Status | Description |
| :- | :- |
| `200` | Attribution models |
| `401` | Unauthorized |
| `429` | Too many requests |
| `500` | Internal server error |
### `200` response body
Field
Type
Description
attribution\_models
object\[]
Field
Type
Description
id
string
name
string, nullable
# Fetch all labels available for breakdown
Source: https://docs.northbeam.io/reference/get_breakdowns-1
openapi/data-export-v1.json GET /breakdowns
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
## Responses
| Status | Description |
| :- | :- |
| `200` | Breakdown labels |
| `401` | Unauthorized |
| `429` | Too many requests |
| `500` | Internal server error |
### `200` response body
Field
Type
Description
breakdowns
object\[]
Field
Type
Description
key
string
values
string\[]
# Fetch a data export result
Source: https://docs.northbeam.io/reference/get_data-export-result-export-id-1
openapi/data-export-v1.json GET /data-export/result/{export_id}
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
## Path parameters
Parameter
Type
Description
export\_idrequired
string (uuid)
## Responses
| Status | Description |
| :- | :- |
| `200` | Data export result |
| `401` | Unauthorized |
| `429` | Too many requests |
| `500` | Internal server error |
### `200` response body
Field
Type
Description
data\_export\_id
string (uuid)
status
string
Available options: "PENDING", "SUCCESS", "ERROR"
result
string (uri)\[]
created\_at
string (date-time)
finished\_at
string (date-time), nullable
warn
object
Warning info regarding deprecated params, actions expected, etc.
# Fetch all available metrics
Source: https://docs.northbeam.io/reference/get_metrics-1
openapi/data-export-v1.json GET /metrics
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
## Responses
| Status | Description |
| :- | :- |
| `200` | Metrics |
| `401` | Unauthorized |
| `429` | Too many requests |
| `500` | Internal server error |
### `200` response body
Field
Type
Description
metrics
object\[]
Field
Type
Description
id
string
label
string, nullable
# Fetch a list of orders (V1)
Source: https://docs.northbeam.io/reference/get_orders
openapi/orders-v1.json GET /orders
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
## Query parameters
Parameter
Type
Description
start\_daterequired
string
Start date of the form %Y-%m-%d Default: "2001-01-01"
end\_daterequired
string
End date of the form %Y-%m-%d Default: "9999-01-01"
## Responses
| Status | Description |
| :- | :- |
| `200` | Orders fetched |
| `401` | Unauthenticated |
| `500` | Could not fetch |
# Fetch a list of orders
Source: https://docs.northbeam.io/reference/get_orders-1
openapi/orders-v2.json GET /orders
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
## Query parameters
Parameter
Type
Description
start\_daterequired
string
Start date of the form %Y-%m-%d Default: "2001-01-01"
end\_daterequired
string
End date of the form %Y-%m-%d Default: "9999-01-01"
## Responses
| Status | Description |
| :- | :- |
| `200` | Orders fetched |
| `401` | Unauthenticated |
| `500` | Could not fetch |
# List spend records
Source: https://docs.northbeam.io/reference/get_spend
openapi/spend-v1.json GET /spend
Retrieve daily spend records for a platform and date range.
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
## Query parameters
Parameter
Type
Description
Example
date
string (date)
The date of spend entries to search for - provide this OR the Date Start/End ONLY
"1970-01-01"
date\_start
string (date)
The date range of a spend entries to search for - provide this or and a end date OR a date ONLY
"1970-01-01T00:00:00Z"
date\_end
string (date)
The date range of a spend entries to search for - provide this or and a start date OR a date ONLY
"1970-01-01T00:00:00Z"
platform\_account\_id
string
The Ad Platform Account ID to search for, required
"12345"
campaign\_id
string
The Ad Platform's Campaign ID to search for
"12345"
adset\_id
string
The Ad Platform's Adset ID to search for
"12345"
ad\_id
string
The Ad Platform's Ad ID to search for
"12345"
page
integer
If Paginating - supply page number Required range: x >= 1 Default: 1
1
page\_size
integer
Results per page - Maximum of 1000 results per page Default: 1000
1000
## Responses
| Status | Description |
| :- | :- |
| `200` | List of spend records. |
| `401` | Authentication failed. |
| `422` | The request body is invalid. |
| `4XX` | An unexpected error occurred. |
| `5XX` | An unexpected error occurred. |
### `200` response body
Field
Type
Description
datarequired
object\[]
Field
Type
Description
Example
daterequired
string (date)
The date of spend entry to upsert, required
"1970-01-01"
platform\_account\_id
string
The Ad Platform Account ID to upsert, used for segregating ad objects per ad platform account Default: ""
"12345"
platform\_namerequired
string
The Ad Platform Name to upsert, required
"Facebook"
campaign\_idrequired
string
The Ad Platform's Campaign ID (utm\_campaign, if known) to upsert, required
"12345"
campaign\_namerequired
string
The Ad Platform Campaign Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as campaign\_id
"Banana Festival Awareness Campaign"
adset\_id
string
The Ad Platform's Adset ID (utm\_term, if known) to upsert, defaults to '' if empty (not all platforms support adsets) Default: ""
"12345"
adset\_name
string
The Ad Platform Adset Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset\_id - defaults to '' if empty Default: ""
"Banana Adset"
ad\_id
string
The Ad Platform's Ad ID (utm\_content, if known) to upsert, defaults to '' if empty (not all platforms support ads) Default: ""
"12345"
ad\_name
string
The Ad Platform Ad Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset\_id - defaults to '' if empty Default: ""
"Banana Ad"
spendrequired
number
Amount (in currency) spent on ad object to upsert, defaults to 0 if empty Required range: x >= 0
"123"
spend\_currencyrequired
string
The Currency of the Spend per ISO 4217 to upsert, required Required string length: 3 - 3
"USD"
impressions
number
The amount of impressions the ad object received on a given date, defaults to 0 if empty Required range: x >= 0 Default: 0
299
clicks
number
The amount of clicks the ad object received on a given date, defaults to 0 if empty Required range: x >= 0 Default: 0
0
created\_atrequired
string (date-time)
updated\_atrequired
string (date-time)
pagerequired
integer
page\_sizerequired
integer
total\_pagesrequired
integer
total\_countrequired
integer
### `401` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
### `422` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
### `4XX` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
### `5XX` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
# List spend records (hourly)
Source: https://docs.northbeam.io/reference/get_spend-hourly
openapi/spend-v1.json GET /spend_hourly
Retrieve hourly spend records for a platform and time range.
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
## Query parameters
Parameter
Type
Description
Example
hour\_start\_iso\_begin
string (date-time)
The date range of a spend entries to search for - provide this or and a end date OR a date ONLY
"1970-01-01T00:00:00-0000"
hour\_start\_iso\_end
string (date-time)
The date range of a spend entries to search for - provide this or and a start date OR a date ONLY
"1970-01-01T01:00:00-0000"
platform\_account\_id
string
The Ad Platform Account ID to search for, required
"12345"
campaign\_id
string
The Ad Platform's Campaign ID to search for
"12345"
adset\_id
string
The Ad Platform's Adset ID to search for
"12345"
ad\_id
string
The Ad Platform's Ad ID to search for
"12345"
page
integer
If Paginating - supply page number Required range: x >= 1 Default: 1
1
page\_size
integer
Results per page - Maximum of 1000 results per page Default: 1000
1000
## Responses
| Status | Description |
| :- | :- |
| `200` | List of spend records. |
| `401` | Authentication failed. |
| `422` | The request body is invalid. |
| `4XX` | An unexpected error occurred. |
| `5XX` | An unexpected error occurred. |
### `200` response body
Field
Type
Description
datarequired
object\[]
Field
Type
Description
Example
hour\_start\_isorequired
string (date-time)
The date-time of spend entry to upsert in UTC, required
"1970-01-01T00:00:00-0000"
platform\_account\_id
string
The Ad Platform Account ID to upsert, used for segregating ad objects per ad platform account Default: ""
"12345"
platform\_namerequired
string
The Ad Platform Name to upsert, required
"Facebook"
campaign\_idrequired
string
The Ad Platform's Campaign ID (utm\_campaign, if known) to upsert, required
"12345"
campaign\_namerequired
string
The Ad Platform Campaign Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as campaign\_id
"Banana Festival Awareness Campaign"
adset\_id
string
The Ad Platform's Adset ID (utm\_term, if known) to upsert, defaults to '' if empty (not all platforms support adsets) Default: ""
"12345"
adset\_name
string
The Ad Platform Adset Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset\_id - defaults to '' if empty Default: ""
"Banana Adset"
ad\_id
string
The Ad Platform's Ad ID (utm\_content, if known) to upsert, defaults to '' if empty (not all platforms support ads) Default: ""
"12345"
ad\_name
string
The Ad Platform Ad Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset\_id - defaults to '' if empty Default: ""
"Banana Ad"
spendrequired
number
Amount (in currency) spent on ad object to upsert, defaults to 0 if empty Required range: x >= 0
123.5
spend\_currencyrequired
string
The Currency of the Spend per ISO 4217 to upsert, required Required string length: 3 - 3
"USD"
impressions
number
The amount of impressions the ad object received on a given date, defaults to 0 if empty Required range: x >= 0 Default: 0
299
clicks
number
The amount of clicks the ad object received on a given date, defaults to 0 if empty Required range: x >= 0 Default: 0
0
created\_atrequired
string (date-time)
updated\_atrequired
string (date-time)
pagerequired
integer
page\_sizerequired
integer
total\_pagesrequired
integer
total\_countrequired
integer
### `401` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
### `422` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
### `4XX` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
### `5XX` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
# Partially update existing orders
Source: https://docs.northbeam.io/reference/patchorders
openapi/orders-v2.json PATCH /orders
Update specific fields of existing orders. Only fields present in the
request payload will be modified. Omitted fields retain their existing values.
Use explicit null to clear optional field values.
**Note:** The `products` and `refunds` fields currently cannot be patched. To modify
products or refunds, re-submit the full order via POST.
Array fields (order_tags, discount_codes) are replaced entirely when
present - no per-item merging is performed.
The entire batch fails if any order_id does not exist or any entry fails validation.
Update specific fields of existing orders. Only fields present in the
request payload will be modified. Omitted fields retain their existing values.
Use explicit null to clear optional field values.
**Note:** The `products` and `refunds` fields currently cannot be patched. To modify
products or refunds, re-submit the full order via POST.
Array fields (order\_tags, discount\_codes) are replaced entirely when
present - no per-item merging is performed.
The entire batch fails if any order\_id does not exist or any entry fails validation.
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
| `Content-Type` required | `application/json` |
## Body
Required array length: `1 - 2500` elements
Partial order update. Only order\_id and customer\_id are required.
Field
Type
Description
Example
order\_idrequired
string
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. Minimum string length: 1
"abc-123"
customer\_idrequired
string
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. This should not be an email. Minimum string length: 1
"def-456"
time\_of\_purchase
string (date-time)
The time the order was placed by the customer. ISO-8601 timestamp.
"2022-03-08T01:23:45-08:00"
customer\_email
string (email), nullable
The email associated with the customer. Cannot be provided if hashed\_customer\_email is present.
"[example@gmail.com](mailto:example@gmail.com)"
hashed\_customer\_email
string, nullable
Pre-hashed (SHA-256) email associated with the customer. Cannot be provided if customer\_email is present. Important: Email must be normalized before hashing. See the Hashing Customer Data guide for normalization rules and implementation examples.
The phone number associated with the customer. Cannot be provided if hashed\_customer\_phone\_number is present.
"1112223333"
hashed\_customer\_phone\_number
string, nullable
Pre-hashed (SHA-256) phone number associated with the customer. Cannot be provided if customer\_phone\_number is present. Important: Phone number must be normalized to E.164 format before hashing. See the Hashing Customer Data guide for normalization rules and implementation examples.
A list of discount codes used in the order. Items must be unique.
"Discount"
discount\_amount
number, nullable
The amount of money discounted due to discount codes in the currency of the order. Required range: x \<= 100000000000000
10
order\_tags
string\[], nullable
A list of internal tags describing the order. Items must be unique.
"Special order"
tax
number, nullable
The tax amount in the currency of the order. Required range: x \<= 100000000000000
1
is\_recurring\_order
boolean, nullable
Whether or not this order is part of a recurring purchase.
false
currency
string, nullable
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. Minimum string length: 3 Pattern:
The amount of money collected from the customer (including taxes, shipping, and other fees) in the currency of the order. Required range: x \<= 100000000000000
10000
customer\_shipping\_address
object, nullable
Field
Type
Description
Example
address1
string
The street address of the customer's shipping address. Minimum string length: 1
"123 Main St."
address2
string
An optional additional field for the street address.
"Apt. 1A"
city
string
The city or locality of the customer's shipping address. Minimum string length: 1
"Small town"
state
string
The state or region of the customer's shipping address.
"CO"
ziprequired
string
The postal code (e.g. zip, postcode) of the customer's shipping address.
"11111"
country\_coderequired
string
The three-letter ISO 3166 country code of the customer's shipping address. Minimum string length: 1 Pattern:
The amount that was paid for shipping for this order Required range: x \<= 100000000000000
10.99
alternate\_order\_ids
object\[], nullable
Alternate identifiers for this order
Field
Type
Description
Example
typerequired
string
Alias type identifier Minimum string length: 1
"shopify\_checkout\_token"
idrequired
string
The alternate order ID value Minimum string length: 1
"abc-xyz-123"
## Responses
| Status | Description |
| :- | :- |
| `200` | Orders successfully queued for update |
| `400` | Invalid input - validation error or order not found |
| `401` | Unauthenticated |
| `413` | Payload too large |
| `500` | Server error |
### `200` response body
Field
Type
Description
Example
message
string
"Orders received"
# Create a Sales Attribution export
Source: https://docs.northbeam.io/reference/post_data-export-1
openapi/data-export-v1.json POST /data-export
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
| `Content-Type` required | `application/json` |
## Body
Send **one** of the following 3 shapes.
### Export to Northbeam documents
Field
Type
Description
export\_file\_name
string
Name of the exported file, if not provided, default one will be used. Minimum string length: 3 Pattern: ^\[A-Za-z0-9\_-]+\$
level
string
Level of metrics to export. Available options: "platform", "campaign", "adset", "ad" Default: "platform"
time\_granularity
string
Data time granularity. Available options: "MONTHLY", "WEEKLY", "DAILY", "HOURLY" Default: "DAILY"
period\_type
string
Time period to be exported. It can be either a relative window or a fixed window. If you choose to export a fixed window, the period\_options property must be set. Available options: "FIXED", "TODAY", "YESTERDAY", "YESTERDAY\_AND\_TODAY", "LAST\_3\_DAYS", "LAST\_7\_DAYS", "LAST\_14\_DAYS", "LAST\_28\_DAYS", "LAST\_30\_DAYS", "LAST\_60\_DAYS", "LAST\_90\_DAYS", "LAST\_180\_DAYS", "MONTH\_TO\_DATE", "LAST\_MONTH", "THIS\_WEEK", "LAST\_WEEK", "THIS\_WEEK\_AND\_LAST\_WEEK", "LAST\_3\_WEEKS", "LAST\_4\_WEEKS", "LAST\_7\_WEEKS", "LAST\_12\_WEEKS", "LAST\_14\_WEEKS", "LAST\_26\_WEEKS", "LAST\_28\_WEEKS", "LAST\_52\_WEEKS", "THIS\_MONTH", "THIS\_MONTH\_AND\_LAST\_MONTH", "LAST\_3\_MONTHS", "LAST\_6\_MONTHS", "LAST\_9\_MONTHS", "LAST\_12\_MONTHS", "YEAR\_TO\_DATE", "LAST\_YEAR", "LAST\_3\_YEARS", "LAST\_5\_YEARS" Default: "LAST\_7\_DAYS"
period\_options
object
Time frame to be exported if period\_type is set to "FIXED". The time period cannot be greater than 2 years.
Field
Type
Description
period\_starting\_at
string (date-time)
period\_ending\_at
string (date-time)
breakdowns
object\[]
Labels used to breakdown the data. If you are unsure which breakdowns to use, you can fetch them using the /breakdowns endpoint.
Field
Type
Description
key
string
values
string\[]
options
object
Field
Type
Description
export\_aggregation
string
Aggregation type. Available options: "BREAKDOWN", "DATE" Default: "BREAKDOWN"
remove\_zero\_spend
boolean
Remove rows with zero spend. Default: false
aggregate\_data
boolean
Aggregate data, ignoring campaign, adset and ad levels. Default: false
include\_ids
boolean
Include campaign, adset and ad ids in exported data. Default: false
include\_kind\_and\_platform
boolean
Include campaign, adset and ad kind and platform in exported data. Default: false
attribution\_optionsrequired
object
Field
Type
Description
attribution\_models
string\[]
Attribution models to use. Check in /attribution-models for available models. Required range: x >= 1
attribution\_windows
string\[]
Required range: x >= 1
accounting\_modes
string\[]
Required range: x >= 1
metricsrequired
object\[]
Metrics to export. Check in /metrics for available metrics. Required range: x >= 1
Field
Type
Description
idrequired
string
Metric ID
label
string
Metric label to be used as file header. If not provided, a default label will be used. Pattern: ^\[a-zA-Z]\[a-zA-Z0-9\_]+\[a-zA-Z0-9]\$
### Export to GCS bucket
Field
Type
Description
bucket\_namerequired
string
Name of the external bucket where to export your file.
export\_file\_name
string
Name of the exported file, if not provided, default one will be used. Can include subdirectory paths (e.g., folder/subfolder/file). Minimum string length: 3 Pattern: ^(?!/)(?!.\*//)\[A-Za-z0-9\_/-]+(?\
level
string
Level of metrics to export. Available options: "platform", "campaign", "adset", "ad" Default: "platform"
time\_granularity
string
Data time granularity. Available options: "MONTHLY", "WEEKLY", "DAILY", "HOURLY" Default: "DAILY"
period\_type
string
Time period to be exported. It can be either a relative window or a fixed window. If you choose to export a fixed window, the period\_options property must be set. Available options: "FIXED", "TODAY", "YESTERDAY", "YESTERDAY\_AND\_TODAY", "LAST\_3\_DAYS", "LAST\_7\_DAYS", "LAST\_14\_DAYS", "LAST\_28\_DAYS", "LAST\_30\_DAYS", "LAST\_60\_DAYS", "LAST\_90\_DAYS", "LAST\_180\_DAYS", "MONTH\_TO\_DATE", "LAST\_MONTH", "THIS\_WEEK", "LAST\_WEEK", "THIS\_WEEK\_AND\_LAST\_WEEK", "LAST\_3\_WEEKS", "LAST\_4\_WEEKS", "LAST\_7\_WEEKS", "LAST\_12\_WEEKS", "LAST\_14\_WEEKS", "LAST\_26\_WEEKS", "LAST\_28\_WEEKS", "LAST\_52\_WEEKS", "THIS\_MONTH", "THIS\_MONTH\_AND\_LAST\_MONTH", "LAST\_3\_MONTHS", "LAST\_6\_MONTHS", "LAST\_9\_MONTHS", "LAST\_12\_MONTHS", "YEAR\_TO\_DATE", "LAST\_YEAR", "LAST\_3\_YEARS", "LAST\_5\_YEARS" Default: "LAST\_7\_DAYS"
period\_options
object
Time frame to be exported if period\_type is set to "FIXED". The time period cannot be greater than 2 years.
Field
Type
Description
period\_starting\_at
string (date-time)
period\_ending\_at
string (date-time)
breakdowns
object\[]
Labels used to breakdown the data. If you are unsure which breakdowns to use, you can fetch them using the /breakdowns endpoint.
Field
Type
Description
key
string
values
string\[]
options
object
Field
Type
Description
export\_aggregation
string
Aggregation type. Available options: "BREAKDOWN", "DATE" Default: "BREAKDOWN"
remove\_zero\_spend
boolean
Remove rows with zero spend. Default: false
aggregate\_data
boolean
Aggregate data, ignoring campaign, adset and ad levels. Default: false
include\_ids
boolean
Include campaign, adset and ad ids in exported data. Default: false
include\_kind\_and\_platform
boolean
Include campaign, adset and ad kind and platform in exported data. Default: false
attribution\_optionsrequired
object
Field
Type
Description
attribution\_models
string\[]
Attribution models to use. Check in /attribution-models for available models. Required range: x >= 1
attribution\_windows
string\[]
Required range: x >= 1
accounting\_modes
string\[]
Required range: x >= 1
metricsrequired
object\[]
Metrics to export. Check in /metrics for available metrics. Required range: x >= 1
Field
Type
Description
idrequired
string
Metric ID
label
string
Metric label to be used as file header. If not provided, a default label will be used. Pattern: ^\[a-zA-Z]\[a-zA-Z0-9\_]+\[a-zA-Z0-9]\$
### Export to S3 bucket
Field
Type
Description
aws\_rolerequired
string
AWS role ARN with access to the S3 bucket.
regionrequired
string
Region of the S3 bucket.
export\_file\_name
string
Name of the exported file, if not provided, default one will be used. Can include subdirectory paths (e.g., folder/subfolder/file). Minimum string length: 3 Pattern: ^(?!/)(?!.\*//)\[A-Za-z0-9\_/-]+(?\
level
string
Level of metrics to export. Available options: "platform", "campaign", "adset", "ad" Default: "platform"
time\_granularity
string
Data time granularity. Available options: "MONTHLY", "WEEKLY", "DAILY", "HOURLY" Default: "DAILY"
period\_type
string
Time period to be exported. It can be either a relative window or a fixed window. If you choose to export a fixed window, the period\_options property must be set. Available options: "FIXED", "TODAY", "YESTERDAY", "YESTERDAY\_AND\_TODAY", "LAST\_3\_DAYS", "LAST\_7\_DAYS", "LAST\_14\_DAYS", "LAST\_28\_DAYS", "LAST\_30\_DAYS", "LAST\_60\_DAYS", "LAST\_90\_DAYS", "LAST\_180\_DAYS", "MONTH\_TO\_DATE", "LAST\_MONTH", "THIS\_WEEK", "LAST\_WEEK", "THIS\_WEEK\_AND\_LAST\_WEEK", "LAST\_3\_WEEKS", "LAST\_4\_WEEKS", "LAST\_7\_WEEKS", "LAST\_12\_WEEKS", "LAST\_14\_WEEKS", "LAST\_26\_WEEKS", "LAST\_28\_WEEKS", "LAST\_52\_WEEKS", "THIS\_MONTH", "THIS\_MONTH\_AND\_LAST\_MONTH", "LAST\_3\_MONTHS", "LAST\_6\_MONTHS", "LAST\_9\_MONTHS", "LAST\_12\_MONTHS", "YEAR\_TO\_DATE", "LAST\_YEAR", "LAST\_3\_YEARS", "LAST\_5\_YEARS" Default: "LAST\_7\_DAYS"
period\_options
object
Time frame to be exported if period\_type is set to "FIXED". The time period cannot be greater than 2 years.
Field
Type
Description
period\_starting\_at
string (date-time)
period\_ending\_at
string (date-time)
breakdowns
object\[]
Labels used to breakdown the data. If you are unsure which breakdowns to use, you can fetch them using the /breakdowns endpoint.
Field
Type
Description
key
string
values
string\[]
options
object
Field
Type
Description
export\_aggregation
string
Aggregation type. Available options: "BREAKDOWN", "DATE" Default: "BREAKDOWN"
remove\_zero\_spend
boolean
Remove rows with zero spend. Default: false
aggregate\_data
boolean
Aggregate data, ignoring campaign, adset and ad levels. Default: false
include\_ids
boolean
Include campaign, adset and ad ids in exported data. Default: false
include\_kind\_and\_platform
boolean
Include campaign, adset and ad kind and platform in exported data. Default: false
attribution\_optionsrequired
object
Field
Type
Description
attribution\_models
string\[]
Attribution models to use. Check in /attribution-models for available models. Required range: x >= 1
attribution\_windows
string\[]
Required range: x >= 1
accounting\_modes
string\[]
Required range: x >= 1
metricsrequired
object\[]
Metrics to export. Check in /metrics for available metrics. Required range: x >= 1
Field
Type
Description
idrequired
string
Metric ID
label
string
Metric label to be used as file header. If not provided, a default label will be used. Pattern: ^\[a-zA-Z]\[a-zA-Z0-9\_]+\[a-zA-Z0-9]\$
## Responses
| Status | Description |
| :- | :- |
| `201` | Data Export created successfully |
| `401` | Unauthorized |
| `422` | Invalid Body Params |
| `429` | Too many requests |
| `500` | Internal server error |
### `201` response body
Field
Type
Description
idrequired
string (uuid)
# Create an Orders export
Source: https://docs.northbeam.io/reference/post_data-export-orders
openapi/data-export-v1.json POST /data-export/orders
Trigger a one-off Orders export to your own GCS or S3 bucket. The export contains one row per order. By default it uses the default order columns (which include the customer type, first-time vs. returning); if you pass an explicit `columns` list you get exactly those columns. Product ids/SKUs, order tags, and the order source name are available as optional columns. Poll the returned `id` with `GET /data-export/result/{export_id}`.
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
| `Content-Type` required | `application/json` |
## Body
Field
Type
Description
bucket\_namerequired
string
Name of the external GCS or S3 bucket to export to.
aws\_role
string, nullable
AWS role ARN with access to the S3 bucket (required for S3 exports).
region
string, nullable
AWS region of the S3 bucket (required for S3 exports).
export\_file\_name
string
Name of the exported file. A default name is used if omitted. Minimum string length: 3 Pattern: ^(?!/)(?!.\*//)\[A-Za-z0-9\_/-]+(?\
start\_daterequired
string (date-time)
Start of the export window (inclusive).
end\_daterequired
string (date-time)
End of the export window (exclusive).
columns
string\[]
Optional list of column ids to include, in order. When omitted, the default columns are used. When provided, it must be a non-empty list of distinct ids, and you get exactly the columns you list — any subset of the allowed ids is valid and nothing is mandatory (customer\_type is a default column, so include it here if you want it). products is a single column of comma-separated SKUs, falling back to the product id when a SKU is missing. Minimum array length: 1 Items must be unique.
## Responses
| Status | Description |
| :- | :- |
| `201` | Orders export created successfully |
| `401` | Unauthorized |
| `422` | Invalid Body Params |
| `429` | Too many requests |
| `500` | Internal server error |
### `201` response body
Field
Type
Description
idrequired
string (uuid)
# Upsert a list of orders to Northbeam (V1, deprecated)
Source: https://docs.northbeam.io/reference/post_orders
openapi/orders-v1.json POST /orders
**This is the deprecated V1 endpoint.** New integrations should use the
[V2 upsert orders endpoint](/reference/post_orders-1). V1 will be
supported for existing integrations but will not receive new features.
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
| `Content-Type` required | `application/json` |
## Body
Orders list
Minimum array length: `1` Items must be unique.
Field
Type
Description
Example
order\_idrequired
string
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. Minimum string length: 1
"abc-123"
customer\_idrequired
string
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. This should not be an email. Minimum string length: 1
"def-456"
time\_of\_purchaserequired
string (date-time)
The time the order was placed by the customer. ISO-8601 timestamp.
"2022-03-08T01:23:45-08:00"
customer\_email
string (email)
The email associated with the customer. Cannot be provided if hashed\_customer\_email is present.
"[example@gmail.com](mailto:example@gmail.com)"
customer\_phone\_number
string
The phone number associated with the customer. Cannot be provided if hashed\_customer\_phone\_number is present.
"1112223333"
hashed\_customer\_email
string
Pre-hashed (SHA-256) email associated with the customer. Cannot be provided if customer\_email is present. Important: Email must be normalized before hashing. See the Hashing Customer Data guide for normalization rules and implementation examples.
Pre-hashed (SHA-256) phone number associated with the customer. Cannot be provided if customer\_phone\_number is present. Important: Phone number must be normalized to E.164 format before hashing. See the Hashing Customer Data guide for normalization rules and implementation examples.
A list of discount codes used in the order. Items must be unique.
"Discount"
discount\_amount
number
The amount of money discounted due to discount codes in the currency of the order. Required range: x \<= 100000000000000
10
order\_tags
string\[]
A list of internal tags describing the order. Items must be unique.
"Special order"
taxrequired
number
The tax amount in the currency of the order. Required range: x \<= 100000000000000
1
is\_recurring\_order
boolean
Whether or not this order is part of a recurring purchase.
false
currencyrequired
string
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. Minimum string length: 1 Pattern:
The amount of money collected from the customer (including taxes, shipping, and other fees) in the currency of the order. Required range: x \<= 100000000000000
10000
productsrequired
object\[]
A list of objects describing the products in the order. Minimum array length: 1
Field
Type
Description
Example
idrequired
string
A unique identifier describing the product in the order. Minimum string length: 1
"prod-1"
namerequired
string
The name of the product. Minimum string length: 1
"Our product"
quantityrequired
number
How many of this product was sold in the order Required range: x \<= 100000000000000
1
pricerequired
number
The (per unit) price of the product in the currency of the order. Required range: x \<= 100000000000000
10011
refunds
object\[]
A list of objects describing the refunded products. Items must be unique.
Field
Type
Description
product\_idrequired
string
A unique identifier describing the product in the refund (should also be included in the products list). Minimum string length: 1
quantityrequired
number
The number of products refunded (should be less than or equal to the corresponding quantity in the products list). Required range: x \<= 100000000000000
refund\_amountrequired
number
The total amount refunded to the customer in the currency of the order. Required range: x \<= 100000000000000
refund\_costrequired
number
The estimated total cost of the refund, including the refund amount to the customer and any other overhead costs (i.e. shipping, fees). Required range: x \<= 100000000000000
refund\_made\_atrequired
string (date-time)
The time the refund was fulfilled by your brand. ISO-8601 timestamp.
customer\_shipping\_address
object
Field
Type
Description
Example
address1
string
The street address of the customer's shipping address. Minimum string length: 1
"123 Main St."
address2
string
An optional additional field for the street address.
"Apt. 1A"
city
string
The city or locality of the customer's shipping address. Minimum string length: 1
"Small town"
state
string
The state or region of the customer's shipping address.
"CO"
ziprequired
string
The postal code (e.g. zip, postcode) of the customer's shipping address.
"11111"
country\_coderequired
string
The three-letter ISO 3166 country code of the customer’s shipping address. Minimum string length: 3 Pattern:
# Upsert a list of orders to Northbeam
Source: https://docs.northbeam.io/reference/post_orders-1
openapi/orders-v2.json POST /orders
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
| `Content-Type` required | `application/json` |
## Body
Orders list
Minimum array length: `1` Items must be unique.
Field
Type
Description
Example
order\_idrequired
string
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. Minimum string length: 1
"abc-123"
customer\_idrequired
string
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. This should not be an email. Minimum string length: 1
"def-456"
time\_of\_purchaserequired
string (date-time)
The time the order was placed by the customer. ISO-8601 timestamp.
"2022-03-08T01:23:45-08:00"
customer\_email
string (email)
The email associated with the customer. Cannot be provided if hashed\_customer\_email is present.
"[example@gmail.com](mailto:example@gmail.com)"
customer\_phone\_number
string
The phone number associated with the customer. Cannot be provided if hashed\_customer\_phone\_number is present.
"1112223333"
hashed\_customer\_email
string
Pre-hashed (SHA-256) email associated with the customer. Cannot be provided if customer\_email is present. Important: Email must be normalized before hashing. See the Hashing Customer Data guide for normalization rules and implementation examples.
Pre-hashed (SHA-256) phone number associated with the customer. Cannot be provided if customer\_phone\_number is present. Important: Phone number must be normalized to E.164 format before hashing. See the Hashing Customer Data guide for normalization rules and implementation examples.
A list of discount codes used in the order. Items must be unique.
"Discount"
discount\_amount
number
The amount of money discounted due to discount codes in the currency of the order. Required range: x \<= 100000000000000
10
order\_tags
string\[]
A list of internal tags describing the order. Items must be unique.
"Special order"
taxrequired
number
The tax amount in the currency of the order. Required range: x \<= 100000000000000
1
is\_recurring\_order
boolean
Whether or not this order is part of a recurring purchase.
false
currencyrequired
string
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. Minimum string length: 3 Pattern:
The amount of money collected from the customer (including taxes, shipping, and other fees) in the currency of the order. Required range: x \<= 100000000000000
10000
productsrequired
object\[]
A list of objects describing the products in the order. Minimum array length: 1
Field
Type
Description
Example
idrequired
string
A unique identifier describing the product in the order. Minimum string length: 1
"prod-1"
namerequired
string
The name of the product. Minimum string length: 1
"Our product"
quantityrequired
number
How many of this product was sold in the order Required range: x \<= 100000000000000
1
pricerequired
number
The (per unit) price of the product in the currency of the order. Required range: x \<= 100000000000000
10011
variant\_id
string
A unique identifier describing the product variant in the order. Minimum string length: 1
"prod-variant-1"
variant\_name
string
The name of the product variant. Cannot be empty when specified.
"Our product variant"
refunds
object\[]
A list of objects describing the refunded products. Items must be unique.
Field
Type
Description
product\_idrequired
string
A unique identifier describing the product in the refund (should also be included in the products list). Minimum string length: 1
quantityrequired
number
The number of products refunded (should be less than or equal to the corresponding quantity in the products list). Required range: x \<= 100000000000000
refund\_amountrequired
number
The total amount refunded to the customer in the currency of the order. Required range: x \<= 100000000000000
refund\_costrequired
number
The estimated total cost of the refund, including the refund amount to the customer and any other overhead costs (i.e. shipping, fees). Required range: x \<= 100000000000000
refund\_made\_atrequired
string (date-time)
The time the refund was fulfilled by your brand. ISO-8601 timestamp.
variant\_id
string
A unique identifier describing the variant of the product in the refund (should also be included in the products list). Minimum string length: 1
customer\_shipping\_address
object
Field
Type
Description
Example
address1
string
The street address of the customer's shipping address. Minimum string length: 1
"123 Main St."
address2
string
An optional additional field for the street address.
"Apt. 1A"
city
string
The city or locality of the customer's shipping address. Minimum string length: 1
"Small town"
state
string
The state or region of the customer's shipping address.
"CO"
ziprequired
string
The postal code (e.g. zip, postcode) of the customer's shipping address.
"11111"
country\_coderequired
string
The three-letter ISO 3166 country code of the customer's shipping address. Minimum string length: 1 Pattern:
# Upsert one or multiple spend records
Source: https://docs.northbeam.io/reference/post_spend
openapi/spend-v1.json POST /spend
Create or update daily spend records. Records are matched on platform and the campaign/adset/ad hierarchy plus date; existing records with the same key are overwritten. Batches of up to 1000 per call.
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
| `Content-Type` required | `application/json` |
## Body
Field
Type
Description
datarequired
object\[]
Field
Type
Description
Example
daterequired
string (date)
The date of spend entry to upsert, required
"1970-01-01"
platform\_account\_id
string
The Ad Platform Account ID to upsert, used for segregating ad objects per ad platform account Default: ""
"12345"
platform\_namerequired
string
The Ad Platform Name to upsert, required
"Facebook"
campaign\_idrequired
string
The Ad Platform's Campaign ID (utm\_campaign, if known) to upsert, required
"12345"
campaign\_namerequired
string
The Ad Platform Campaign Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as campaign\_id
"Banana Festival Awareness Campaign"
adset\_id
string
The Ad Platform's Adset ID (utm\_term, if known) to upsert, defaults to '' if empty (not all platforms support adsets) Default: ""
"12345"
adset\_name
string
The Ad Platform Adset Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset\_id - defaults to '' if empty Default: ""
"Banana Adset"
ad\_id
string
The Ad Platform's Ad ID (utm\_content, if known) to upsert, defaults to '' if empty (not all platforms support ads) Default: ""
"12345"
ad\_name
string
The Ad Platform Ad Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset\_id - defaults to '' if empty Default: ""
"Banana Ad"
spendrequired
number
Amount (in currency) spent on ad object to upsert, defaults to 0 if empty Required range: x >= 0
"123"
spend\_currencyrequired
string
The Currency of the Spend per ISO 4217 to upsert, required Required string length: 3 - 3
"USD"
impressions
number
The amount of impressions the ad object received on a given date, defaults to 0 if empty Required range: x >= 0 Default: 0
299
clicks
number
The amount of clicks the ad object received on a given date, defaults to 0 if empty Required range: x >= 0 Default: 0
0
## Responses
| Status | Description |
| :- | :- |
| `201` | The spend records were successfully upserted. |
| `401` | Authentication failed. |
| `422` | The request body is invalid. |
| `4XX` | An unexpected error occurred. |
| `5XX` | An unexpected error occurred. |
### `201` response body
Field
Type
Description
datarequired
object\[]
Field
Type
Description
Example
daterequired
string (date)
The date of spend entry to upsert, required
"1970-01-01"
platform\_account\_id
string
The Ad Platform Account ID to upsert, used for segregating ad objects per ad platform account Default: ""
"12345"
platform\_namerequired
string
The Ad Platform Name to upsert, required
"Facebook"
campaign\_idrequired
string
The Ad Platform's Campaign ID (utm\_campaign, if known) to upsert, required
"12345"
campaign\_namerequired
string
The Ad Platform Campaign Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as campaign\_id
"Banana Festival Awareness Campaign"
adset\_id
string
The Ad Platform's Adset ID (utm\_term, if known) to upsert, defaults to '' if empty (not all platforms support adsets) Default: ""
"12345"
adset\_name
string
The Ad Platform Adset Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset\_id - defaults to '' if empty Default: ""
"Banana Adset"
ad\_id
string
The Ad Platform's Ad ID (utm\_content, if known) to upsert, defaults to '' if empty (not all platforms support ads) Default: ""
"12345"
ad\_name
string
The Ad Platform Ad Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset\_id - defaults to '' if empty Default: ""
"Banana Ad"
spendrequired
number
Amount (in currency) spent on ad object to upsert, defaults to 0 if empty Required range: x >= 0
"123"
spend\_currencyrequired
string
The Currency of the Spend per ISO 4217 to upsert, required Required string length: 3 - 3
"USD"
impressions
number
The amount of impressions the ad object received on a given date, defaults to 0 if empty Required range: x >= 0 Default: 0
299
clicks
number
The amount of clicks the ad object received on a given date, defaults to 0 if empty Required range: x >= 0 Default: 0
0
created\_atrequired
string (date-time)
updated\_atrequired
string (date-time)
### `401` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
### `422` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
### `4XX` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
### `5XX` response body
Field
Type
Description
errors
object\[], nullable
messagerequired
string
request\_id
string (uuid), nullable
# Upsert one or multiple hourly spend records
Source: https://docs.northbeam.io/reference/post_spend-hourly
openapi/spend-v1.json POST /spend_hourly
Create or update hourly spend records. Same matching behavior as the daily endpoint, at hourly granularity. Batches of up to 1000 per call.
## Headers
| Header | Description |
| :- | :- |
| `Authorization` required | Your Northbeam API key |
| `Data-Client-ID` required | Your Northbeam client ID |
| `Content-Type` required | `application/json` |
## Body
Field
Type
Description
datarequired
object\[]
Field
Type
Description
Example
hour\_start\_isorequired
string (date-time)
The date-time of spend entry to upsert in UTC, required
"1970-01-01T00:00:00-0000"
platform\_account\_id
string
The Ad Platform Account ID to upsert, used for segregating ad objects per ad platform account Default: ""
"12345"
platform\_namerequired
string
The Ad Platform Name to upsert, required
"Facebook"
campaign\_idrequired
string
The Ad Platform's Campaign ID (utm\_campaign, if known) to upsert, required
"12345"
campaign\_namerequired
string
The Ad Platform Campaign Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as campaign\_id
"Banana Festival Awareness Campaign"
adset\_id
string
The Ad Platform's Adset ID (utm\_term, if known) to upsert, defaults to '' if empty (not all platforms support adsets) Default: ""
"12345"
adset\_name
string
The Ad Platform Adset Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset\_id - defaults to '' if empty Default: ""
"Banana Adset"
ad\_id
string
The Ad Platform's Ad ID (utm\_content, if known) to upsert, defaults to '' if empty (not all platforms support ads) Default: ""
"12345"
ad\_name
string
The Ad Platform Ad Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset\_id - defaults to '' if empty Default: ""
"Banana Ad"
spendrequired
number
Amount (in currency) spent on ad object to upsert, defaults to 0 if empty Required range: x >= 0
123.5
spend\_currencyrequired
string
The Currency of the Spend per ISO 4217 to upsert, required Required string length: 3 - 3
"USD"
impressions
number
The amount of impressions the ad object received on a given date, defaults to 0 if empty Required range: x >= 0 Default: 0
299
clicks
number
The amount of clicks the ad object received on a given date, defaults to 0 if empty Required range: x >= 0 Default: 0
0
## Responses
| Status | Description |
| :- | :- |
| `201` | The hourly spend records were successfully upserted. |
| `401` | Authentication failed. |
| `422` | The request body is invalid. |
| `4XX` | An unexpected error occurred. |
| `5XX` | An unexpected error occurred. |
### `201` response body
Field
Type
Description
datarequired
object\[]
Field
Type
Description
Example
hour\_start\_isorequired
string (date-time)
The date-time of spend entry to upsert in UTC, required
"1970-01-01T00:00:00-0000"
platform\_account\_id
string
The Ad Platform Account ID to upsert, used for segregating ad objects per ad platform account Default: ""
"12345"
platform\_namerequired
string
The Ad Platform Name to upsert, required
"Facebook"
campaign\_idrequired
string
The Ad Platform's Campaign ID (utm\_campaign, if known) to upsert, required
"12345"
campaign\_namerequired
string
The Ad Platform Campaign Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as campaign\_id
"Banana Festival Awareness Campaign"
adset\_id
string
The Ad Platform's Adset ID (utm\_term, if known) to upsert, defaults to '' if empty (not all platforms support adsets) Default: ""
"12345"
adset\_name
string
The Ad Platform Adset Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset\_id - defaults to '' if empty Default: ""
"Banana Adset"
ad\_id
string
The Ad Platform's Ad ID (utm\_content, if known) to upsert, defaults to '' if empty (not all platforms support ads) Default: ""
"12345"
ad\_name
string
The Ad Platform Ad Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset\_id - defaults to '' if empty Default: ""
"Banana Ad"
spendrequired
number
Amount (in currency) spent on ad object to upsert, defaults to 0 if empty Required range: x >= 0
123.5
spend\_currencyrequired
string
The Currency of the Spend per ISO 4217 to upsert, required Required string length: 3 - 3
"USD"
impressions
number
The amount of impressions the ad object received on a given date, defaults to 0 if empty Required range: x >= 0 Default: 0
299
clicks
number
The amount of clicks the ad object received on a given date, defaults to 0 if empty Required range: x >= 0 Default: 0