### Create a Data Export Request

Source: https://docs.northbeam.io/docs/northbeam-api-data-export-1

Use these examples to initiate a data export. Metrics and attribution_options are mandatory fields.

```curl
curl --request POST \
     --url https://api.northbeam.io/v1/exports/data-export \
     --header 'Authorization: Basic <api_key>' \
     --header 'Data-Client-ID: <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
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": "<api_key>",
    "Data-Client-ID": "<client_id>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

--------------------------------

### Embed UTM Parameter Guide Video

Source: https://docs.northbeam.io/docs/tracking-for-snapchat-ads

HTML block containing the YouTube video embed for the UTM parameter step-by-step guide.

```html
<iframe width="560" height="315" src="https://www.youtube.com/embed/bnjQpwazReA?si=wy08-3TNWhc7sERP" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
```

--------------------------------

### Embed UTM Parameter Setup Video

Source: https://docs.northbeam.io/docs/setting-up-facebook-ads-tracking

HTML snippet to display the instructional video for setting up UTM parameters.

```html
<div style="position: relative; padding-bottom: 66.41509433962266%; height: 0;"><iframe src="https://www.loom.com/embed/dfd6bbb850b2426eaaf8b74315986575?sid=5eede71e-445c-4490-8f4c-6aed047b5eb6" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
```

--------------------------------

### Example JSON response for metrics

Source: https://docs.northbeam.io/docs/northbeam-api-data-export-1

The API returns a list of metrics with their respective IDs and labels.

```json
{
  "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"
    }
  ]
}
```

--------------------------------

### Fetch metrics via API

Source: https://docs.northbeam.io/docs/northbeam-api-data-export-1

Use these examples to retrieve available metrics. Replace <api_key> and <client_id> with your account credentials.

```curl
curl --request GET \
     --url https://api.northbeam.io/v1/exports/metrics \
     --header 'Authorization: Basic <api_key>' \
     --header 'Data-Client-ID: <client_id>' \
     --header 'accept: application/json'
```

```python
import requests

url = "https://api.northbeam.io/v1/exports/metrics"

headers = {
    "accept": "application/json",
    "Authorization": "<api_key>",
    "Data-Client-ID": "<client_id>"
}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### Example JSON Response for Attribution Models

Source: https://docs.northbeam.io/docs/northbeam-api-data-export-1

This is an example of the JSON response you will receive when fetching attribution models. It lists various models like 'Clicks only' and 'Last touch'.

```json
{
  "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"
    }
  ]
}
```

--------------------------------

### Install Northbeam Pixel

Source: https://docs.northbeam.io/docs/third-party-checkouts

Include this script in your storefront to enable session tracking. Replace `{DATA_CLIENT_ID}` with your actual Northbeam Data Client ID.

```html
<!-- 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 -->
```

--------------------------------

### Embedded Loom Video Guide

Source: https://docs.northbeam.io/docs/non-shopify-installation

This HTML snippet embeds a video guide from Loom, providing a visual walkthrough of Northbeam features.

```html
<div style="position: relative; padding-bottom: 69.65699208443272%; height: 0;"><iframe src="https://www.loom.com/embed/9649009bb9dc44fab06e492ab8379761?sid=37bdc0ac-c971-44db-b3fc-dea2be6a365e" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
```

--------------------------------

### Fetch breakdown labels via API

Source: https://docs.northbeam.io/docs/northbeam-api-data-export-1

Use these examples to retrieve available breakdown labels. Replace <api_key> and <client_id> with your account credentials.

```curl
curl --request GET \
     --url https://api.northbeam.io/v1/exports/breakdowns \
     --header 'Authorization: Basic <api_key>' \
     --header 'Data-Client-ID: <client_id>' \
     --header 'accept: application/json'
```

```python
import requests

url = "https://api.northbeam.io/v1/exports/breakdowns"

headers = {
    "accept": "application/json",
    "Authorization": "<api_key>",
    "Data-Client-ID": "<client_id>"
}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### Fetch All Available Metrics

Source: https://docs.northbeam.io/reference/get_metrics-1

Use this GET request to retrieve a list of all available metrics from the Northbeam API. Ensure your request includes the 'accept: application/json' header.

```shell
curl --request GET \
     --url https://api.northbeam.io/v1/exports/metrics \
     --header 'accept: application/json'
```

--------------------------------

### UTM Parameters Setup

Source: https://docs.northbeam.io/docs/non-integrated-channel-setup-spend-api-utms

Properly configuring UTM parameters is essential for Northbeam to accurately track and attribute revenue to your marketing efforts.

```APIDOC
## Setting up UTM Parameters

### Description
UTM parameters are captured in real-time by the Northbeam pixel when a visitor lands on your site. Accurate UTM setup from the start is critical as they cannot be changed retroactively.

### Required UTM Parameters

*   `utm_source`
*   `utm_medium`
*   `utm_campaign`

