Campaign Metrics API

This section provides detailed information about the Campaign Metrics API in Retail Media Reporting.

Overview

The Campaign Metrics API retrieves campaign performance metrics for a specific supplier and retailer within a date range. This API provides comprehensive insights into the performance of your retail media campaigns, including financial metrics, performance indicators, and attribution data.

Authentication

This API uses OAuth 2.0 client credentials flow for authentication. See the Authentication section for detailed instructions.

API Endpoint

Method: GET

URL: {BASE_URL}/retail-media/supplier/{supplierId}/retailers/{retailerId}/campaign-metrics

Path Parameters

Parameter	Type	Description
supplierId	string	The supplier identifier
retailerId	string	The retailer identifier

Query Parameters

Parameter	Type	Required	Description
fromDate	string	Yes	Start date in YYYY-MM-DD format
toDate	string	Yes	End date in YYYY-MM-DD format
page	number	No	Page number for pagination

Request Headers

Authorization: Bearer {access_token}
Content-Type: application/json

Response

Success Response

Status Code: 200 OK

{
  "status": "success",
  "message": "Campaign metrics retrieved successfully",
  "errorCode": "",
  "data": [
    {
      "id": "campaign_789",
      "name": "Spring Sale Campaign",
      "startDate": "2024-03-01",
      "endDate": "2024-03-31",
      "totalBudget": 10000.00,
      "dailyCap": 500.00,
      "spentCredits": 8500.00,
      "discount": 250.00,
      "sponsoredUnit": 150,
      "sponsoredRevenue": 25000.00,
      "dailySpentCredits": 300.00,
      "hasActiveAdSet": true,
      "statuses": 10,
      "campaignStatus": "active",
      "remainingBudget": 1500.00,
      "accountCreditsSpent": 8500.00,
      "attributedClicks": 1200,
      "clicks": 1500,
      "impressions": 50000,
      "salesCount": 75,
      "salesValue": 25000.00,
      "spent": 8500.00,
      "roas": 2.94,
      "avgCTR": 3.0,
      "avgCPC": 5.67,
      "avgCOS": 113.33,
      "avgCPM": 170.00,
      "ctr": 3.0,
      "cos": 113.33
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 1,
    "totalRecords": 1,
    "pageSize": 100
  },
  "metadata": {}
}

Available Metrics

The campaign metrics API provides comprehensive data about your campaigns, including performance indicators and financial metrics. Here's a detailed breakdown of the available metrics:

Metric	Description	Type	Aggregation
id	Unique identifier for the campaign	string	All-Time
name	Name of the campaign	string	All-Time
startDate	Campaign start date (YYYY-MM-DD)	string	All-Time
endDate	Campaign end date (YYYY-MM-DD)	string	All-Time
totalBudget	Total budget allocated for the campaign	number	All-Time
dailyCap	Daily spending limit for the campaign	number	All-Time
spentCredits	Total credits spent on the campaign (all time)	number	All-Time
discount	Discount amount applied to the campaign	number	Date Range
sponsoredUnit	Unit sales attributed to retail media ad sets	number	Date Range
sponsoredRevenue	Retailer revenue attributed to sponsored ad campaigns	number	Date Range
dailySpentCredits	Credits spent on the current day	number	All-Time
hasActiveAdSet	Whether campaign has active ad sets	boolean	All-Time
statuses	Status code (10: active, -10: inactive)	number	All-Time
campaignStatus	Human-readable campaign status	string	All-Time
remainingBudget	Remaining budget for the campaign	number	All-Time
accountCreditsSpent	Account credits spent	number	Date Range
attributedClicks	Number of attributed clicks (legacy)	number	Date Range
clicks	Total clicks on sponsored product/content	number	Date Range
impressions	Total impressions of sponsored product/content	number	Date Range
salesCount	Number of sales attributed to the campaign	number	Date Range
salesValue	Total value of sales	number	Date Range
spent	Total advertising spend across all CPC and CPM campaigns	number	Date Range
roas	Return on ad spend (ROAS = Sponsored Revenue / Advertising Spend)	number	Date Range
avgCTR	Average click-through rate (CTR = Clicks / Impressions)	number	Date Range
avgCPC	Average cost per click	number	Date Range
avgCOS	Average cost of sale (COS = Total Advertising Spend / Sponsored Revenue)	number	Date Range
avgCPM	Average cost per thousand impressions	number	Date Range
ctr	Click-through rate (legacy)	number	Date Range
cos	Cost of sale (legacy)	number	Date Range

Understanding the Metrics

The campaign metrics provide insights into various aspects of your campaign performance:

Performance Metrics

• Impressions: Total number of times your ads were displayed
• Clicks: Total number of clicks received
• CTR (Click-Through Rate): Ratio of clicks to impressions
• CPC (Cost per Click): Average cost for each click
• CPM (Cost per Mille): Cost per thousand impressions

Financial Metrics

• Total Budget: Total allocated budget for the campaign
• Spent: Total amount spent on the campaign
• Remaining Budget: Available budget remaining
• ROAS (Return on Ad Spend): Return on investment for the campaign
• COS (Cost of Sale): Cost per sale

Sales Metrics

• Sales Count: Number of sales attributed to the campaign
• Sales Value: Total value of sales generated
• Sponsored Units: Number of units sold through sponsored content

Example Usage (JavaScript)

// First, obtain an access token using OAuth 2.0 client credentials flow
const getAccessToken = async () => {
  const response = await fetch('{BASE_URL}/connect/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      client_id: 'YOUR_CLIENT_ID',
      client_secret: 'YOUR_CLIENT_SECRET',
      grant_type: 'client_credentials'
    })
  });
  
  const data = await response.json();
  return data.access_token;
};

// Then, make the API request
const getCampaignMetrics = async () => {
  const accessToken = await getAccessToken();
  
  const response = await fetch(
    '{BASE_URL}/retail-media/supplier/{supplierId}/retailers/{retailerId}/campaign-metrics?fromDate=2024-03-01&toDate=2024-03-31&page=1',
    {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  const data = await response.json();
  console.log(data);
};

Best Practices

1. Regular Monitoring: Check campaign metrics daily to ensure optimal performance
2. Budget Management: Monitor spent credits and remaining budget to prevent overspending
3. Performance Analysis: Use CTR and CPC metrics to optimize ad performance
4. ROAS Tracking: Monitor ROAS to ensure campaign profitability
5. Daily Cap Monitoring: Keep track of daily spent credits against daily caps
6. Status Tracking: Regularly check campaign status to ensure active campaigns are running as expected
7. Date Range Selection: Choose appropriate date ranges to identify trends and patterns
8. Pagination: Use pagination parameters to handle large datasets efficiently