Ad Set Summary Metrics API

This section provides detailed information about the Ad Set Summary Metrics API in Retail Media Reporting.

Overview

The Ad Set Summary Metrics API retrieves summary metrics for ad sets within a specific campaign. This API provides insights into the performance of your retail media ad sets, helping you track and analyze the effectiveness of your advertising sets across various dimensions.

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/{campaignId}/adset-summary-metrics

Path Parameters

Parameter	Type	Description
supplierId	string	The supplier identifier
retailerId	string	The retailer identifier
campaignId	string	The campaign 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": "Ad set summary metrics retrieved successfully",
  "errorCode": "",
  "data": [
    {
      "adsetId": "adset_456",
      "name": "Ad Set 1",
      "type": "Display",
      "strategy": "MaxClicks",
      "sponsoredRevenue": 15000.00,
      "roas": 3.0,
      "impressions": 30000,
      "clicks": 900,
      "sponsoredUnit": 90,
      "ctr": 3.0,
      "cos": 100.00,
      "spend": 5000.00,
      "discount": 250.00,
      "salesCount": 45,
      "salesValue": 15000.00,
      "accountCreditsSpent": 5000.00
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 1,
    "totalRecords": 1,
    "pageSize": 100
  },
  "metadata": {}
}

Available Metrics

The Ad Set Summary Metrics API provides comprehensive data about your ad sets, including performance indicators and financial metrics. Here's a detailed breakdown of the available metrics:

Metric	Description	Type	Aggregation
adsetId	Unique identifier for the ad set	string	All-Time
name	Name of the ad set	string	All-Time
type	The format of the ad (e.g., Display, Banner, Carousel)	string	All-Time
strategy	The bidding strategy used (e.g., MaxClicks, Bid)	string	All-Time
sponsoredRevenue	Total revenue generated from sponsored sales	number	Date Range
roas	Return on ad spend (ROAS = Sponsored Revenue / Advertising Spend)	number	Date Range
impressions	Total number of times the ad was displayed	number	Date Range
clicks	Total number of clicks received	number	Date Range
sponsoredUnit	Number of sponsored units sold	number	Date Range
ctr	Click-through rate (CTR = Clicks / Impressions)	number	Date Range
cos	Cost of Sales (COS = Total Advertising Spend / Sponsored Revenue)	number	Date Range
spend	Total amount spent on the ad set	number	Date Range
discount	Discount amount applied to the ad set	number	Date Range
salesCount	Number of sales attributed to the ad set	number	Date Range
salesValue	Total value of sales from the ad set	number	Date Range
accountCreditsSpent	Account credits spent on the ad set	number	Date Range

Understanding the Metrics

The Ad Set Summary Metrics provide insights into various aspects of your ad set 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
• Sponsored Units: Number of units sold through sponsored ads

Financial Metrics

• Spend: Total amount spent on the ad set
• ROAS (Return on Ad Spend): Return on investment for the ad set
• COS (Cost of Sale): Cost per sale
• Discount: Discount amount applied to the ad set

Sales Metrics

• Sales Count: Number of sales attributed to the ad set
• Sales Value: Total value of sales generated
• Sponsored Revenue: Revenue from sponsored units

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 getAdSetSummaryMetrics = async () => {
  const accessToken = await getAccessToken();
  
  const response = await fetch(
    '{BASE_URL}/retail-media/supplier/{supplierId}/retailers/{retailerId}/campaign/{campaignId}/adset-summary-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 ad set metrics daily to ensure optimal performance
2. Performance Analysis: Use CTR and ROAS metrics to optimize ad performance
3. Budget Management: Track spend against performance metrics
4. Ad Type Analysis: Compare performance across different ad types (Display, Banner, Carousel)
5. Strategy Optimization: Analyze different bidding strategies to find the most effective approach
6. Sales Attribution: Monitor sponsored units and revenue to understand conversion effectiveness
7. Date Range Selection: Choose appropriate date ranges to identify trends and patterns
8. Pagination: Use pagination parameters to handle large datasets efficiently