> 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/amazon-ads-legacy.md).

# Amazon Ads (legacy)

Amazon Ads (legacy) source: setup, report types, and troubleshooting for data flows created before the unified Amazon Ads source.

{% hint style="warning" %}
**This page covers the legacy Amazon Ads source.** It's no longer available for new data flows. Existing data flows that use it keep running and show the source as **Amazon Ads (legacy)**. For new data flows, use the [Amazon Ads](https://docs.coupler.io/sources/category/ppc/amazon-ads.md) source, which is built on the Amazon Ads unified reporting API.
{% endhint %}

{% hint style="danger" %}
**Migrate before June 30, 2027.** The legacy source uses the Amazon Ads Reporting API v3, which [Amazon deprecates on June 30, 2027](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/faq). After that date, legacy data flows stop receiving data. See [Migrating to the new Amazon Ads source](#migrating-to-the-new-amazon-ads-source).
{% endhint %}

The legacy Amazon Ads source pulls Sponsored Products (SP), Sponsored Brands (SB), Sponsored Display (SD), and Sponsored TV (ST) report data per marketplace profile into your spreadsheets, BI tools, databases, and AI tools on a schedule.

## How to check if you use the legacy Amazon Ads source

* In the data flows list, search for "Amazon Ads (legacy)". The data flows found use the legacy source.
* When editing a data flow, open the source summary. If the source is shown as **Amazon Ads (legacy)**, it uses the legacy source.

## Migrating to the new Amazon Ads source

The new [Amazon Ads](https://docs.coupler.io/sources/category/ppc/amazon-ads.md) source covers Sponsored Products, Sponsored Brands, Sponsored Display, Sponsored TV, and Amazon DSP in one report, supports longer date ranges, and lets you build custom reports from dimensions and metrics of your choice.

**What's different in the new source**

* **Accounts** — You select unified advertiser accounts instead of marketplace profiles. One global account groups several marketplaces, so you no longer need to select each country profile separately.
* **Report types** — Campaign, ad group, ad, advertised product, search term, and custom reports. There are no separate reports per ad product: every report covers all your ad products, with an **Ad product** column.
* **Date ranges** — You can set long date ranges. Coupler.io splits them into chunks that fit the Amazon Ads API limits.
* **Column names** — Columns use the Amazon Ads API field names, for example `campaign.name` and `metric.sales`. Rename them in the Data sets step if your destination relies on the old column names.
* **ACoS** — There's no ACoS metric. Add a formula column that divides **Total cost** by **Sales**.

**Which report to use instead**

| Legacy report                                             | New Amazon Ads report                                   |
| --------------------------------------------------------- | ------------------------------------------------------- |
| Campaign (SP, SB, SD, ST)                                 | Campaign performance report                             |
| Ad group (SP, SB, SD)                                     | Ad group performance report                             |
| Ad (SB)                                                   | Ad performance report                                   |
| Advertised products (SP), Advertised product (SD)         | Advertised product report                               |
| Search term (SP, SB)                                      | Search term report                                      |
| Targeting (SP, SB, SD, ST)                                | Custom report with the **Targeting** dimensions         |
| Placement (SP)                                            | Custom report with the **Placement** dimensions         |
| Purchased product report (SP, SB), Purchased product (SD) | Custom report with the **Converted product** dimensions |

**How to migrate**

{% stepper %}
{% step %}
**Edit your data flow and add the Amazon Ads source.** Select your Amazon connection, or connect your Amazon account again.
{% endstep %}

{% step %}
**Select your accounts and the report type** that replaces your legacy report (see the table above).
{% endstep %}

{% step %}
**Set the report period and metrics,** then compare the preview with your legacy source output.
{% endstep %}

{% step %}
**Switch the data set over.** In the Data sets step, rename columns if needed, then use the new source in the data set that goes to your destination and disable the legacy source.
{% endstep %}
{% endstepper %}

## Amazon Ads (legacy) data overview

Amazon Ads data flows give you access to performance metrics across different report levels and ad types. Understanding what data is available helps you choose the right report type for your analysis.

## Report types and data levels

| Report Type                                 | Data Level              | Account Coverage            | Best For                                       |
| ------------------------------------------- | ----------------------- | --------------------------- | ---------------------------------------------- |
| Campaign performance by campaigns           | Campaign                | Single or multiple accounts | Comparing campaign-level ROI                   |
| Campaign performance by ad groups           | Ad group                | Single or multiple accounts | Finding underperforming ad groups              |
| Campaign performance by campaign placement  | Placement               | Single or multiple accounts | Understanding ad placement effectiveness       |
| Targeting report                            | Keyword/target          | Single or multiple accounts | Optimizing bids and match types                |
| Search terms report                         | Search query            | Single or multiple accounts | Discovering new keywords and negative keywords |
| Advertised products report                  | Product                 | Single or multiple accounts | Identifying top and bottom product performers  |
| Sponsored products purchased product report | Product (post-purchase) | Single or multiple accounts | Attributing sales to advertised products       |
| Sponsored brands purchased product report   | Product (post-purchase) | Single or multiple accounts | Measuring branded campaign ROI                 |

## Available metrics

#### Performance metrics

| Metric             | Description                                  | Report Types                                   |
| ------------------ | -------------------------------------------- | ---------------------------------------------- |
| Impressions        | Number of times your ads were shown          | All                                            |
| Clicks             | Total clicks on your ads                     | All                                            |
| Spend              | Total advertising spend in the period        | All                                            |
| Sales              | Total sales from attributed conversions      | Campaign, ad group, placement, product reports |
| Units sold         | Number of units sold from ad clicks          | Campaign, ad group, product reports            |
| ACoS               | Advertising Cost of Sale (spend / sales)     | Campaign, ad group, placement, search terms    |
| CTR                | Click-through rate (clicks / impressions)    | Campaign, ad group, placement, targeting       |
| CPC                | Cost per click (spend / clicks)              | Campaign, ad group, placement, targeting       |
| Conversion rate    | Conversions as % of clicks                   | Campaign, ad group, search terms               |
| New ASIN purchases | Sales from products not previously purchased | Campaign, ad group                             |

#### Engagement and efficiency metrics

| Metric                 | Description                             | Report Types                  |
| ---------------------- | --------------------------------------- | ----------------------------- |
| Impressions share      | Your share of impressions in a category | Campaign, ad group            |
| Conversion value       | Total monetary value of conversions     | Product reports               |
| Attributed conversions | Conversions linked to your ads          | Search terms, product reports |
| Units ordered          | Total units ordered from your ads       | Purchased product reports     |

#### Targeting and query metrics (search terms & targeting reports)

| Metric      | Description                               | Report Types        |
| ----------- | ----------------------------------------- | ------------------- |
| Match type  | Keyword match type (exact, phrase, broad) | Targeting report    |
| Bid         | Current bid amount for the keyword/target | Targeting report    |
| Search term | Customer's exact search query             | Search terms report |

## Common metric combinations

**Campaign ROI analysis:** Spend, sales, ACoS, CTR (shows profitability and efficiency)

**Ad group optimization:** Impressions, clicks, CPC, conversion rate, units sold (helps find underperformers)

**Search term discovery:** Search term, impressions, clicks, spend, conversions (identify new keyword opportunities)

**Product performance:** Advertised product, units sold, conversion value, ACoS (which products drive revenue)

**Placement effectiveness:** Campaign placement, impressions, clicks, CTR, spend (compare placement channels)

## Platform-specific notes

* **31-day maximum:** The Amazon Ads API limits date ranges to 31 consecutive days. If you need longer periods, either schedule weekly pulls or use "Totals only" split mode for a single aggregated record.
* **Account coverage:** When you select multiple Amazon Ads accounts, data is pulled separately for each and appended together in your destination. Add an "account" or "profile" column to distinguish between accounts.
* **Report generation time:** Amazon generates reports asynchronously, and processing can take anywhere from a few minutes up to about 3 hours depending on report size and Amazon's own queue. If you see a "report is currently being generated" message, this is expected — re-running the data flow doesn't start a new report, it continues checking the one already in progress.
* **Ad product coverage:** Each report type covers one ad product, shown in its name: Sponsored Products (SP), Sponsored Brands (SB), Sponsored Display (SD), or Sponsored TV (ST). Amazon DSP isn't supported; use the new [Amazon Ads](https://docs.coupler.io/sources/category/ppc/amazon-ads.md) source for it.
* **Data refresh latency:** Amazon Ads data is typically available within 24–48 hours of ad activity. Schedule your data flows accordingly if you need near-real-time reporting.

## Amazon Ads (legacy) common issues

### Connection issues

<details>

<summary>"No accounts" showing after connecting</summary>

If you see "No accounts" or your Amazon Ads accounts aren't appearing in the account selector:

1. **Verify your Amazon account permissions** — Make sure your Amazon user account has advertiser access and is not restricted to read-only roles.
2. **Re-authorize the connection** — Disconnect and reconnect your Amazon Ads account. Click the gear icon next to your connection, select "Revoke," then create a new connection and re-authenticate.
3. **Check account country codes** — If you operate in multiple Amazon regions (US, EU, etc.), each region may require a separate account setup. The connector now includes country code support; ensure each account has the correct country designation.
4. **Wait after account setup** — If you recently created a new Amazon Ads account, it can take a few hours to appear in Coupler.io. Try reconnecting later.

If accounts still don't appear, reach out to support with a screenshot of your Amazon Ads dashboard showing your accounts.

</details>

<details>

<summary>401 Unauthorized error after successful connection</summary>

If you see a 401 error when running a data flow:

1. **Your access token has expired** — Reconnect your Amazon Ads account. Go to your data flow, click the connection settings, and re-authenticate with Amazon.
2. **Check account permissions** — Verify that the Amazon user account you connected still has advertiser access. If permissions were recently changed, re-authenticate.

</details>

### Missing data

<details>

<summary>Search terms or keyword data is incomplete or missing</summary>

If your search terms report is showing fewer rows than expected:

1. **Check your date range** — Amazon only returns search term data for the last 95 days. If your date range is older, you'll see no results.
2. **Verify you have query volume** — Search term reports only show terms that generated clicks or impressions. If you have very low traffic in your date range, results may be sparse.
3. **Use the correct report type** — Ensure you've selected "Search terms report," not "Targeting report" (which shows keywords you've bid on, not actual customer searches).

</details>

<details>

<summary>Product-level data not matching Amazon Ads dashboard</summary>

If your "Advertised products report" numbers don't match the Amazon Ads UI:

1. **Verify the report type** — Ensure you're pulling "Advertised products report" (product-level metrics) vs. "Sponsored products purchased product report" (post-purchase attribution).
2. **Check your date range** — Confirm your Coupler.io date range matches the Amazon dashboard. The Amazon Ads UI may show data in a different timezone.
3. **Filter matching** — If you applied advanced filters in Coupler.io, the filtered data will naturally be lower than the dashboard total. Review your filters.
4. **Contact support** — If metrics still don't align after checking above, provide a side-by-side screenshot of both your Coupler.io report and the Amazon Ads dashboard for the same date range and ad group.

</details>

### Permission errors

<details>

<summary>"Access denied" or "Insufficient permissions" error</summary>

If you see permission-related errors:

1. **Verify advertiser role** — Your Amazon account must have at least the "Advertiser" role to access reports. Campaign managers with read-only access cannot pull data via API.
2. **Check account status** — Ensure your Amazon Ads account is active and not suspended or in dispute status.
3. **Re-authenticate** — Disconnect and reconnect your Amazon Ads account. Old tokens may have permission issues.

If you manage accounts on behalf of clients, make sure you're logged in with the account that has delegated access to those client accounts.

</details>

### Data discrepancies

<details>

<summary>Data in Coupler.io doesn't match Amazon Ads dashboard</summary>

Small differences are normal due to report processing delays. If you see larger discrepancies:

1. **Check data freshness** — Amazon Ads data takes 24–48 hours to finalize. If you're pulling data from yesterday or today, the numbers may change as Amazon processes transactions.
2. **Verify date range** — Ensure your Coupler.io date range exactly matches the dashboard (same timezone, same start/end dates).
3. **Compare report types** — Different report types (campaign vs. ad group) may show slightly different totals due to data aggregation differences.
4. **Run a manual test** — Run your data flow manually, then immediately check the Amazon Ads dashboard for the same period to compare.

If discrepancies persist, contact support with screenshots showing both the Coupler.io data and the Amazon dashboard for comparison.

</details>

### Rate limits and API errors

<details>

<summary>"The requested report is currently being generated" error</summary>

This error means Amazon is still processing your report request. Amazon's own processing time varies — it's usually done within a few minutes, but can take up to about 3 hours for large or complex reports.

**What to do:**

1. **Wait and retry** — Re-running the data flow doesn't create a new report request; Coupler.io recognizes the same request and continues checking the report already in progress.
2. **Reduce your date range** — If this happens frequently, try pulling shorter date ranges (7–14 days instead of 31 days) to reduce processing time.

This is not a permanent error and should resolve once Amazon finishes generating the report.

</details>

<details>

<summary>"Date range exceeds maximum (31 days)" error</summary>

Amazon Ads API has a strict 31-day maximum for any single request.

**How to fix:**

1. **Reduce your date range** — Set your date range to 31 days or fewer.
2. **Use "Totals only" split** — Instead of daily breakdown, select "Totals only" for a single aggregated row. This works with longer date ranges if you pull weekly.
3. **Schedule weekly pulls** — Create a data flow that pulls the last 7 days weekly. You'll get a continuous history without hitting the 31-day limit.

If you absolutely need historical data beyond 95 days, export it manually from Amazon and append it in your destination.

</details>

<details>

<summary>"Request to Amazon Ads API has failed" error</summary>

This is a general API failure, usually temporary. Possible causes:

1. **Amazon API downtime** — Check the Amazon Ads service status. Try again in a few minutes.
2. **Timeout on large reports** — If you're pulling a very large report (thousands of rows, long date range), the API may timeout. Reduce your date range or number of metrics.
3. **Network connectivity** — Ensure your Coupler.io account has stable internet.
4. **Retry the data flow** — Click "Run" again. Many temporary API issues resolve on retry.

If the error persists after 2–3 retries, contact Coupler.io support with your data flow URL and the error message.

</details>

## Amazon Ads (legacy) FAQ

<details>

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

Yes. During setup, select multiple accounts in the "Accounts" step. Coupler.io will pull data from all selected accounts and append them together in your destination. To keep account data separate, add an "account" or "profile" ID column so you can filter by account in your destination.

</details>

<details>

<summary>What's the maximum date range I can pull?</summary>

The Amazon Ads API allows a maximum of **31 consecutive days** per request. If you need longer periods:

* Create a data flow with a 31-day range, or
* Use "Totals only" split and schedule weekly pulls to build rolling history

Historical data beyond 95 days is not available via the API and must be exported manually from your Amazon Ads account.

</details>

<details>

<summary>Why is my data different from the Amazon Ads dashboard?</summary>

Small differences are normal due to report processing delays. Larger discrepancies usually mean:

1. **Data latency** — Allow 24–48 hours for Amazon to finalize data. Yesterday's numbers may still be changing.
2. **Date range mismatch** — Ensure your Coupler.io date range exactly matches the dashboard (same timezone, same start/end dates).
3. **Report type difference** — Campaign and ad group reports may show different totals due to data aggregation.

Run a manual refresh, then immediately check the Amazon dashboard for the same period to compare.

</details>

<details>

<summary>Why am I seeing "The requested report is currently being generated" error?</summary>

This means Amazon is still processing your report. Processing time varies — it's usually done within a few minutes, but large or complex reports can take up to about 3 hours.

**What to do:**

* Wait and retry — this doesn't create a new report request, Coupler.io continues checking the one already in progress
* Reduce your date range (shorter ranges process faster)

This error will eventually resolve on its own.

</details>

<details>

<summary>Can I pull Sponsored Brands, Sponsored Display, or Sponsored TV data with the legacy Amazon Ads source?</summary>

Yes. Pick the report type marked with the ad product: SB for Sponsored Brands, SD for Sponsored Display, ST for Sponsored TV. Amazon DSP data isn't available in the legacy source; use the new [Amazon Ads](https://docs.coupler.io/sources/category/ppc/amazon-ads.md) source for it.

</details>

<details>

<summary>Can I combine Amazon Ads data with other ad channels (Google Ads, Facebook, etc.)?</summary>

Yes! Use the **Append transformation** to combine data from multiple sources. For example:

1. Create separate data flows for Amazon Ads, Google Ads, and Facebook Ads
2. Set them all to write to the same destination table
3. Use Append to stack the rows together
4. Add a "source" or "channel" column to distinguish between platforms

This gives you a unified multi-channel ad performance view in one table.

{% hint style="info" %}
See [Migrating to the new Amazon Ads source](#migrating-to-the-new-amazon-ads-source).
{% endhint %}

</details>

<details>

<summary>What permissions do I need in my Amazon account?</summary>

Your Amazon user account must have **Advertiser access** (not read-only). This typically means having one of these roles:

* Account owner
* Advertising manager
* Campaign manager (with report access)

Read-only or restricted roles won't have permission to pull data via API. If you manage client accounts, ensure you have delegated advertiser access set up by the account owner.

</details>

<details>

<summary>Can I use macros for dynamic date ranges?</summary>

Yes. The Amazon Ads connector supports macros for the Start Date and End Date fields. For example:

* `{{today}}` — Today's date
* `{{yesterday}}` — Yesterday's date
* `{{30daysago}}` — 30 days back

**Note:** Allow 24–48 hours for data to finalize. For most use cases, use `{{7daysago}}` or later to ensure accurate, finalized data.

{% hint style="info" %}
Learn more about macros in the [Coupler.io help center](https://docs.coupler.io/functionality/macros-in-data-flows).
{% endhint %}

</details>

<details>

<summary>What's the difference between "Campaign performance by campaigns" and "Campaign performance by ad groups"?</summary>

**Campaign performance by campaigns** shows metrics rolled up to the campaign level (one row per campaign)—good for high-level ROI analysis.

**Campaign performance by ad groups** shows metrics at the ad group level (one row per ad group within each campaign)—good for finding underperforming ad groups within campaigns.

Choose based on your analysis depth: use campaigns for executive summaries, ad groups for detailed optimization.

</details>

<details>

<summary>Why does my data flow keep failing?</summary>

Common reasons:

1. **Date range exceeds 31 days** — Reduce to 31 days or fewer
2. **401 Unauthorized error** — Re-authenticate your Amazon connection
3. **API timeout** — Reduce your date range or metrics, then retry
4. **"Report is being generated"** — Wait and retry; this can take up to about 3 hours for large reports

{% hint style="info" %}
See [Common Issues](#amazon-ads-legacy-common-issues) for detailed troubleshooting steps.
{% endhint %}

</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/amazon-ads-legacy.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.
