Short answer
The Amazon Ads API is a REST API for managing Sponsored Products, Sponsored Brands, Sponsored Display, Sponsored TV and Amazon DSP campaigns and for pulling their performance data. Access needs an approved Login with Amazon (LwA) client, a user who grants that client the advertising::campaign_management scope, and a profile ID for every marketplace you touch. The calls themselves are simple. What decides whether an integration survives production is regional routing, asynchronous reports with short data retention, dynamic rate limits, and a version change now under way: Amazon calls its new Ads API v1 the eventual replacement for the per-product APIs, and both reporting v3 and Amazon Marketing Stream v1 are scheduled to stop on 30 June 2027.
Everything below was checked against Amazon's Ads API documentation on 30 October 2026. Amazon updates these pages often, so treat dates and limits as of that day.
What the Ads API covers, and what it does not
The Ads API is a separate product from the Selling Partner API (SP-API). It has its own application process, its own authorization and its own hosts. A seller tool that shows TACoS or profit per ad dollar therefore runs two integrations side by side: SP-API for orders, fees and inventory, and the Ads API for spend, clicks and attributed sales. If you are new to the seller side, our SP-API integration guide covers it.
On the advertising side, the documentation groups the API into campaign management for each ad product, reporting, exports, Amazon Marketing Stream, Amazon Marketing Cloud, budget rules, recommendations, Amazon Attribution (still labelled beta), billing and several smaller services. Retail data such as orders or inventory is not part of it.
Getting access
Amazon's onboarding overview lists three steps, and direct advertisers, partners and integrators are all eligible:
- Create an LwA application. It is free, needs no approval and gives you a client ID and secret.
- Apply for API access. The form asks how you intend to use the API and points you to the Amazon Ads API License Agreement and the Data Protection Policy. Amazon says approval may take up to one business day.
- Assign API access to the LwA application. After approval you link the security profile you applied with, which turns it into a client the API accepts.
Use a shared company mailbox for the developer account rather than one engineer's address. Losing access to that account means losing the client every advertiser authorized.
Authorization: one consent per region
Requests are made by your client on behalf of an Amazon user who manages advertising accounts. That user grants access through the LwA authorization code flow, as described in Amazon's authorization guide. The consent URL starts with a region-specific prefix:
- North America:
https://www.amazon.com/ap/oa - Europe:
https://eu.account.amazon.com/ap/oa - Far East:
https://apac.account.amazon.com/ap/oa
The prefix decides which Amazon account system the user signs in to. Send a Japanese advertiser to the North American prefix and they log in with an amazon.com identity that may have no advertising access at all. Once you hold a refresh token, the resulting access tokens work against any regional host; the prefix only matters at consent time.
Set scope to advertising::campaign_management for the sponsored ads, DSP and Attribution APIs. Clients approved before October 2020 may still need the older cpc_advertising:campaign_management. Access tokens expire after 60 minutes, so keep refresh logic in one service that every worker asks for a token, rather than letting each job refresh on its own and race the others.
Profiles and regional hosts
Almost every request needs a profile ID, which stands for one advertising account in one marketplace. You list them with GET /v2/profiles, and the call returns only the profiles of the region whose host you called. The hosts, per the API overview:
- North America (US, CA, MX, BR):
advertising-api.amazon.com - Europe (UK, FR, IT, ES, DE, NL, AE, PL, TR, EG, SA, SE, BE, IN, ZA):
advertising-api-eu.amazon.com - Far East (JP, AU, SG):
advertising-api-fe.amazon.com
India and the Gulf markets sit on the European host, which surprises teams that route by continent. Build the routing from this table, not from guesswork.
After that, each call carries three headers: Amazon-Advertising-API-ClientId with your client ID, Authorization with the bearer token, and Amazon-Advertising-API-Scope with the profile ID. Two details from the profiles guide save debugging time:
- An empty array means the authorization worked but the user has no View and Edit rights on any advertising account in that region. It is a permissions answer, not an error.
- Amazon DSP advertiser accounts are not returned by
/v2/profiles. They come from the DSP advertiser and manager account endpoints instead.
Store profiles with their country code, currency and time zone. Reports come back in the profile's time zone and currency, and a multi-marketplace dashboard that ignores either will add yen to euros sooner or later.
Two generations of the API at once
In 2026 you are building across a transition. Amazon describes Ads API v1 as a common model with shared field names, error handling and resource patterns across Sponsored Products, Sponsored Brands, Sponsored Display, Sponsored TV and DSP, recommends it to anyone starting out, and says it will eventually fully replace the product-specific APIs. Coverage is still growing; Amazon lists reporting, recommendations, rules and media planning among the areas it expects to expand.
Two dates matter for anything you ship now:
- Reporting v3 (
/reporting/reports) is marked for deprecation on 30 June 2027, with a new reporting API under/adsApi/v1/as its replacement. - Amazon Marketing Stream v1 is shut off on the same day. Its successor, Stream v2, writes Parquet files to your own S3 bucket. We cover that move in our Amazon Marketing Stream integration guide.
Our rule for new builds: use v1 endpoints where they cover what you need, keep the product-specific endpoints behind an adapter where they do not, and plan the reporting migration as its own work item rather than a footnote in 2027.
Reporting in practice
Reports are asynchronous in both generations. In reporting v3 you send one request to POST /reporting/reports with an ad product, a report type, a groupBy, a column list and a timeUnit of DAILY or SUMMARY. You get back a reportId with status PENDING, poll GET /reporting/reports/{reportId} until it reads COMPLETED, then download a gzipped JSON file from the S3 link in url. Amazon's reporting tutorial warns that generation can take up to three hours, and an identical request sent while the first is still running returns 425.
The limits that shape the data model sit in the report type tables. For campaign reports:
| Ad product | Longest range per request | Data retention |
|---|---|---|
| Sponsored Products | 31 days | 95 days |
| Sponsored Brands | 31 days | 60 days |
| Sponsored Display | 31 days | 65 days |
| Sponsored TV | 31 days | 95 days |
| Amazon DSP | 31 days | 95 days |
Retention is the number that hurts. Amazon will not give you last year's Sponsored Brands performance through this endpoint, so the history your client wants next spring has to be stored by you, starting the day they connect. Pull daily rows, keep them in your own warehouse, and re-pull the trailing window every day, because attributed sales for recent days keep moving.
The new reporting API changes the shape of a request. Instead of choosing a report type, you list fields, such as campaign.id, date.value or metric.impressions, and the service groups by every dimension you include. You create reports with POST /adsApi/v1/create/reports and check them with POST /adsApi/v1/retrieve/reports, which Amazon suggests calling about once a minute; a finished report lists one or more parts, each with a presigned S3 URL. Amazon's Stream v2 overview describes this reporting API as meant for ad hoc use, with usage limits of one concurrent report per advertiser and about 100 reports a day, and points recurring, automated reporting to Stream v2. If you are designing an hourly or many-account pipeline today, read that sentence twice.
Reports return IDs and numbers, not names or settings. Get campaign, ad group and target metadata from the exports service and join on the IDs. That is cheaper than listing entities one by one, as the next section explains.
Rate limits and 429s
The Ads API does not publish fixed quotas. Per its rate limiting page, a throttled call returns 429 with a Retry-After header in seconds, and limits move with overall system load. Reporting is stricter: its limits depend on the size of the report queue in each region, so the same request rate can pass at night and fail at the regional peak.
What follows from that:
- Retry
429and5xxwith exponential backoff and a ceiling; do not retry other4xxcodes until the request is fixed. - Spread report creation through the day and run backfills in small slices, as Amazon itself recommends.
- Avoid the extended list operations unless you need entity status; Amazon counts them at five times the weight of a standard call.
- Never list every entity of a large account to build a snapshot. Request an export and parse it.
Put one scheduler in charge of all report requests per region. Independent cron jobs that each back off on their own will still overload the queue together.
Writes: bids, budgets and guardrails
Campaign management endpoints let you create campaigns and change bids, budgets, targets and states, mostly in batches. The API will happily apply a bad change to 5,000 keywords. The safety has to be in your code:
- compute the change, write it to a log with the before and after values, and only then send it;
- cap the size of any automated change (for example no bid moves more than a set percentage in one run) and require a human for anything above the cap;
- make every write idempotent so a retry after a timeout does not apply the change twice;
- re-read the entity after the write rather than trusting the response alone.
Hourly bid or budget changes make sense only with hourly data. If that is your plan, the reporting API is the wrong source, and Amazon Marketing Stream is the right one.
A reference architecture
For most Ads API projects we end up with the same components:
- Token service holding refresh tokens per authorizing user and handing out access tokens.
- Account registry of profiles and DSP advertisers with region, marketplace, currency and time zone, refreshed daily.
- Report scheduler per region with backoff, deduplication of identical requests and a trailing-window re-pull.
- Raw landing store keeping every downloaded file untouched, so a parsing bug never means re-requesting data Amazon no longer keeps.
- Modelled tables joining performance to exported entity metadata and, through ASIN and SKU, to SP-API sales and fees.
- Monitoring on report latency, 429 rates and data freshness per account, because a silent gap in ads data costs money the next day. We wrote about monitoring systems in production separately.
The same pattern applies to SP-API work, and our post on building an Amazon data connector goes deeper into the landing and modelling layers.
Build it, or use a data layer
A custom Ads API integration is the right call when the advertising data feeds your own product, your bidding logic, or a warehouse with rules only your team knows. If what you need is the data itself, in an AI client or a spreadsheet, without running the pipeline, DataDoe, the product our team engineers, connects Amazon Ads next to Seller and Vendor Central. Its Amazon Ads MCP page shows what the AI side looks like, and PPC teams comparing tools can read its Amazon PPC software page. Changes to campaigns there run through Actions, which stay off until you enable them; most AI clients ask before a change, and every change is logged.
How we scope an Ads API project
We start with the questions that change the design: which ad products and regions, how much history the client expects to see, whether the system writes or only reads, and how fresh the numbers must be. Hourly answers point to Stream, daily answers to the reporting API, and the June 2027 dates decide which generation we build on. Then we build the token service and registry first, because everything else depends on them.
Deltologic has built marketplace integrations since 2020, with more than 200 builds behind us; the marketplace integrations page shows the scope, and API migrations covers moves like the reporting v3 retirement. If you are planning an Amazon Ads API integration or need an existing one moved before the 2027 deadlines, send us a short brief. A senior engineer reads it and replies with a plan.
Frequently asked questions
How do I get access to the Amazon Ads API?
Create a Login with Amazon application, apply for Amazon Ads API access with it, and assign API access to the application once approved. Direct advertisers, partners and integrators can all apply, and Amazon says approval may take up to one business day.
What is the difference between the Amazon Ads API and the SP-API?
The Amazon Ads API manages advertising campaigns and returns ad performance. The Selling Partner API covers orders, fees, inventory and listings. They have separate applications, authorization and hosts, so a tool that combines ad spend with sales runs both.
How long does the Amazon Ads API keep report data?
In reporting v3, campaign reports can cover at most 31 days per request, and data is kept for 95 days for Sponsored Products, Sponsored TV and Amazon DSP, 65 days for Sponsored Display and 60 days for Sponsored Brands. Longer history has to be stored by your own system.
Is Amazon Ads reporting v3 being deprecated?
Yes. Amazon marks reporting v3 for deprecation on 30 June 2027 and points to the new reporting API under /adsApi/v1/. Amazon Marketing Stream v1 is shut off on the same date in favour of Stream v2.