Data reference

Introduction

Amazon Ads is Amazon’s retail-media advertising platform, unifying three sponsored ad surfaces — Sponsored Products, Sponsored Brands, and Sponsored Display — for sellers, vendors, and agencies advertising on Amazon’s marketplace and partner properties. The platform supports CPC and vCPM (viewable CPM) payment models across awareness, consideration, and conversion objectives, with bidding tied to keywords, ASINs, audiences, and product categories. The connector imports campaign structure and performance metrics from all three sub-APIs through the Amazon Ads Reporting API v3, normalizing them into a single unified reporting format. As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration. To connect this data source, see How to connect Amazon Ads to Adriel.

Data refresh strategy

Architecture data

Architecture covers ad accounts, campaigns, ad groups (ad sets), ads, and keywords. It refreshes once daily at 5:00 PM UTC. On data source creation, the cache fills with 60 days of historical data for the ad account, campaign, ad set, ad, and keyword levels.

Reports data

Reports include daily performance metrics for ad accounts, campaigns, ad groups, ads, and keywords across Sponsored Products, Sponsored Brands, and Sponsored Display. Cache-only. Report data comes from cached daily performance snapshots — dashboard queries always read from the last snapshot, never live from Amazon Ads. Metrics based on uniqueness (such as reach) can be overvalued when viewed over a date range longer than one day, because uniqueness is computed per snapshot rather than across the full range. Refresh schedule. Reports refresh on three schedules:

1:00 AM UTC daily — syncs the last 9 days for the campaign, ad set, and ad levels
9:00 AM UTC every 2 days — syncs the last 9 days for the keyword level
6:00 PM UTC every 10 days — syncs the last 17 days for the campaign, ad set, ad, and keyword levels

Data is reliable within the cache sync period. Data outside this range may be incomplete or inaccurate due to legacy caching behavior.

Architecture levels

Ad account → Campaign → Ad group (ad set) → Ad → Keyword

Date range limits

Breakdown	Max range
Daily	93 days
Weekly	1 year
Monthly	2 years

Attribution windows

Amazon Ads reports conversions across four click-attribution windows: 1d, 7d, 14d, and 30d. Most conversion and sales metrics are exposed as one variant per window (Amazon Ads Reporting API v3) — for example, purchases exist as purchases1d, purchases7d, purchases14d, and purchases30d. The exact metric set varies by sub-API (see the metric categories below). Because Amazon’s console and the API can default to different attribution windows, match the window when comparing Amazon’s numbers to a dashboard widget for like-for-like results.

Metrics

How to read the columns Data type uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean. API Key in code style like impressions is the literal Amazon Ads API field name. Italic text describes how a value is produced when it doesn’t map cleanly to a single API field.

Because Amazon Ads unifies three ad surfaces, the metrics available on a given row depend on which sub-API the ad belongs to. Querying a metric on the wrong sub-API returns empty values.

Delivery and cost

Metric	Description	Data type	API Key
Impressions	Total times the ads were shown.	Number	`impressions`
Clicks (all)	Total clicks.	Number	`clicks`
CTR	Click-through rate.	Percentage	`clickThroughRate`
CPC	Cost per click.	Currency	`costPerClick`
CPM	Cost per thousand impressions.	Currency	Adriel-computed (spend ÷ impressions × 1,000)
Ad spend	Total amount spent.	Currency	`cost`

Sales and conversions (Sponsored Products)

The largest metric set — ASIN-level performance and search-term reporting.

Metric	Description	Data type	API Key
Purchases (1d / 7d / 14d / 30d)	Attributed purchases by attribution window.	Number	`purchases1d` / `purchases7d` / `purchases14d` / `purchases30d`
Purchases (Same SKU)	Purchases of the advertised SKU only.	Number	`purchasesSameSku`
Sales	Total attributed sales revenue.	Currency	`sales`
Sales (Same SKU)	Sales of the advertised SKU only.	Currency	`attributedSalesSameSku`
Sales (Other SKU)	Sales of other SKUs from the advertised brand.	Currency	`salesOtherSku`
Units sold (clicks)	Units sold attributed to clicks.	Number	`unitsSoldClicks`
Units sold (Same SKU)	Units of the advertised SKU sold.	Number	`unitsSoldSameSku`
Units sold (Other SKU)	Units of other SKUs sold.	Number	`unitsSoldOtherSku`
ACOS (clicks)	Advertising cost of sale, click-attributed.	Percentage	`acosClicks`
ROAS (clicks)	Return on ad spend, click-attributed.	Ratio	`roasClicks`
Add to list	Add-to-list events.	Number	`addToList`
Qualified borrows	Kindle Unlimited qualified borrows.	Number	`qualifiedBorrows`
Royalty qualified borrows	Royalty-eligible Kindle borrows.	Number	`royaltyQualifiedBorrows`
Kindle edition normalized	Kindle edition normalized pages read.	Number	`kindleEditionNormalized`

