Sales Reporting API

Developers can use the Reporting API to download sales reports.

Create a Security Profile

To use the Sales Reporting API, you need to create a security profile and request access to the API for this security profile. Security profile is the mechanism used to generate access tokens for API access.

To create a security profile, follow these steps:

  1. Login to your Amazon Developer Console account. You will be prompted to create an account if you do not already have one.
  2. In the main navigation, click Apps & Services.
  3. Click API Access
  4. Click the Create a new security profile button.
  5. Enter a Security Profile Name and Security Profile Description for your new profile, then click Save.
  6. Save your client ID and client secret, as you will need this information to access the Sales Reporting API.
  7. Return to the API Access page.
  8. Select your new security profile from the drop-down
  9. Select Attach to associate the security profile with the Reporting API.

You can now use the client ID and client secret to request a Login With Amazon (LWA) access token.

Request LWA Access Token

With your client ID and client secret, use the Login With Amazon API to request a Login with Amazon access token by following these steps:

1. Send token request

Send a POST request to https://api.amazon.com/auth/o2/token with the following header and content:

  • Header: Content-Type: application/x-www-form-urlencoded
  • Content:
    • client_id: The client ID you saved in step 5 of Create a Security Profile.
    • client_secret: The client secret you saved in step 5 of Create a Security Profile.
    • grant_type: Set to client_credentials.
    • scope: Set to adx_reporting::appstore:marketer.

Sample JSON content:

{
    "grant_type": "client_credentials",
    "client_id": "amzn1.application-oa2-client.ae941846cdd745e9a53319f7bb98d435",
    "client_secret": "41d135b2b02ce5f2fbf7643a66477c089fcc1d88d11f69d3e4a6285b917ca35d",    
    "scope": "adx_reporting::appstore:marketer"
}

Sample cURL request:

curl -k -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=amzn1.application-oa2-client.5c1462ee102c4a57a5224d0c72118741&client_secret=15d1829ddf4f12d1c5d425e57e5ca081d0f7a63bd94c9e142ff8b20d9de880a4&scope=adx_reporting::appstore:marketer' https://api.amazon.com/auth/O2/token

2. Save the response

The response looks like this:

{"access_token":"Atc|MAEBIBav2tvCbJOA9Jv5sRpej6xY_qzHFuCpbWT-Z94nRqVWVcfmZVNPEhZiet-H3vdQcORqE5pO4fCKEi6kfvzzPtxHIoPIte-ZbKB1XgfjfJnciJHqnbV1UF4WJ_an1g9y7yvWKWJddQ2NLPO-C-Y71BPxJ0KDWOPonn_2qFLY5OJo3BhHKIwNHteQAwkCA9iko8d5tosS7fo3dvS-PFmiBk3OMUmr1AdYtuOnq1RVrX7-C14oWzfACudykTn5cDb48Qy2k6R70__GzHG3fC_-Rfzt7zwhfdBWpwoQk-GbV4Bes457oZwHz89Tj-AAf3DouYQ","scope":"adx_reporting::appstore:marketer","token_type":"bearer","expires_in":3600}
  • access_token: The access token.
  • 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.

3. Handle any error responses

If your token request results in an error, the response message body includes one of the following error messages:

Error message body Details
{"error_description":"Client authentication failed","error":"invalid_client"} Invalid secret key
{"error_description":"The request has an invalid parameter : scope","error":"invalid_scope"} Invalid scope value
{"error_description":"The authorization grant type is not supported by the authorization server","error":"unsupported_grant_type"} Incorrect authorization grant type
{"error_description":"The Content-Type is not supported by the authorization server","error":"invalid_request"} Unsupported content-type

How to use the access token

Once you have obtained a valid access token, send a request to the Reporting APIs with the Authorization header set. The value of the Authorization header is Bearer <YOUR_ACCESS_TOKEN>, where <YOUR_ACCESS_TOKEN> is the value of the access_token field in the response from Request LWA Access Token. The access token is a long string of characters beginning with "Atc|".

Sample cURL request:

curl -v -k -X GET "<see below for URL format>"   -H  "Authorization: Bearer Atc|MAEBIKfsULrH7jSzvJTV8UmiHWr9M86O3JRmv4t1hqoCBriSMEP5Gsey_FiBxteZ8oxGd6abGuOFga8fwnMhmSD_Sg4MI4odXLPgB2IVs8M1uswjuWjnsMcvehpWvf9tzQT8HTWiBigInJLB8BrMg5J3O02hlTvcF441XxXDXthyj993COJ2u5swOTKjC_dcijiN8amuzrj32rh9Fr3CNgCpoZ0WqXnBhoHUVMYSOBV-owA5rI4-OfysXC71Zbtv1hb8igk"  

