> ## Documentation Index
> Fetch the complete documentation index at: https://docs.northbeam.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Meta Ads Setup

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

<Info>
  **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
</Info>

<CardGroup cols={3}>
  <Card title="1. Connect the account" icon="plug" href="#connect-your-meta-ad-account">
    Sync spend, impressions, and campaign structure from Meta.
  </Card>

  <Card title="2. Add Northbeam parameters" icon="link" href="#add-northbeam-parameters-to-your-ads">
    Add `nbt` and `nb_placement` so visits and orders tie back to your ads.
  </Card>

  <Card title="3. Confirm tracking" icon="circle-check" href="#confirm-tracking">
    Test a live ad to check the parameters and the Pixel.
  </Card>
</CardGroup>

<Steps titleSize="h2">
  <Step title="Connect your Meta ad account">
    <span id="step-1-connect-your-meta-ad-account" style={{ display: "block", scrollMarginTop: "7rem" }} />

    <span id="what-does-the-connection-do" style={{ display: "block", scrollMarginTop: "7rem" }} />

    <span id="how-to-connect-your-ad-account" style={{ display: "block", scrollMarginTop: "7rem" }} />

    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.

    <Note>
      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.
    </Note>

    **If you skip this step:** campaign, ad set, and ad details may be missing, along with spend, impressions, and Meta-reported metrics.
  </Step>

  <Step title="Add Northbeam parameters to your ads">
    <span id="step-2-insert-northbeam-utm-parameters" style={{ display: "block", scrollMarginTop: "7rem" }} />

    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

    <span id="how-to-set-up-the-northbeam-utm-parameters" style={{ display: "block", scrollMarginTop: "7rem" }} />

    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.

    <Frame caption="Build a URL parameter > Custom parameters">
      <img src="https://mintcdn.com/northbeam/EpMPeQ8Ec2Yrg9EI/images/readme/4ba9e613-Screenshot_2025-05-13_at_9.33.31_AM.png?fit=max&auto=format&n=EpMPeQ8Ec2Yrg9EI&q=85&s=679c42fadd8721c21b8a0af6b106fa3a" alt="Build a URL Parameter > Custom Parameters" style={{ maxWidth: "560px", maxHeight: "440px", width: "auto", height: "auto", margin: "0 auto" }} data-og-width="777" width="777" data-og-height="429" height="429" data-path="images/readme/4ba9e613-Screenshot_2025-05-13_at_9.33.31_AM.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/northbeam/EpMPeQ8Ec2Yrg9EI/images/readme/4ba9e613-Screenshot_2025-05-13_at_9.33.31_AM.png?w=280&fit=max&auto=format&n=EpMPeQ8Ec2Yrg9EI&q=85&s=46e39419ee985a186842fc0517036e16 280w, https://mintcdn.com/northbeam/EpMPeQ8Ec2Yrg9EI/images/readme/4ba9e613-Screenshot_2025-05-13_at_9.33.31_AM.png?w=560&fit=max&auto=format&n=EpMPeQ8Ec2Yrg9EI&q=85&s=43f8c5ab882db119ef54614dc02e0b55 560w, https://mintcdn.com/northbeam/EpMPeQ8Ec2Yrg9EI/images/readme/4ba9e613-Screenshot_2025-05-13_at_9.33.31_AM.png?w=840&fit=max&auto=format&n=EpMPeQ8Ec2Yrg9EI&q=85&s=ee36f35cfdb0b1bac0c1e7b51dc3e260 840w, https://mintcdn.com/northbeam/EpMPeQ8Ec2Yrg9EI/images/readme/4ba9e613-Screenshot_2025-05-13_at_9.33.31_AM.png?w=1100&fit=max&auto=format&n=EpMPeQ8Ec2Yrg9EI&q=85&s=0a00c972ee78d953ede3db67450d3e08 1100w, https://mintcdn.com/northbeam/EpMPeQ8Ec2Yrg9EI/images/readme/4ba9e613-Screenshot_2025-05-13_at_9.33.31_AM.png?w=1650&fit=max&auto=format&n=EpMPeQ8Ec2Yrg9EI&q=85&s=47050c572bc89dfcea37e91ee7e0031d 1650w, https://mintcdn.com/northbeam/EpMPeQ8Ec2Yrg9EI/images/readme/4ba9e613-Screenshot_2025-05-13_at_9.33.31_AM.png?w=2500&fit=max&auto=format&n=EpMPeQ8Ec2Yrg9EI&q=85&s=969720842c0a7b0937ae12fcf95787b6 2500w" />
    </Frame>

    <Warning>
      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.
    </Warning>

    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.

    <AccordionGroup>
      <Accordion title="Watch a walkthrough">
        <iframe src="https://www.loom.com/embed/dfd6bbb850b2426eaaf8b74315986575?sid=5eede71e-445c-4490-8f4c-6aed047b5eb6" width="100%" height="450" allowfullscreen />
      </Accordion>
    </AccordionGroup>

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

    <table>
      <thead>
        <tr>
          <th>
            Platform
          </th>

          <th>
            Supported Parameters
          </th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            **Triple Whale**
          </td>

          <td>
            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}}`
          </td>
        </tr>

        <tr>
          <td>
            **Hyros**
          </td>

          <td>
            `fbc_id={{adset.id}}&h_ad_id={{ad.id}}`
          </td>
        </tr>

        <tr>
          <td>
            **Rockerbox**
          </td>

          <td>
            `fb_campaignid={{campaign.id}}&fb_adsetid={{adset.id}}&fb_adid={{ad.id}}`
          </td>
        </tr>

        <tr>
          <td>
            **Wicked Reports**
          </td>

          <td>
            `WickedSource=Facebook&WickedID={{ad.id}}`
          </td>
        </tr>
      </tbody>
    </table>

    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:

    <span id="option-1-northbeam-redirect-link" style={{ display: "block", scrollMarginTop: "7rem" }} />

    <span id="option-2-preserve-the-northbeam-utm-parameters" style={{ display: "block", scrollMarginTop: "7rem" }} />

    * **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.
  </Step>

  <Step title="Confirm tracking">
    * **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

    <span id="-how-to-confirm-your-meta-ads-are-tracking-properly" style={{ display: "block", scrollMarginTop: "7rem" }} />

    <span id="-step-by-step-verify-utms-+-pixel-with-a-live-ad-preview" style={{ display: "block", scrollMarginTop: "7rem" }} />

    <span id="1-get-a-live-preview-link" style={{ display: "block", scrollMarginTop: "7rem" }} />

    <span id="2-test-the-link" style={{ display: "block", scrollMarginTop: "7rem" }} />

    <span id="don’t-see-the-ad" style={{ display: "block", scrollMarginTop: "7rem" }} />

    <span id="3-verify-utms-and-pixel-via-developer-tools" style={{ display: "block", scrollMarginTop: "7rem" }} />

    <span id="utm-validation" style={{ display: "block", scrollMarginTop: "7rem" }} />

    <span id="pixel-validation" style={{ display: "block", scrollMarginTop: "7rem" }} />

    <span id="-what-this-means" style={{ display: "block", scrollMarginTop: "7rem" }} />

    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.

    <AccordionGroup>
      <Accordion title="See screenshots of each step">
        <Frame caption="Share a link from the ad preview">
          <img src="https://mintcdn.com/northbeam/EpMPeQ8Ec2Yrg9EI/images/readme/a82db463-Screenshot_2025-04-10_at_11.01.14_PM.png?fit=max&auto=format&n=EpMPeQ8Ec2Yrg9EI&q=85&s=21d61c28dfd99e87bc056604a9efeab8" alt="Meta Ads Manager preview with Share a link option" style={{ maxWidth: "560px", maxHeight: "440px", width: "auto", height: "auto", margin: "0 auto" }} width="1160" height="672" data-path="images/readme/a82db463-Screenshot_2025-04-10_at_11.01.14_PM.png" />
        </Frame>

        <Frame caption="The nbt value in the first Northbeam request's Payload">
          <img src="https://mintcdn.com/northbeam/EpMPeQ8Ec2Yrg9EI/images/readme/2e13d764-Screenshot_2025-04-10_at_11.06.31_PM.png?fit=max&auto=format&n=EpMPeQ8Ec2Yrg9EI&q=85&s=0409b5152b85af1603bf508cd7977198" alt="Click the first 'Network' request, then look in the 'Payload'" style={{ maxWidth: "560px", maxHeight: "440px", width: "auto", height: "auto", margin: "0 auto" }} width="676" height="46" data-path="images/readme/2e13d764-Screenshot_2025-04-10_at_11.06.31_PM.png" />
        </Frame>

        <Frame caption="It's normal to see several requests. Look for the one with pv in the Payload.">
          <img src="https://mintcdn.com/northbeam/EpMPeQ8Ec2Yrg9EI/images/readme/12aa2af0-Screenshot_2025-04-11_at_11.44.04_AM.png?fit=max&auto=format&n=EpMPeQ8Ec2Yrg9EI&q=85&s=0fb888f99a76de4ae6e6c3489f46d1b4" alt="Network tab with multiple Northbeam collector requests, one showing pv in the Payload" style={{ maxWidth: "560px", maxHeight: "440px", width: "auto", height: "auto", margin: "0 auto" }} width="827" height="271" data-path="images/readme/12aa2af0-Screenshot_2025-04-11_at_11.44.04_AM.png" />
        </Frame>
      </Accordion>

      <Accordion title="How to open Developer Tools in your browser">
        **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.
      </Accordion>

      <Accordion title="Watch a walkthrough">
        <iframe src="https://www.loom.com/embed/a155e0324835438e87965ef143e94953?sid=111298c7-0567-45c5-9e2b-51ac50ef4581" width="100%" height="450" allowfullscreen />
      </Accordion>
    </AccordionGroup>

    If any check fails, see [Troubleshooting Northbeam data](/docs/troubleshooting-tracking-issues).
  </Step>
</Steps>

<Note>
  **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).
</Note>

## Optional Meta features

<span id="clicks-+-deterministic-views-c+dv" style={{ display: "block", scrollMarginTop: "7rem" }} />

<span id="northbeam-apex-for-meta" style={{ display: "block", scrollMarginTop: "7rem" }} />

These are separate from the setup above and need their own configuration.

<CardGroup cols={2}>
  <Card title="Clicks + Deterministic Views (C+DV)" icon="eye" href="/docs/clicks-deterministic-views">
    An attribution model that credits Meta ads people saw but didn't click, using verified view data.
  </Card>

  <Card title="Northbeam Apex for Meta" icon="bullseye" href="/docs/setting-up-apex">
    Sends Northbeam attribution back to Meta so it can optimize toward it. Runs alongside your Pixel and Conversions API.
  </Card>
</CardGroup>

<span id="7-why-doesnt-meta-reported-purchases-in-northbeam-match-in-platform" style={{ display: "block", scrollMarginTop: "7rem" }} />

## Need help?

<CardGroup cols={2}>
  <Card title="Meta Ads FAQ" icon="circle-question" href="/docs/channels/meta/faq">
    Common Meta setup and reporting questions.
  </Card>

  <Card title="Troubleshooting Northbeam data" icon="wrench" href="/docs/troubleshooting-tracking-issues">
    Start here if a check above fails.
  </Card>
</CardGroup>