Store/Update AdCosts

This API request stores and updates ad cost data for a specific site using the HTTP method PUT. The request includes the following parameters:

Path Parameters:

SiteIdstringRequired

The ID of the site for which to add or update ad cost data

Headers:

AuthorizationstringRequired

The authorization token for accessing the API. The header value should be set to "Bearer {your-access-token}", where {your-access-token} is the access token assigned to the user.

Request Body (JSON payload):

The data containing the ad cost information to store or update. The payload should include the following parameters:

CaptureDateIsostringRequired

The ISO 8601 date when the ad cost was captured (format: yyyy-MM-dd). Should not be a future date.

CostdoubleRequired

The cost of the ad.

CurrencyCodestringRequired

The currency code for the ad. Must be valid and non-empty. Examples include GBP, USD, EUR

Impressionsint

The number of times the ad was displayed.

Clicksint

The number of clicks generated by the ad.

MarketingSourcestringRequired

The source of the marketing platform. Only custom sources are accepted. If you wish to use one of our supported cost ingestions then please contact customer support.

AdCostTypestringRequired

The type of ad cost. Must be one of the following values:

AdCostType	Description
Affiliate	Affiliate marketing costs such as Awin, or ShareASale
PayPerClick	Pay-per-click advertising costs such as Google Ads, Bing Ads
SocialMedia	Social media advertising costs on platforms such as Facebook, Instagram, and LinkedIn
ContentDiscovery	Content discovery platform costs such as Taboola, Outbrain
Programmatic	Programmatic ad buying costs such as The Trade Desk
DemandSidePlatform	Costs from demand-side platforms (DSP) such as Amazon DSP, Google DV360
RetargetingAndPersonalizedAdvertisingPlatform	Retargeting or personalized ad platform costs such as Criteo and AdRoll

CampaignIdentifiersArrayRequired

Campaign Identifiers provide a way to attribute ad costs to specific campaign levels. These identifiers allow for detailed cost tracking, enabling you to view ad spend at a highly granular level for each day.

An array of campaign identifiers. Each item in the array should include the following parameters:

IdentifierNamestringRequired

The name for the campaign identifier.

IdentifierValuestringRequired

The value for the campaign identifier.

ImportanceintRequired

Hierarchical importance (1 = most important/granular e.g. A Keyword).

You must provide at least one campaign idenfitier and it should help make the ad cost unique for the given date supplied.

There are many benefits to supplying more granular levels of identifiers:

Detailed Cost Analysis: Campaign Identifiers help separate costs across multiple campaigns and ads running simultaneously. By differentiating ads at various levels, you can gain a more dynamic and specific view of ad spend in reports.
ID-to-Name Mapping: Each identifier includes both an ID and a name, so campaign segments in reports display meaningful names rather than just IDs, providing a clearer view of ad performance.
Integration with Other Data: When following our guide on setting query string parameters, you can connect ad costs to related events like form submissions and revenue. See our URL tagging documentation for more information on this integration.

The following example data shows various levels of campaign identifiers and their usage:

Identifier Name	Identifier Value	Importance
CampaignLevelId	123	10
CampaignLevelValue	example campaign name	9
AdLevel1Id	456	8
AdLevel1Value	example ad group name	7
AdLevel2Id	789	6
AdLevel2Value	example ad name	5
AdLevel3Id	098	4
AdLevel3Value	example creative name	3
KeywordId	765	2
KeywordValue	example keyword example	1

AdditionalPropertiesArray

An array of additional properties. Each item should include the following parameters:

NamestringRequired

The name of the additional property.

ValuestringRequired

The value of the additional property.

Replace {siteId} in the URL endpoint with the appropriate ID for the site, and replace {your-access-token} in the authorization header with your access token.

Request

PUT

{siteId}/adcost/upload

curl -X PUT \
  'https://rest.rulerapi.com/v1/{siteId}/adcost/upload' \
  -H 'Authorization: Bearer {your-access-token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "CaptureDateIso": "{captureDateIso}",
    "Cost": "{cost}",
    "CurrencyCode": "{currencyCode}",
    "Impressions": "{impressions}",
    "Clicks": "{clicks}",
    "MarketingSource": "{marketingSource}",
    "AdCostType": "{adCostType}",
    "CampaignIdentifiers": [
      {
        "IdentifierName": "{identifierName}",
        "IdentifierValue": "{identifierValue}",
        "Importance": "{importance}"
      }
    ],
    "AdditionalProperties": [
      {
        "Name": "{name}",
        "Value": "{value}"
      }
    ]
  }'

Response

Status: 202

API Thresholds

maxRequestsPerSecond: 1000, maxConcurrentRequests: 1000