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

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.

How Do I Set Up The Spend API?

Important Links:

• Spend API Docs
• Endpoint: https://api.northbeam.io/v1/spend

Required Credentials (Find these in the Northbeam dashboard):

• API Key
• Client ID

Settings > API keys

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.

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

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

[
  {
    "date": "2025-07-20",
    "platform_name": "email_marketing",
    "campaign_id": "12345",
    "campaign_name": "12345",
    "spend": 135.50,
    "spend_currency": "USD"
  }
]

Spend API Responses

🕙

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.

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.

Other Requirements:

• Make sure 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, go to: Settings → Profile in the Northbeam dashboard

UTM & Spend Field Mapping Example

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:

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.

Creating a New Breakdown Label

Follow these steps to build the label:

1. Go to the Sales Page in your Northbeam dashboard.
2. Click the three dots (…) next to Breakdown By, then click Manage Breakdowns.
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

Breakdown Rule Logic

Use OR logic to group matching revenue and spend sources:

Output Label Logic

The Output Label Rule is how the matching criteria will be labeled.

{{#functions.lower}}{{data.name}}{{/functions.lower}}

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

✅

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. Go to the **Sales page **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.