When the access token expires, get a new one by following the procedure above in Request LWA Access Token and start using the new access token in your requests. You will know your access token has expired if it has been over an hour since you last requested an access token and you start getting 403 Forbidden HTTP errors with a message that says "Request is not authorized."

Sales Reporting API URL

Use the following as the base URL for sending Sales Reporting API requests:

developer.amazon.com

Request sales report URL

You can use the Sales Reporting API to download a single sales report file. The API request returns a URL which you can use to download the file from the secure S3 storage location.

Syntax

/api/appstore/download/report/sales/<year>/<month>

Parameters

Year The four-digit year of the report file to be downloaded
Month Two digit month value for the report file

Example

The following example shows how to request the sales report for January 2018.

Request:

curl -v -k -X GET "https://developer.amazon.com/api/appstore/download/report/sales/2018/04" -H "Authorization: Bearer Atc|MQEBIDdrcC586BxhFBdS7FQVS454oUO-fo90H5gUYVMZB1UVsPFoOPLj_zrpkf9BuMrx-PksU_qDJHL-PJ5suEQTigL1tv7A6AKlyoJJaoyzyzKhd0dwWw3LWUGrlxXxW459nJJH66F89GSBolrmlfuNONly8Cbts2Fy_KHI9YwvzwSVcgf_nvefss_H1O8tsvoYpORVuL8IXBrzT7bHxU0Xj5VjiaxDtU6N4oOQafefT8AcdN0IOYnh3Us8uEeeur3_OH473JwO3SjA4NRaS61Aq37UyhvM9pK3ccGOO5JoMkw1V9kDQQVhKiGWfCoTUBlaVkU"

Response:

https://appstore-adx-reporting.s3.amazonaws.com/85923/sales/sales_2018_01.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20180405T060912Z&X-Amz-SignedHeaders=host&X-Amz-Expires=299&X-Amz-Credential=AKIAJMFYXPVLQKTRRB7Q%2F20180405%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=adab43be54631565d330727383341d56989d129e4dea151411cf7a802b9e5e12

Errors

If your token request results in an error, the response message body includes one of the following error messages:

Error Details
{"Message":"Request is not authorized."} Incorrect Access Key, or the requested report is out of scope (for example, if a marketer requests a payments/agency report).
{"Message":"Unable to fetch the request scope for uri = (URL Entered) and verb = GET"} Invalid URL or method.

Use the S3 URL to download the report

The reporting API returns an S3 URL, which you can use to download the report.

Error messages:

Amazon S3 may return one of the following errors:

Report Not Found You try to retrieve a file, but a file with the specified name does not exist in the S3 folder.

Server Unavailable If the S3 bucket is not available when you try to download the report, you will receive an HTTP 404 error code.

For additional information, see S3 error responses.

Reporting API FAQ

Q: What is the earliest report that I can retrieve using the API?

The earliest available report is January 2018. Reports for 2017 and earlier years are currently not available.

Q: How do I delete the security profiles?

Security profiles can be deleted only by admin level users. Navigate to the Security Profiles tab under Apps&Services, choose and delete the required security profiles.

Q: Why cURL commands have scopes defined as Marketer?

Scope is a required field for API access. Marketer is defined as a default scope for the sales reporting API.

Q: Can the access token and pre-signed S3 URL be used forever?

No, The access token is valid only for one hour. The pre-signed S3 URL is valid only for 5 minutes. These timeouts are for security reasons.

Q: Can the security profile Client ID and Client Secret be used forever?

Yes. They can be used until the day security profile is deleted from Developer Console. However, for your security, we strongly recommend you update your API associated security profiles at least once every 6 months.

Q: I have 5 admins in the team. Can all of them create security profiles? If yes, how is it managed?

Yes, all the 5 admins can create security profiles. Every admin can see all the security profiles (Even the profiles created by other admins)

CSV file format

The CSV file is a text file with a .csv file extension. The CSV file must use UTF-8 encoding, to support localized strings.

The CSV file contains one header row (which displays the column titles). Each subsequent row in the file contains the information for one report item. The Invoice ID field defines a unique identifier for each line-item in the report.

The CSV file is a text file with a .csv file extension. The CSV file must use UTF-8 encoding, to support localized strings.

The CSV file contains one header row (which displays the column titles). Each subsequent row in the file contains the information for one report item. The Invoice ID field defines a unique identifier for each line-item in the report.