### Alignment with Spend API

*   For accurate spend and revenue alignment, the `utm_campaign` parameter must exactly match the `campaign_name` field from the Spend API.

### Recommended Practices

*   **`utm_source` and `utm_medium`**: While you can use any values, it's recommended to use platform names for clarity. Consistency in these values aids in grouping and labeling performance data.
*   **Uniqueness**: Ensure that each platform's traffic can be uniquely identified, typically through a distinct `utm_source` + `utm_medium` combination.

### Other Requirements

*   The [Northbeam Pixel](https://docs.northbeam.io/docs/add-pixel#-how-to-test-for-your-northbeam-pixel-on-any-web-page) must be 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 are supported.
*   Verify your connected domain in the Northbeam dashboard under **Settings → Profile**.
```

--------------------------------

### Handlebars for Output Label Formatting

Source: https://docs.northbeam.io/docs/non-integrated-channel-setup-spend-api-utms

Use Handlebars helpers to format data for output labels. This example applies a lowercase function to the campaign data.

```handlebars
{{#functions.lower}}{{data.adKey.campaign}}{{/functions.lower}}
```

--------------------------------

### GET /v1/orders

Source: https://docs.northbeam.io/reference/get_orders

Retrieves a list of orders from the Northbeam platform based on a provided start and end date.

```APIDOC
## GET /v1/orders

### Description
Fetch a list of orders from the Northbeam API.

### Method
GET

### Endpoint
https://api.northbeam.io/v1/orders

### Parameters
#### Query Parameters
- **start_date** (string) - Required - Start date of the form %Y-%m-%d. Defaults to 2001-01-01.
- **end_date** (string) - Required - End date of the form %Y-%m-%d. Defaults to 9999-01-01.

### Response
#### Success Response (200)
- Orders fetched

#### Error Responses
- **401** - Unauthenticated
- **500** - Could not fetch
```

--------------------------------

### Implement Tatari JavaScript Library

Source: https://docs.northbeam.io/docs/tracking-for-tatari

Add this script to the <head> section of your website to initialize Tatari tracking. Replace YOUR_TOKEN with your specific integration token.

```html
 <script>  
     !function(){try{!function(t,i){if(!i.version){window.tatari=i,i  
     .init=function(t,n){var e=function(t,n){i[n]=function(){t.push([  
     n].concat(Array.prototype.slice.call(arguments,0)))}};"track  
     pageview identify".split(" ")  
     .forEach(function(t){e(i,t)}),i._i=t,i.config=n,i.pageview()}  
     ,i.version="1.2.1"; var  
     n=t.createElement("script");n.type="text/javascript",n.async=!0  
     ,n.src="https://d2hrivdxn8ekm8.cloudfront.net/tag-manager/YOUR_TOKEN-latest.js";var e=t.getElementsByTagName("script")[0];e.parentNode.insertBefore(n,e)}}(document,window.tatari||[])}catch(t){console.log(t)}}();  
     tatari.init('YOUR_TOKEN');  
 </script>
```

--------------------------------

### GET /v1/exports/metrics

Source: https://docs.northbeam.io/reference/metrics

Retrieves a list of all available metrics from the Northbeam API.

```APIDOC
## GET /v1/exports/metrics

### Description
Fetches all available metrics from the Northbeam system.

### Method
GET

### Endpoint
https://api.northbeam.io/v1/exports/metrics

### Request Example
```bash
curl --request GET \
     --url https://api.northbeam.io/v1/exports/metrics \
     --header 'accept: application/json'
```

### Response
#### Success Response (200)
- **metrics** (array) - A list of available metrics.

#### Error Responses
- **401** - Unauthorized
- **429** - Too many requests
- **500** - Internal server error
```

--------------------------------

### GET /v1/exports/metrics

Source: https://docs.northbeam.io/reference/get_metrics-1

Retrieves a list of all available metrics from the Northbeam API.

```APIDOC
## GET /v1/exports/metrics

### Description
Fetch all available metrics from the Northbeam system.

### Method
GET

### Endpoint
https://api.northbeam.io/v1/exports/metrics

### Response
#### Success Response (200)
- **metrics** (array) - A list of available metrics.

#### Error Responses
- **401** - Unauthorized
- **429** - Too many requests
- **500** - Internal server error

### Request Example
```bash
curl --request GET \
     --url https://api.northbeam.io/v1/exports/metrics \
     --header 'accept: application/json'
```
```

--------------------------------

### Install Northbeam Pixel Script

Source: https://docs.northbeam.io/docs/non-shopify-installation

Embed this script in the `<head>` section of every page. Replace `{DATA_CLIENT_ID}` with your unique Northbeam Data Client ID. Do not modify any other part of the script.

```html
<!-- 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 -->
```

--------------------------------

### GET /v1/exports/data-export/result/{export_id}

Source: https://docs.northbeam.io/reference/data-exportresultexport_id

Retrieves the result of a specific data export by its unique identifier.

```APIDOC
## GET /v1/exports/data-export/result/{export_id}

### Description
Retrieves the result of a specific data export by its unique identifier.

### Method
GET

### Endpoint
https://api.northbeam.io/v1/exports/data-export/result/{export_id}

### Parameters
#### Path Parameters
- **export_id** (uuid) - Required - The unique identifier of the data export.

### Response
#### Success Response (200)
- **Data export result** - Returns the result of the data export.

#### Error Responses
- **401** - Unauthorized
- **429** - Too many requests
- **500** - Internal server error
```

--------------------------------

### Fetch All Available Attribution Models

Source: https://docs.northbeam.io/reference/attribution-models

Use this endpoint to retrieve a list of all available attribution models. Ensure you have the correct authentication headers.

```Shell
curl --request GET \
     --url https://api.northbeam.io/v1/exports/attribution-models \
     --header 'accept: application/json'
```

--------------------------------

### Fetch Attribution Models using Python

Source: https://docs.northbeam.io/docs/northbeam-api-data-export-1

This Python script demonstrates how to fetch available attribution models using the requests library. Replace `<api_key>` and `<client_id>` with your account-specific values.

```python
import requests

url = "https://api.northbeam.io/v1/exports/attribution-models"

headers = {
    "accept": "application/json",
    "Authorization": "<api_key>",
    "Data-Client-ID": "<client_id>"
}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### Breakdown labels JSON response structure

Source: https://docs.northbeam.io/docs/northbeam-api-data-export-1

Example of the JSON response returned by the breakdown labels endpoint.

```json
{
  "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"]
    }
  ]
}
```

--------------------------------

### GET /v1/spend

Source: https://docs.northbeam.io/reference

Retrieves a list of spend records based on specified date ranges or platform identifiers.

```APIDOC
## GET /v1/spend

### Description
Retrieves a list of spend records. You can filter by a specific date or a date range, and optionally filter by platform account, campaign, adset, or ad IDs.

### Method
GET

### Endpoint
https://api.northbeam.io/v1/spend

### Parameters
#### Query Parameters
- **date** (date) - Optional - The date of spend entries to search for (provide this OR date_start/date_end).
- **date_start** (date) - Optional - The start date for a range of spend entries (provide this with date_end OR use date).
- **date_end** (date) - Optional - The end date for a range of spend entries (provide this with date_start OR use date).
- **platform_account_id** (string) - Required - The Ad Platform Account ID to search for.
- **campaign_id** (string) - Optional - The Ad Platform's Campaign ID to search for.
- **adset_id** (string) - Optional - The Ad Platform's Adset ID to search for.
- **ad_id** (string) - Optional - The Ad Platform's Ad ID to search for.
- **page** (integer) - Optional - Page number for pagination (defaults to 1).
- **page_size** (integer) - Optional - Results per page (maximum 1000, defaults to 1000).

### Response
#### Success Response (200)
- **List** (array) - List of spend records.

#### Error Responses
- **401** - Authentication failed.
- **422** - The request body is invalid.
- **4XX/5XX** - An unexpected error occurred.
```

--------------------------------

### Fire Purchase Event Example

Source: https://docs.northbeam.io/docs/purchase-pixel

Use this JavaScript snippet to fire a purchase event. Ensure the payload is correctly structured as an object within curly braces. Values for prices, coupons, and customer IDs can be provided directly or with fallback defaults.

```javascript
<script type="application/javascript">
  window.Northbeam.firePurchaseEvent({
  id: "ORD98" || "Missing - unmatched order",
  totalPrice: 100 || 0,
  shippingPrice: 10 || 0,
  taxPrice: 5.5 || 0,
  coupons: "SALE20, FAMILY10" || "",
  currency: "USD" || "USD",
  customerId: "customer-93" || "UNKNOWN VISITOR",
  lineItems: [
    {
      productId: "SKU-0001" || "UNKNOWN PRODUCT",
      variantId: "0001-A" || "",
      productName: "Pants" || "UNKNOWN VARIANT",
      variantName: "Blue" || "",
      price: 10 || 0,
      quantity: 1 || 0,
    }]
	})
</script>
```

--------------------------------

### Using Google Tag Manager (GTM) for Customer Identification

Source: https://docs.northbeam.io/docs/third-party-checkouts

Instructions for setting up a GTM tag to capture customer email and pass it to Northbeam.

```APIDOC
## Option B — Google Tag Manager (GTM)

1. Create a **Data Layer Variable** in GTM for the customer email (e.g. `dlv - customer_email`).
2. Create a new **Custom HTML Tag** in GTM.
3. Paste the `identify()` snippet and reference your variable:

```javascript
   window.Northbeam.identify("email", "{{dlv - customer_email}}");
```

4. Set the trigger to fire on the checkout page where the email is captured.
5. **Publish** the GTM container.
```