Amazon Advertising API Getting Started Guide
Amazon Advertising API
Getting Started Guide
V 1.3.2017-01-24
Amazon Advertising API Getting Started Guide
Account setup
Developers interact with the API on behalf of an advertiser using an authorization token. All actions taken through
the API require both a developer (Login with Amazon) and an advertiser (Selling on Amazon) account.
API authorization through Login with Amazon
Login with Amazon enables an advertiser to grant a 3rd party application access to their advertising data. The
owner of the application has to provide a login URL to the advertiser. This URL will redirect the advertiser to an
Amazon owned login page where the advertiser logs in with their Selling on Amazon account. The advertiser
then gives the application permission to access their advertising data. Last, the advertiser is redirected to the
applications return URL that includes an authorization code. This authorization code is required for requesting
an authorization token to access the advertisers account via the API.
Additional information on login URL and authorization token is in the Getting an Authorization Token section.
The next section describes in detail how to setup a developer account for accessing the Advertising API.
Step 1: Create a developer account (Login with Amazon)
The Amazon Advertising API leverages Login with Amazon to handle delegated authorization. This means that
you must register a Login with Amazon application before you can receive tokens for API access.
To set up a worldwide Login with Amazon account, follow these steps:
1. Register as a developer on https://login.amazon.com/ using the Sign Up link in the top left corner.
If you already have an existing Amazon account (Amazon Web Services, Seller Central, etc.) you may
use this account to login.
2. Register a new application using the Register new application link in the top right corner.
After registering the application open the Web Settings panel and provide at least one “Allowed Return
URL” (e.g. https://www.your-domain.com/signup). This will be the URL where your customers are
redirected after they granted your application API access. Please copy and paste the Client ID and Client
Secret, since you will need it later in this guide.
Step 2: Apply for access
Important: Completing this step is required before moving to the next step.
Now that you have a developer account, apply for access by visiting https://advertising.amazon.com/API and
complete the sign up form. Your request is reviewed and if approved, you will receive an email with instructions
for the onboarding process. This process will guide you through accepting the Amazon Advertising license
agreement and whitelisting a Login with Amazon application Client ID.
1
Amazon Advertising API Getting Started Guide
Obtaining consent to access an advertiser’s account
This step-by-step guide will take you through the process of obtaining consent to manage an advertiser’s
account. While this flow is handled by your web application in the future, URL requests are made directly in the
browser and cURL for illustrative purposes.
We will start by fetching an authorization code from Login with Amazon.
1. Please ensure that you added an Allowed Return URL to your Login with Amazon application as
described earlier in the account setup section. The authorization code that is required to obtain an
authorization token is passed to your web application via this return URL. For this example, we will extract
it from the URL manually.
2. The following URL is the consent link that you can send to any advertiser you wish to manage.
https://www.amazon.com/ap/oa?client_id=YOUR_LWA_CLIENT_ID
&scope=cpc_advertising:campaign_management
&response_type=code
&redirect_uri=YOUR_RETURN_URL
3. The advertiser should sign in using their Amazon advertiser account and click through the consent
screens. Once consent has been granted, the advertiser will be redirected to the return URL. If you do
not possess an advertiser account, you can sign in using the credentials of your Login with Amazon
account for this example.
4. Once the advertiser is redirected, the Login with Amazon authorization code will be a query parameter in
the return URL. This is the authorization code that you’ll exchange for authorization tokens. Authorization
codes are specific to the Client ID, advertiser account and scope combination. A scope is associated with
a set of permissions which, in this case, is “cpc_advertising:campaign_management,” which grants the
ability to manage Sponsored Products.
At this point, you will have access to the advertiser’s advertising data. The next section describes how to
exchange the authorization code for access and refresh tokens.
Obtaining authorization tokens
Once you have the authorization code, you must make another call to exchange it for access and refresh tokens.
The following call is an example of how to do this.
curl \
-X POST \
-H "Content-Type:application/x-www-form-urlencoded;charset=UTF-8" \
--data
"grant_type=authorization_code&code=AUTH_CODE&redirect_uri=YOUR_RETURN_URL&client_id=YOUR_C
LIENT_ID&client_secret=YOUR_SECRET_KEY" \
https://api.amazon.com/auth/o2/token
2
Amazon Advertising API Getting Started Guide
You should receive a JSON response containing an access token and refresh token. Use the access token for
subsequent calls to the Advertising API. Important: The refresh token will never expire while access tokens are
only valid for 60 minutes, so they need to be refreshed periodically using the refresh token via following
command:
curl \
-X POST \
-H "Content-Type:application/x-www-form-urlencoded;charset=UTF-8" \
--data
"grant_type=refresh_token&client_id=YOUR_CLIENT_ID&refresh_token=YOUR_REFRESH_TOKEN&client_secret=
YOUR_CLIENT_SECRET" \
https://api.amazon.com/auth/o2/token
Sandbox environment
Use the sandbox for experimentation and testing: https://advertising-api-test.amazon.com. The sandbox
provides an environment that enables clients to test CRUD operations, but the data is not replicated to production
and will not show up on your advertiser account or result in active ads. Since the ads created in the sandbox are
not actively serving, the reports requested through the sandbox will not contain production data. However,
reports are populated with example data for manual targeting campaigns containing keywords and product ads
(i.e. selected products to advertise) or for auto targeting campaigns containing product ads only. For testing the
reporting functions, we recommend to use a production advertiser account to access meaningful metrics based
on real campaigns.
Create sandbox profiles
Profiles identify a specific advertiser in a specific marketplace (country). All calls to fetch or modify the state of
the account require specifying a profile ID. Since the sandbox environment comes without registered profiles we
will first create a profile within the sandbox using the following command (valid values for country code are US,
CA, UK, DE, FR, IT and ES):
Example:
curl \
-X PUT \
-H "Content-Type:application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{"countryCode":"US"}' \
https://advertising-api-test.amazon.com/v1/profiles/register
3
Amazon Advertising API Getting Started Guide
Fetch profiles
Make a call to get the profiles associated with the advertiser account authorized via the authorization token
obtained above. You can simulate this call with the following cURL request:
curl \
-X GET \
-H "Content-Type:application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://advertising-api-test.amazon.com/v1/profiles
The response should contain the profile you registered in the last step. If there are multiple profiles, you can use
the accountInfo map to identify the profile you wish to use for this example.
Create your first campaign
Now that you have a profile, you can create your first campaign. Place the following payload in a file called
testCampaign.txt:
[
{
"name": "Hello World Campaign",
"state": "enabled",
"startDate": "20290101",
"campaignType": "sponsoredProducts",
"targetingType": "auto",
"dailyBudget": 1.00
}
]
You can now create a campaign using a POST request with this data. Important: You must provide the Profile
obtained earlier in the “Amazon-Advertising-API-Scope” header to scope the creation of a campaign to a specific
advertiser account in a specific marketplace:
curl \
-X POST \
-H "Content-Type:application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Amazon-Advertising-API-Scope: YOUR_PROFILE_ID" \
--data @testCampaign.txt \
https://advertising-api-test.amazon.com/v1/campaigns
4
Amazon Advertising API Getting Started Guide
If you received a response indicating successful creation of your campaign, then you are done! The response
will contain an ID you can use to manage that campaign in the future.
Additional resources
For a mapping between the marketplace strings and countries, please refer to Amazon MWS endpoints and
MarketplaceId values.
5