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

# Custom

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

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

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

***

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

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

<Tabs>
  <Tab title="In your site's code">
    <Steps>
      <Step title="Copy the pixel">
        Copy the **Northbeam Pixel** from [Settings → Northbeam Pixel and Event Tracking](https://dashboard.northbeam.io/settings/tracking-script-tags).
      </Step>

      <Step title="Paste it in the head of every page">
        Paste it into the `<head>` section of your site's template, so it loads on every page.
      </Step>

      <Step title="Publish">
        Deploy or publish your site.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Google Tag Manager">
    <Steps>
      <Step title="Create a Custom HTML tag">
        In Google Tag Manager, go to **Tags → New** and set **Tag Type** to **Custom HTML**.
      </Step>

      <Step title="Paste the pixel">
        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.
      </Step>

      <Step title="Fire it on all pages">
        Set the trigger to **All Pages**.
      </Step>

      <Step title="Publish the container">
        Click **Submit** to publish. Unpublished changes don't track anything.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Warning>
  **Don't change the script.** Paste it exactly as it appears in your dashboard.
</Warning>

<Accordion title="Using a Content Security Policy (CSP)?">
  If your site uses a CSP, its `connect-src` must allow your `i.` subdomain. Add either:

  * `*.your-store.com`, or
  * `i.your-store.com`
</Accordion>

<Accordion title="Need the script without the dashboard?">
  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}
  <!-- Begin: Northbeam pixel -->
  <script>(function(){var t;(n=t=t||{}).A="identify",n.B="trackPageView",n.C="fireEmailCaptureEvent",n.D="fireCustomGoal",n.E="firePurchaseEvent",n.F="trackPageViewInitial",n.G="fireSlimPurchaseEvent",n.H="identifyCustomerId";var n="//j.northbeam.io/ota-sp/{DATA_CLIENT_ID}.js";function r(n){for(var e=[],t=1;t<arguments.length;t++)e[t-1]=arguments[t];i.push({fnName:n,args:e})}var e,i=[],a=((e={})[t.F]=function(n){r(t.F,n)},(a={_q:i})[t.A]=function(n,e){return r(t.A,n,e)},a[t.B]=function(){return r(t.B)},a[t.C]=function(n,e){return r(t.C,n,e)},a[t.D]=function(n,e){return r(t.D,n,e)},a[t.E]=function(n){return r(t.E,n)},a[t.G]=function(n){return r(t.G,n)},a[t.H]=function(n,e){return r(t.H,n,e)},Object.assign(function(n){for(var e=[],t=1;t<arguments.length;t++)e.push(arguments[t]);return r.apply(null,[n].concat(e))},a));window.Northbeam=a,(a=document.createElement("script")).async=!0,a.src=n,document.head.appendChild(a),e.trackPageViewInitial(window.location.href);})()</script>
  <!-- End: Northbeam pixel -->
  ```
</Accordion>

***

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

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

<Card title="Set up purchase events" icon="cart-shopping" href="/docs/purchase-pixel">
  Full instructions, examples, field reference, and testing steps.
</Card>

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

***

## Test your setup

Check that you have:

* The **Northbeam Pixel** in the `<head>` 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).

<span id="3-add-optional-tracking" style={{ display: "block", scrollMarginTop: "7rem" }} />

## Optional tracking

Add these only if they apply to your store.

<CardGroup cols={2}>
  <Card title="Custom Goals" icon="bullseye" href="/docs/setting-up-custom-goals">
    Track other actions, like sign-ups, add-to-carts, or form submissions.
  </Card>

  <Card title="Page View Events" icon="eye" href="/docs/page-view-events">
    Only for single-page apps (for example, Next.js or React Router). Most sites don't need this.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can I install Northbeam through Google Tag Manager?">
    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.
  </Accordion>

  <Accordion title="My store is headless but uses Shopify's checkout. Which guide do I follow?">
    Follow the [Shopify](/docs/shopify-installation) guide.
  </Accordion>

  <Accordion title="Where's the list of every pixel function?">
    See [All Pixel Functions](/docs/optional-additional-methods).
  </Accordion>
</AccordionGroup>