Brand awareness (Sponsored Brands)

Adds video and brand-awareness metrics.

Metric	Description	Data type	API Key
Video 5-second view rate	Share of impressions where the video played at least 5 seconds.	Percentage	`video5SecondViewRate`
Video complete views	Video plays reaching 100% completion.	Number	`videoCompleteViews`
Branded searches	Searches for the advertised brand following ad exposure.	Number	`brandedSearches`
Detail page views	Views of the advertised product detail page.	Number	`detailPageViews`
New-to-brand metrics	Conversions from customers new to the brand.	Number	`newToBrand` (multiple variants)*

View-through and engagement (Sponsored Display)

Adds view-through and engagement metrics.

Metric	Description	Data type	API Key
Impressions (viewable)	Viewable impressions.	Number	`impressionsViews`
Add to cart (views)	View-through add-to-cart events.	Number	`addToCartViews`
Cumulative reach	Unique users reached cumulatively.	Number	Sponsored Display-specific
Lead form opens	Lead-generation form opens.	Number	`leadFormOpens`
Link outs	Clicks to an external destination.	Number	`linkOuts`

Conversions and attribution (cross-API)

Metric	Description	Data type	API Key
Conversions	Total attributed conversions (defaults to purchases when no conversion event is set).	Number	`purchases`, `attributedConversions1d`, `attributedConversions7d`, `attributedConversions14d`, `attributedConversions30d`
Conversion value	Monetary value of attributed conversions.	Currency	`sales`, `attributedSales1d`, `attributedSales7d`, `attributedSales14d`, `attributedSales30d`
Revenue	Monetary value of attributed conversions.	Currency	`sales`, `attributedSales1d`, `attributedSales7d`, `attributedSales14d`, `attributedSales30d`
Attributed conversions (1d / 7d / 14d / 30d)	Conversions by attribution window.	Number	`attributedConversions1d` / `attributedConversions7d` / `attributedConversions14d` / `attributedConversions30d`
Attributed units ordered (1d / 7d / 14d / 30d)	Units ordered by attribution window.	Number	`attributedUnitsOrdered1d` / `attributedUnitsOrdered7d` / `attributedUnitsOrdered14d` / `attributedUnitsOrdered30d`

Custom conversion events

For each conversion event configured in the connected Amazon Ads account, Adriel auto-generates a count metric plus derived KPIs. Events appear only when the underlying event is active in the account.

Pattern	Description	Data type	API Key
`Amazon Ads: [event]`	Count of the conversion event.	Number	Resolved from Amazon conversions
`Amazon Ads: [event]: Conversion value`	Monetary value of the event.	Currency	Resolved from Amazon conversions
`Amazon Ads: [event]: CPA`	Cost per action.	Currency	Adriel-computed (spend ÷ count)
`Amazon Ads: [event]: ROAS`	Return on ad spend.	Ratio	Adriel-computed (value ÷ spend)
`Amazon Ads: [event]: CVR`	Conversion rate.	Percentage	Adriel-computed (count ÷ clicks × 100%)

Campaign structure metadata

Metric	Description	Data type	API Key
Ad account name	Name of the ad account.	Text	`accountInfo.name`
Campaign name	Campaign name.	Text	`campaignName`
Campaign ID	Campaign identifier.	Text	`campaignId`
Ad group name	Ad group name.	Text	`adGroupName`
Ad group ID	Ad group identifier.	Text	`adGroupId`
Ad ID	Ad identifier.	Text	`adId`
Portfolio ID	Portfolio identifier.	Text	`portfolioId`
Advertised ASIN	Advertised ASIN.	Text	`advertisedAsin`
Advertised SKU	Advertised SKU.	Text	`advertisedSku`
Search term	Search query that triggered the ad.	Text	`searchTerm`
Match type	Broad, Phrase, or Exact.	Text	`matchType`
Keyword name	Keyword text (search campaigns only).	Text	`keywordText`
Keyword bid	Current bid on the keyword.	Currency	`keywordBid`
Bidding strategy	Campaign bidding strategy.	Text	`campaignBiddingStrategy`
Campaign budget	Campaign budget fields.	Currency	`campaignBudget` (multiple fields)*
Status	Campaign state and serving status.	Text	`state`, `serviceStatus`, `servingStatus`
Objective	Campaign objective.	Text	`objective`
Starts	Campaign start date.	Date	`startDate`
Ends	Campaign end date.	Date	`endDate`

