Starting today, you can download sales reports programmatically through the Appstore Sales Reporting API, with the ability to download compressed CSV files with transactional monthly sales data.

With the API, developers are no longer required to log in into the developer portal through the UI on a daily basis to pull the developer reports. The API allows developers to automate this process, saving time and improving efficiency.

These reports are updated every 24 hours (12:00 am UTC). You can automate sales data and analysis through this API in addition to your current process of logging into the developer portal and downloading summary sales data. The reporting API is a RESTful API, so there is no SDK required. You can use your favorite scripting language to call the API. Setting up the API access through Amazon should take less than five minutes.

Steps to access the API 

There are three simple steps to get the reports through the API. First, create a security profile on the developer portal. Second, associate the security profile to the reporting API. Finally, use security credentials from the security profile to create a token which can be used to get a secure link to download the reports.

Step 1: Create a security profile

A security profile provides the API keys to gain access to the reports. Security profiles can be created by any developer with admin credentials.

To create a security profile, log in into your Amazon developer portal account here. Open your developer console and go to the Apps and Services tab in the top navigation and then click on Security Profiles.
 

On the security profiles page, you will see the list of security profiles you have already created within your account and an option to create a new security profile. For API access, we recommend you create a new security profile with a descriptive name. If you prefer to use an existing security profile, you can skip to step two.

To create a security profile you need to fill in security profile name and security profile description. Hit the Save button for a new security profile to be generated.
 

Save the client ID and Client Secret. These two strings are required to secure a token and download the report.

Step 2: Associate the security profile with the reporting API

Go to the API access page in the top navigation under Apps and Services.
 

On this page, you will see a dropdown to select an existing security profile to associate with the reporting API. From the dropdown, select the security profile name you just created in Step one and click Attach. Once this is done, the specific security profile and the credentials are ready to be used for procuring a token and downloading the reports. These first two steps are required only once until you change the credentials again.

Step 3: Procure a token and download the report

With your client ID and client secret, send a POST request to the following endpoint to get your access token.

Header: Content-Type: application/x-www-form-urlencoded

• client_id : The Client ID you saved in step 1
• client_secret : The Client Secret you saved in step 1
• grant_type : Set to client_credentials .
• scope : Set to adx_reporting::appstore:marketer .

You can find sample JSON and cURL request in the tech documents here.

The response from the request will have the following fields.

• access_token : The access token. The access token string always starts with “Atc.”
• expires_in : The number of seconds until the access token expires.
• scope : Will always be adx_reporting::appstore:marketer .
• token_type : Will always be bearer

The token will be valid for one hour.

Use this token along with the authorization header and the URL shown below to get a link with the report.

• The URL: https://developer.amazon.com/api/appstore/download/report/sales/<year>/<month>
• Authorization will always be “bearer”

Example cURL request is shown below for accessing sales reports for the month of March 2018:

curl -v -k -X GET "https://developer.amazon.com/api/appstore/download/report/sales/2018/3" -H "Authorization: Bearer 
Atc|MAEBINAn3eY20pfwmyLZNEB2deSyLiOTVZBBCGNfE0Aq8wS2unVWk6ZKuKy27bS5nJF4e6TuP4IoatoBgZ
CkKiipsrAbJZHtd28CyuEAamlMinfPcwPANXGA4qnkVacvcNNJls4hw3qLqkD_i11wY6cMeGaWt7R8YmQDbsLZ
TXBvSnEYYHpuFwrYjlYGW0eH6wFtnoVf4gmzrxLmwkzoQ8jb97rXkim_SbFLyRryXRtd5NkVoWgU3lCcm5WZit
lLhJy4PSygcSz1a5GQNTuDJaieOnDS9DAebKv0Wvc0Uk0N0NAg8piZGmj0frUcfeVZbwc59JoSVH4IlpHQJ0Jows"

In response to this request, you will receive a compressed CSV file through an AWS S3 3 link. Sample response shown below:

https://appstore.s3.amazonaws.com/85923/sales/sales_201
8_03.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20180405T060912Z&X-Am
z-SignedHeaders=host&X-Amz-Expires=299&X-Amz-Credential=AKIAJMFYXPVLQKTRRB7
Q%2F20180405%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=adab43be5463156
5d330727383341d56989d129e4dea151411cf7a802b9e5e12

The link will be active for five minutes for download.

The downloaded CSV file will have transactional sales information with the following fields: Marketplace, country/region code, invoice ID, transaction ID, transaction time, transaction type, vendor SKU, title, item name, item type, in-app subscription term, number of units of purchase, usage time for Underground apps, marketplace currency, sales price (in marketplace currency), and estimated earnings (marketplace currency).

You can download this transactional sales data from January 2018.

Learn more

To review additional code samples and to understand the measures you can take to protect your data, refer to the Reporting API documentation here.

We hope you enjoy these new improvements. If you have any feedback, please reach out to our support team.

Disclaimer: Please note that all data that you can access through the Reporting API is Amazon confidential and is intended for the use of the developer only. If you give API access to trusted third-parties (to support your day-to-day operations), you are agreeing to share that information at your own risk. Amazon assumes no responsibility for any loss or damage caused by sharing your credentials.