PPC (Advertising)

Retrieve PPC advertising data across all Amazon ad types -- Sponsored Products (SP), Sponsored Brands (SB), and Sponsored Display (SD).

GET /ppc/get-list

Get PPC advertising data for campaigns, ad groups, keywords, products, and more.

Parameters

Name	Type	Required	Description
ppc_type	string	Yes	Ad type: sp (Sponsored Products), sb (Sponsored Brands), sd (Sponsored Display)
entity_type	string	Yes	Entity to retrieve (see table below)
per_page	integer	Yes	Results per page: 10, 20, 50, 100, 250, 500, 1000, 2000
currency	string	Yes	Currency code for monetary values (e.g. USD)
aggregate_mode	string	No	summary (default) or daily
start_date	string	No	Start date in YYYY-MM-DD format (defaults to 7 days ago)
end_date	string	No	End date in YYYY-MM-DD format (defaults to today)
campaign_id	string	No	Filter by campaign ID
ad_group_id	string	No	Filter by ad group ID
custom_filter	object	No	Advanced column-level filtering (see Schema endpoint)
account_title	string	No	Filter by account title
seller_id	string	No	Amazon seller ID (requires marketplace_id)
marketplace_id	string	No	Amazon marketplace ID (requires seller_id)
group_title	string	No	Filter by account group
filter_by	string	No	Field to filter: sku, asin, parent_asin
filter_value	string	No	Value to match (requires filter_by)

Entity Types by PPC Type

PPC Type	Supported Entity Types
sp (Sponsored Products)	campaigns, ad-groups, products, products-by-campaign, ad-keywords, search-terms, targets
sb (Sponsored Brands)	campaigns, ad-groups, ad-keywords
sd (Sponsored Display)	campaigns, ad-groups, products

Response

{
  "current_page": 1,
  "data": [
    {
      "campaign_name": "My SP Campaign",
      "impressions": 15420,
      "clicks": 312,
      "ctr": 2.02,
      "avg_cpc": 0.85,
      "spend": 265.20,
      "sales": 1240.50,
      "conversions": 28,
      "conversion_rate": 8.97,
      "acos": 21.38
    }
  ],
  "total": 45,
  "per_page": 50,
  "last_page": 1
}

Key Metrics

Field	Description
impressions	Total number of ad impressions
clicks	Total ad clicks
ctr	Click-through rate (%)
avg_cpc	Average cost per click
spend	Total advertising spend
sales	Attributed sales from ads
conversions	Number of conversions (orders)
conversion_rate	Conversion rate (%)
acos	Advertising Cost of Sales (%)

Examples

Python

import requests

headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}

# Get Sponsored Products campaigns
response = requests.get(
    "https://app.sellerlegend.com/api/ppc/get-list",
    headers=headers,
    params={
        "account_title": "My Store US",
        "ppc_type": "sp",
        "entity_type": "campaigns",
        "per_page": 100,
        "currency": "USD",
        "start_date": "2025-01-01",
        "end_date": "2025-01-31"
    }
)

campaigns = response.json()
for campaign in campaigns["data"]:
    print(f"{campaign['campaign_name']}: ACoS {campaign['acos']}%")

PHP

$token = "YOUR_ACCESS_TOKEN";

$params = http_build_query([
    "account_title" => "My Store US",
    "ppc_type" => "sp",
    "entity_type" => "campaigns",
    "per_page" => 100,
    "currency" => "USD",
    "start_date" => "2025-01-01",
    "end_date" => "2025-01-31"
]);

$ch = curl_init("https://app.sellerlegend.com/api/ppc/get-list?{$params}");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer {$token}"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

foreach ($response["data"] as $campaign) {
    echo "{$campaign['campaign_name']}: ACoS {$campaign['acos']}%\n";
}

JavaScript

const response = await fetch(
  "https://app.sellerlegend.com/api/ppc/get-list?" + new URLSearchParams({
    account_title: "My Store US",
    ppc_type: "sp",
    entity_type: "campaigns",
    per_page: 100,
    currency: "USD",
    start_date: "2025-01-01",
    end_date: "2025-01-31"
  }),
  {
    headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" }
  }
);

const campaigns = await response.json();
campaigns.data.forEach(c => {
  console.log(`${c.campaign_name}: ACoS ${c.acos}%`);
});

cURL

curl -G "https://app.sellerlegend.com/api/ppc/get-list" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "account_title=My Store US" \
  -d "ppc_type=sp" \
  -d "entity_type=campaigns" \
  -d "per_page=100" \
  -d "currency=USD" \
  -d "start_date=2025-01-01" \
  -d "end_date=2025-01-31"

Daily Breakdown

Use aggregate_mode=daily to get metrics broken down by date:

response = requests.get(
    "https://app.sellerlegend.com/api/ppc/get-list",
    headers=headers,
    params={
        "account_title": "My Store US",
        "ppc_type": "sp",
        "entity_type": "campaigns",
        "aggregate_mode": "daily",
        "per_page": 500,
        "currency": "USD",
        "start_date": "2025-01-01",
        "end_date": "2025-01-31"
    }
)

Filtering by Campaign or Ad Group

Drill down into specific campaigns or ad groups:

# Get ad groups for a specific campaign
response = requests.get(
    "https://app.sellerlegend.com/api/ppc/get-list",
    headers=headers,
    params={
        "account_title": "My Store US",
        "ppc_type": "sp",
        "entity_type": "ad-groups",
        "campaign_id": "CAMPAIGN_ID",
        "per_page": 100,
        "currency": "USD"
    }
)

# Get search terms for a specific ad group
response = requests.get(
    "https://app.sellerlegend.com/api/ppc/get-list",
    headers=headers,
    params={
        "account_title": "My Store US",
        "ppc_type": "sp",
        "entity_type": "search-terms",
        "campaign_id": "CAMPAIGN_ID",
        "ad_group_id": "AD_GROUP_ID",
        "per_page": 500,
        "currency": "USD"
    }
)

TIP

Use the Schema endpoint (GET /schema/get-filterable-columns) to discover which columns are available for custom_filter on PPC datatables.