Breakdowns

Structure

Breakdown	Description	API Key
Ad account	Group by Amazon Ads profile / ad account.	`profileId`
Campaign	Group by campaign.	`campaignName`
Ad group	Group by ad group (ad set).	`adGroupName`
Ad	Group by ad.	`adId`
Keyword	Group by keyword (search campaigns only).	`keywordText`

Amazon-specific

Breakdown	Description	API Key
Search term	Search query that triggered the ad (Sponsored Products).	`searchTerm`
Match type	Broad, Phrase, or Exact (Sponsored Products).	`keywordMatchType`
ASIN	Advertised ASIN.	`advertisedAsin`
Placement	Where the ad served.	`platformPlacement`
Portfolio	Portfolio grouping campaigns.	`portfolioId`, `portfolioName`

Time and date grouping

Amazon Ads returns daily records; Adriel groups them into these views on demand, so all time-grouping breakdowns are Adriel-side aggregations of the same underlying daily data.

Breakdown	Description
Auto Time Breakdown	Automatically picks the best granularity for the date range.
Daily	Split reports by day.
Weekly (Start: Mon)	Split reports by week, starting Monday.
Weekly (Start: Sun)	Split reports by week, starting Sunday.
Week Date Breakdown	Group by the day of the week the impression occurred.
Week Number Breakdown (W#)	Split by week number in the year.
Monthly	Split reports by calendar month.
Quarterly	Split reports by calendar quarter.
Yearly	Split reports by calendar year.

Overview and status

These groupings are provided by Adriel rather than returned as Amazon Ads breakdowns.

Breakdown	Description
Channel	Constant grouping label — for Amazon Ads this is always “amazon”. Used for cross-connector rollup.
No Grouping	Do not break down; return one aggregated row.
Objective	Group by campaign objective.
Status	Group by campaign / ad group / ad status.

Limitations

Cache-only reporting — dashboard values reflect the most recent snapshot, not a live Amazon Ads query.
60-day initial cache — on first connection, only the last 60 days of performance are populated; older history is not backfilled.
Region locked at connection time — North America, Europe, and Far East accounts use different API endpoints. Selecting the wrong region yields no data, and the region cannot be changed after the connection is created.
Metric availability differs per sub-API — Sponsored Products has the largest metric set; Sponsored Brands adds video and brand-awareness metrics; Sponsored Display adds view-through and engagement metrics. Querying a metric on the wrong sub-API returns empty values.
Uniqueness metrics may be overvalued — because reporting is cache-only and uniqueness is computed per snapshot, reach aggregated across multi-day windows can overstate true unique reach.
No deleted-data exclusion — the connector does not return deleted elements, so removed campaigns, ad groups, or ads may not appear in reports.
Rate limiting and truncation — Amazon imposes API rate limits; the connector applies built-in rate limiting and retry logic, and some data can be truncated.

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Attribution windows

Metrics

Delivery and cost

Sales and conversions (Sponsored Products)

Brand awareness (Sponsored Brands)

View-through and engagement (Sponsored Display)

Conversions and attribution (cross-API)

Custom conversion events

Campaign structure metadata

Breakdowns

Structure

Amazon-specific

Time and date grouping

Overview and status

Limitations

API references

See also

​Introduction

​Data refresh strategy

​Architecture data

​Reports data

​Architecture levels

​Date range limits

​Attribution windows

​Metrics

​Delivery and cost

​Sales and conversions (Sponsored Products)

​Brand awareness (Sponsored Brands)

​View-through and engagement (Sponsored Display)

​Conversions and attribution (cross-API)

​Custom conversion events

​Campaign structure metadata

​Breakdowns

​Structure

​Amazon-specific

​Time and date grouping

​Overview and status

​Limitations

​API references

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Attribution windows

Metrics

Delivery and cost

Sales and conversions (Sponsored Products)

Brand awareness (Sponsored Brands)

View-through and engagement (Sponsored Display)

Conversions and attribution (cross-API)

Custom conversion events

Campaign structure metadata

Breakdowns

Structure

Amazon-specific

Time and date grouping

Overview and status

Limitations

API references

See also