> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the Amazon Ads data source in Adriel.

## 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-sources/a-f/amazon-ads/how-to-connect).

## 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](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/overview)) — 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

<Note>
  **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.
</Note>

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

<Note>
  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.
</Note>

| 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

<Note>
  These groupings are provided by Adriel rather than returned as Amazon Ads breakdowns.
</Note>

| 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.

## API references

* [Amazon Ads API documentation](https://advertising.amazon.com/API/docs/en-us/)
* [Reporting API v3 overview](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/overview)
* [Sponsored Products reporting](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign)
* [Login with Amazon (OAuth 2.0)](https://advertising.amazon.com/API/docs/en-us/guides/get-started/create-authorization-grant)

## See also

* [How to connect Amazon Ads to Adriel](/data-sources/a-f/amazon-ads/how-to-connect) (paired how-to)
* [Amazon DSP data reference](/data-sources/a-f/amazon-dsp/data-reference) — for programmatic display via Amazon's DSP
* [Amazon Vendor Central data reference](/data-sources/a-f/amazon-vendor-central/data-reference) — for retail performance complementing ad metrics