Selltics Docs

English

Русский

English

Русский

Appearance

Amazon Ads API ​

Updated

What the Amazon Ads API is, how an application is authorized, what a profile is, and how metrics are delivered.

As Amazon publishes it

The subject matter as Amazon publishes it. Nothing on this page describes a particular application; every statement restates the public documentation listed under Sources.

In short ​

  • The API manages an advertiser's campaigns and returns performance data.
  • Authorization runs through Login with Amazon (LWA); access tokens live one hour.
  • The chosen profile id travels on every campaign or reporting call, so such a request acts on one account in one marketplace.
  • Metrics arrive as reports (pull) or through Amazon Marketing Stream (push).

What it is ​

  • The Amazon Ads API gives an application programmatic access to an advertiser's Amazon Ads accounts.
  • It creates and manages campaigns, ad groups, ads, keywords and targets, and it returns performance data.
  • It covers the sponsored ad products — Sponsored Products, Sponsored Brands and Sponsored Display — and, through separate endpoints, Amazon DSP.
  • Access is granted per application after Amazon approves an API access request.

Authorization ​

  • Login with Amazon (LWA). The advertiser grants an application access through an OAuth 2.0 authorization-code flow. The application exchanges the code for an access token and a refresh token.
  • Access tokens are short-lived (one hour). The refresh token is exchanged for a new access token whenever the old one expires.
  • Every call is identified by the access token (Authorization: Bearer …) and the application's LWA client id (Amazon-Advertising-API-ClientId).

Profiles and scope ​

  • A profile is one advertiser account in one marketplace — the same seller selling in the United States and in Germany has two profiles.
  • Listing the profiles a token can reach is the first call an application makes.
  • The chosen profile id then travels on every campaign or reporting call in the Amazon-Advertising-API-Scope header, so a request always acts on exactly one account in one marketplace.

Regions ​

The API is served from three regional hosts, and a profile is reachable only through the host of its region:

  • North America — advertising-api.amazon.com. Marketplaces, for example: United States, Canada, Mexico, Brazil.
  • Europe — advertising-api-eu.amazon.com. Marketplaces, for example: United Kingdom, Germany, France, Italy, Spain, India, United Arab Emirates.
  • Far East — advertising-api-fe.amazon.com. Marketplaces, for example: Japan, Australia, Singapore.

Getting metrics ​

  • Reports (pull). A report is requested with a date range, a report type, columns and filters; Amazon generates it asynchronously. The application polls the report's status and, once it is complete, downloads a compressed file from the URL in the response.
  • Amazon Marketing Stream (push). An application subscribes per advertiser to datasets such as hourly sponsored-ads traffic and conversions or campaign changes. Amazon delivers the messages to an AWS destination the application owns — an Amazon SQS queue or an Amazon Data Firehose stream — close to real time, instead of the application polling for them.

Rate limits

Calls are throttled; a throttled call answers HTTP 429 and is retried later with backoff.

In this section ​

Sources ​