The following table describes the fields for each entry (row) in the CSV file:

Field Type Description Example
Marketplace String The Amazon marketplace Amazon.com
Country/Region Code String Standard two-digit ISO country/region code for the origin of the transaction. Refer to this list US
Invoice Id String The unique Id for the invoice. This field is set to NA for 2017 and older summary data 8dd921637-b092f385a7ee4-62c6494b3ed702f113
Transaction Id Integer The unique Id associated with this transaction. This field is set to NA for 2017 and older summary data as the sales information includes all transactions in a given day 21854260140446
Transaction Time String The date and time of the transaction. Format is MM/DD/YY HH:MM:SS XST, with 00-23 as the range of hours. XST is the time zone associated with the marketplace of the transaction. For 2017 and older data, this field indicates the date of sale. 05/21/18 14:39 PST
Transaction Type String The transaction type is either Charge or Refund Charge
Adjustment Yes or No This field is set to Yes if the transaction is an adjustment. For 2017 and older data, if the transaction type is Refund, this field will show a null value. Yes
Vendor SKU String String of up to 150-characters that can include the characters a-z, A-Z, 0-9, underscores, periods, and dashes. The SKU is case-sensitive. com.gamevendor.fungame
Title String The title of the app or game. Smashemup Truck Game
Item Name String Name of the app, game, subscription, in-app item or in-game item. Smashemup Truck Game
Item Type String The type of the item. Values include Subscription, App, In-App, Game or In-Game Application
In-App Subscription Term String The term of the subscription. The term can be weekly, biweekly, monthly, bimonthly, quarterly, semi-annually, or annually. This field is applicable only if the item type is Subscription.
This field is not applicable to Twitch.
Weekly
In-App Subscription Status String The status can be Trial or Paid. This field is applicable only if the item type is Subscription.
This field is not applicable to Twitch.
Trial
Units Integer Number of units included in this transaction. 1
Usage Time String The usage time for an Underground app (in minutes). This field is applicable only to Appstore underground products. To calculate the number of units, divide the usage time by 60. For example, usage time of 1200 is 20 units.
This field is not applicable to Twitch.
1200
Marketplace Currency String The marketplace determines the currency of the transaction. See the Marketplace Timezones table. USD
Sales Price Marketplace Currency Selling price that the customer sees after any discounts, not including sales tax. For underground apps, sales price represents the earnings based on number of minutes of app usage. Sales and earnings are the same for Underground apps. For adjustments and refunds, the sales price for the original item is shown. The actual adjusted amount or refunded amount might be different than the sales price (such as a partial refund). 4.99
Estimated Earnings Marketplace Currency Estimate earnings after deducting for Amazon royalties from this transaction. For adjustments and refunds, earnings are shown based on the adjusted amount or the refunded amount. 3.49

Notes

  • The sales data is updated every 24 hours. If you are automating your data pull, the recommendation is to run your scripts every 24 hours to get the latest information. Note that the reported information can have up to 48 hours of lag.
  • The API supports up to 3 requests per second. API calls made more frequently may lead to degraded performance.
  • The earnings are estimated in this file. It may not match exactly with your end of month earnings report which may include additional adjustments not captured here.
  • All adjustments are shown in the month in which the adjustment is made and not in the month the original transaction occurred.
  • Test ASINs show null values for “Title” and “Item Name”. This known issue will be fixed in a future release.

Marketplace information

The following table displays the country/region abbreviations and currency types for each Marketplace.

Country/Region
Abbreviation
Currency
Abbreviation
Currency Marketplace
AU AUD Australian Dollars Amazon.com.au
BR BRL Brazilian Reals Amazon.com.br
CA CAN Canadian Dollars Amazon.ca
CN CHY Chinese Yuan Renminbi Amazon.cn
DE EUR Euros Amazon.de
ES EUR Euros Amazon.es
FR EUR Euros Amazon.fr
GB GBP Pounds Sterling Amazon.co.uk
IN INR Indian Rupees Amazon.in
IT EUR Euros Amazon.it
JP JPY Japanese Yen Amazon.co.jp
US USD Dollars Amazon.com

API Data Security

All data that you can access through the Sales 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 this information.

If you decide to share your API access with a third party, please follow these guidelines:

  1. Create a dedicated security profile for the third party.
  2. Include the third party business name in the security profile name (such as ReportingAPI_<your company name>_<third party name>).
  3. In the security profile description field, clearly describe who will be using the security profile.

For your own protection, we strongly recommend that you update your security profiles every six months (all security profiles associated with the sales reporting API).