What is Custom Spend?

As briefly covered in the Getting Started page, our Custom 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.

Functionality

The Custom Spend API allows for

upload of new entries,
updating of existing entries,
deletion of existing entries,
listing of uploaded entries

With this flexiblity, our customers can programmatically modify their spend data for platforms we do not yet natively support!

When to use Custom Spend API instead of Custom Spend Sheets

Custom Spend Sheets allow you to share spend data for ad platforms that we do not natively support via a Google Sheet. This can be rather cumbersome when there are either:

a lot of ad platforms to support via custom sheets, or
a lot of campaigns (deeper levels) of hierarchy per platform.
Custom Spend API was developed to address these difficulties. Consider using the Custom Spend API instead if:
you have developer resources that can assist you for implementation, and
your spend is complex enough that manually updating the custom sheet periodically will be burdensome.

	Custom Spend Sheet	Custom Spend API
Import ad spend data from any platform	✅	✅
No dev resources required	✅	❌
Minimal ongoing overhead to support	❌	✅

Custom Spend Attributes

Each custom 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, albeit in much more detail here.

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 or 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 on (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 on (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 Custom 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 Custom 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 development of this API was to avoid using Custom Spend sheets. Custom 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 custom sheets, or (ii) a lot of campaigns (deeper levels) of heirarchy per platform. Consider using the Custom Spend API if developer resources are available and the time spent using the custom sheets is burdensome and can be leveraged otherwise!

Further Help

If you have any questions reach out to Customer Success at [email protected]!