> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/ppc/amazon-ads.md).

# Amazon Ads

Connect Amazon Ads to Coupler.io to export Sponsored Ads and Amazon DSP performance from all your accounts into spreadsheets, BI tools, and AI.

Amazon Ads is Amazon's advertising platform for Sponsored Products, Sponsored Brands, Sponsored Display, Sponsored TV, and Amazon DSP campaigns. Coupler.io pulls your Amazon Ads performance data through the Amazon Ads unified reporting API, so one report covers all your ad products, accounts, and marketplaces.

{% hint style="info" %}
Data flows created before the unified source use **Amazon Ads (legacy)**. They keep running until Amazon deprecates the Reporting API v3 on June 30, 2027. See [Amazon Ads (legacy)](https://docs.coupler.io/sources/category/ppc/amazon-ads/amazon-ads-legacy.md) for its documentation and how to migrate.
{% endhint %}

Why connect Amazon Ads to Coupler.io?

* **All ad products in one report** — Sponsored Products, Sponsored Brands, Sponsored Display, Sponsored TV, and Amazon DSP, with an **Ad product** column to tell them apart
* **All accounts and marketplaces at once** — Select several advertiser accounts; one global account covers all its marketplaces
* **Long date ranges** — Set any period within Amazon's data retention; Coupler.io splits it into reports that fit the API limits
* **Custom reports** — Combine the dimensions and metrics you need, from campaigns and targeting to audiences, placements, and benchmarks
* **Flexible destinations** — Export to AI tools, Google Sheets, Excel, BigQuery, Looker Studio, Power BI, or other supported destinations

## Prerequisites

* An Amazon Ads account with access to the advertiser accounts you want to report on
* Permission to view campaign performance and reports in those accounts

## Quick start

{% hint style="success" %}
Start with a **Campaign performance report** for one account, the last 30 days, and the default metrics. Once the preview looks right, add accounts, extend the date range, or switch to a custom report.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a data flow and select Amazon Ads as the source.**\
Click **Connect** and sign in with your Amazon account. Grant Coupler.io access to your advertising data.
{% endstep %}

{% step %}
**Select your accounts.** Choose one or more advertiser accounts. Global accounts cover all their marketplaces, and Amazon DSP regional accounts are listed as well.
{% endstep %}

{% step %}
**Choose a report type.** Pick a predefined report (campaign, ad group, ad, advertised product, or search term) or **Custom report** to choose your own dimensions.
{% endstep %}

{% step %}
**Set the report period.** Pick the start and end dates with the date picker. For a rolling period, you can use [date macros](https://docs.coupler.io/functionality/macros-in-data-flows) such as `{{30daysago}}` and `{{today}}`.\
Then choose how to **Split data by periods**: Daily, Weekly, Monthly, Yearly, or Totals.
{% endstep %}

{% step %}
**Choose your columns.** Select the metrics (and dimensions for a custom report). Optionally, pick a **Currency** to get extra columns with monetary metrics converted into it.
{% endstep %}

{% step %}
**Set up the destination and run the data flow.** Choose where the data goes, run the data flow, and set a schedule to keep it up to date.
{% endstep %}
{% endstepper %}

## Amazon Ads data overview

Each report is aggregated by its dimensions: one row per unique combination of dimension values and time period. Every selected account gets its own report, and the rows are combined in one table.

## Report types

| Report type                 | One row per                                                                               | Use it for                                                                                       |
| --------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Campaign performance report | Campaign                                                                                  | Comparing spend and return across campaigns and ad products                                      |
| Ad group performance report | Ad group, with its campaign                                                               | Finding the strongest and weakest ad groups within each campaign                                 |
| Ad performance report       | Ad, with its ad group and campaign                                                        | Comparing individual ads                                                                         |
| Advertised product report   | Advertised product (ASIN/SKU) and marketplace, with its ad group, campaign, and portfolio | Product-level spend, sales, and halo or new-to-brand results                                     |
| Search term report          | Customer search term in each ad group                                                     | Finding converting keywords and wasted spend                                                     |
| Custom report               | The dimensions you select                                                                 | Any other breakdown, such as targeting, placements, audiences, devices, geography, or benchmarks |

{% hint style="info" %}
Ad product coverage depends on the data Amazon provides for each report. The **Search term report** returns Sponsored Products and Sponsored Brands data. The **Advertised product report** returns Sponsored Ads data and doesn't include Amazon DSP.
{% endhint %}

## Configuration options

| Option                    | What it does                                                                                                                             |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Accounts**              | Advertiser accounts to pull data from. Each account is reported separately, so an account you've lost access to doesn't stop the others. |
| **Report type**           | The predefined report or **Custom report**. Changing it resets the metrics to that report's defaults.                                    |
| **Start date / End date** | The report period. Days follow each campaign's timezone.                                                                                 |
| **Split data by periods** | **Daily**, **Weekly**, **Monthly**, **Yearly**, or **Totals** (one row for the whole period).                                            |
| **Metrics**               | The metrics to include. Each report type has its own list and defaults.                                                                  |
| **Dimensions**            | Custom report only. The fields your data is grouped by.                                                                                  |
| **Currency**              | Optional. Adds a converted column next to every monetary metric. The original metrics stay in the currency the spend was made in.        |

### How far back you can go

Amazon keeps reporting data for a limited time, depending on the split:

| Split data by periods   | Data available for |
| ----------------------- | ------------------ |
| Daily, Weekly           | Last 24 months     |
| Monthly, Yearly, Totals | Last 6 years       |

You don't need to keep the date range short: Coupler.io splits long periods into several reports that fit Amazon's per-report limits and combines the results. Benchmark dimensions only have data from June 1, 2025.

## Available metrics

Metrics are grouped in the metric picker. The main groups:

| Group                                               | Examples                                                                                              |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Delivery                                            | Impressions, Clicks, CTR, CPC, CPM                                                                    |
| Reach                                               | User reach, Average user impression frequency                                                         |
| Costs and fees                                      | Total cost and fee breakdowns                                                                         |
| Amazon retail conversions                           | Purchases, Sales, Units sold, ROAS, Detail page views, with promoted, halo, and new-to-brand variants |
| Off-Amazon conversions                              | Conversions tracked outside Amazon                                                                    |
| Amazon device conversions, Amazon video conversions | Results on Amazon devices and video                                                                   |
| Engagement                                          | Video and engagement metrics                                                                          |
| Combined conversions                                | Amazon and off-Amazon conversions together                                                            |
| Impression share                                    | Impression share (campaign and custom reports)                                                        |

Not every metric applies to every ad product. A metric that doesn't apply to a row's ad product stays empty.

{% hint style="warning" %}
**Ratio metrics aren't summable.** CTR, CPC, CPM, ROAS, and similar metrics must be recalculated when you aggregate rows (for example, ROAS = Sales / Total cost), not summed or averaged.
{% endhint %}

There's no ACoS metric. To get it, add a formula column in the Data sets step that divides **Total cost** by **Sales**.

## Data schema

* **Dimension and metric columns** use the Amazon Ads API field names, for example `campaign.name`, `adGroup.id`, `metric.impressions`, and `metric.sales`.
* **Date columns** — every row has `date.start` and `date.end`: the first and last day of its period (a day, week, month, year, or the whole report period).
* **Converted columns** — with a currency selected, monetary metrics get a `Converted` counterpart, for example `metric.salesConverted`.
* **Fields that depend on the ad product** — some dimensions, such as campaign bid strategy or DSP order details, only have values for certain ad products and are empty for the rest.

## Use cases by role

{% tabs %}
{% tab title="PPC Managers" %}
Pull a daily **Campaign performance report** across all your accounts to track spend, ROAS, and purchases by ad product. Use the **Search term report** to find converting search terms and wasted spend, and a **Custom report** with targeting dimensions to review match types and bids.
{% endtab %}

{% tab title="E-commerce Operations" %}
Use the **Advertised product report** to see which ASINs and SKUs drive sales, including halo and new-to-brand results. Join it with your inventory or catalog data in the Data sets step to plan promotions and budgets per product.
{% endtab %}

{% tab title="Finance & Analytics" %}
Pull monthly totals with a **Currency** selected to report spend and sales from all marketplaces in one currency. Send the data to BigQuery or Looker Studio for profitability dashboards.
{% endtab %}

{% tab title="Agencies" %}
Select several client accounts in one source to build a single cross-account report. Append Amazon Ads data with Google Ads, Facebook Ads, and other ad channels in the Data sets step for a multi-channel view.
{% endtab %}
{% endtabs %}

## Amazon Ads common issues

### Connection issues

<details>

<summary>An Amazon Ads account is missing from the account list</summary>

1. **Check your access** — The list shows the advertiser accounts your Amazon user can access. Ask the account owner to grant you access if an account is missing.
2. **Manager accounts aren't listed** — Select the advertiser accounts linked to the manager account instead.
3. **Reconnect** — If you were granted access recently, reconnect your Amazon account in Coupler.io and reload the list.

</details>

<details>

<summary>Amazon Ads data flow fails with an authorization error</summary>

The error starts with "Amazon Ads rejected the report request" and has status 401 or 403. A 401 means Amazon no longer recognizes the connection; a 403 means the connected Amazon user isn't authorized for the selected account. Reconnect your Amazon account, and check that the user still has access to the account in Amazon Ads.

</details>

### Report configuration errors

<details>

<summary>"Amazon Ads rejected the report request" error</summary>

Amazon rejects a report request it can't build, and the error includes Amazon's explanation after the colon. Common causes:

* **Incompatible fields in a custom report** — Some dimensions and metrics can't be combined. Remove the field named in the error. The [Amazon Ads dimensions library](https://advertising.amazon.com/API/docs/en-us/guides/reporting/ads-v1/dimensions/library) and [metrics library](https://advertising.amazon.com/API/docs/en-us/guides/reporting/ads-v1/metrics/library) list what each field supports.
* **Period out of retention** — The start date is older than Amazon keeps data for the selected split. See [How far back you can go](#how-far-back-you-can-go).

</details>

### Long-running reports

<details>

<summary>Amazon Ads data flow takes a long time to finish</summary>

Amazon generates reports asynchronously, and Coupler.io waits for each one to complete. Large reports — long periods, many accounts, many dimensions, or daily splits — take longer. If a run is interrupted, the next run continues with the reports already in progress instead of starting over.

To speed things up, select fewer dimensions and metrics, use a weekly or monthly split for long periods, or shorten the date range.

</details>

### Data discrepancies

<details>

<summary>Amazon Ads numbers in Coupler.io don't match the Amazon Ads console</summary>

1. **Attribution window** — Conversions are attributed for up to 14 days after an ad interaction, so numbers for recent days keep changing until that window closes. Include the last two weeks in your date range and refresh regularly.
2. **Timezones** — Days follow each campaign's timezone. Compare the same campaigns and dates in the console.
3. **Currency** — Original monetary metrics are in the currency the spend was made in. Summing them across marketplaces mixes currencies; select a **Currency** and use the converted columns instead.
4. **Ratio metrics** — Recalculate CTR, CPC, ROAS, and similar metrics from their components when you aggregate rows.

</details>

## Amazon Ads FAQ

<details>

<summary>What's the difference between Amazon Ads and Amazon Ads (legacy) in Coupler.io?</summary>

**Amazon Ads** is built on the Amazon Ads unified reporting API: one report covers all ad products (including Amazon DSP), you select advertiser accounts instead of marketplace profiles, and long date ranges are split for you. **Amazon Ads (legacy)** is the previous source with a separate report per ad product. It's no longer available for new data flows; existing data flows keep running until June 30, 2027, when Amazon deprecates the Reporting API v3 it uses. See [Amazon Ads (legacy)](https://docs.coupler.io/sources/category/ppc/amazon-ads/amazon-ads-legacy.md#migrating-to-the-new-amazon-ads-source) for how to migrate.

</details>

<details>

<summary>Can I pull data from multiple Amazon Ads accounts in one data flow?</summary>

Yes. Select several accounts in the **Accounts** field. Each account is reported separately and the rows are combined in one table. Add the **Advertiser account name** dimension in a custom report, or use a predefined report, to tell the accounts apart.

</details>

<details>

<summary>Does the Amazon Ads source include Amazon DSP data?</summary>

Yes. The campaign, ad group, ad, and custom reports include Amazon DSP alongside Sponsored Ads, with an **Ad product** column to tell them apart. Amazon doesn't provide DSP data for the search term and advertised product reports.

</details>

<details>

<summary>How much Amazon Ads history can I export?</summary>

Up to 24 months with a daily or weekly split, and up to 6 years with a monthly, yearly, or totals split. Coupler.io splits long date ranges into several reports for you.

</details>

<details>

<summary>How do I get Amazon Ads spend from all marketplaces in one currency?</summary>

Select a **Currency** in the source settings. Every monetary metric gets an extra converted column in that currency, for example `metric.salesConverted`. The original columns stay in the currency the spend was made in.

</details>

<details>

<summary>Why don't I see ACoS in the Amazon Ads metrics?</summary>

Amazon's unified reporting API doesn't provide ACoS. Add a formula column in the Data sets step that divides **Total cost** by **Sales**, or use **ROAS**, which is its inverse.

</details>

<details>

<summary>Can I send Amazon Ads data to AI tools like Claude or ChatGPT?</summary>

Yes. Choose an AI destination such as Claude, ChatGPT, Cursor, Gemini, or Perplexity to analyze your Amazon Ads performance with AI.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/ppc/amazon-ads.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
