Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Devices
Build
Test
Publish
Connect
Documentation
Skip to main content
Developers can use the Reporting API to download sales, earnings, and subscription reports. To use Developer Console APIs, you need to create a security profile and map the security profile to the API. Security profile is the mechanism used to generate access tokens for API access.

Create a Security Profile

To create a security profile, follow these steps:
  1. Sign in to your Amazon Developer Console account. You will be prompted to create an account if you do not already have one.
  2. From the top navigation, select My Settings > API Access.
  3. Click the name of the API. API Access page
  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 (from the Web Settings tab), as you will need this information to access the Sales Reporting API. Client ID and Client Secret

Map the Security Profile to the API

To map the security profile to the API, follow these steps:
  1. Return to the API Access page.
  2. Click the API name to select the API.
  3. Select your new security profile from the drop-down list.
  4. Select Attach to associate the security profile with this API. The API name and attached security profile is added to the Security Profile(s) in use panel. Client ID and Client Secret
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 7 of Create a Security Profile.
    • client_secret: The client secret you saved in step 7 of Create a Security Profile.
    • grant_type: Set to client_credentials.
    • scope: Set the value to appstore::apps:readwrite (or adx_reporting::appstore:marketer for the Reporting API).
Sample JSON content:
Sample cURL request:

2. Save the response

The response looks like this:
  • access_token: The access token.
  • expires_in: The number of seconds until the access token expires.
  • scope: Will be appstore::apps:readwrite (or adx_reporting::appstore:marketer for the Reporting API).
  • 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 bodyDetails
{“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:
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.”

Reporting API URL

Use the following as the base URL for sending Reporting API requests: developer.amazon.com

Request report file URLs

You can use the Reporting API to download the following files:
  • Single sales or subscription report file
  • Earnings and payments report file
  • Subscription overview 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> /api/appstore/download/report/earnings/<year> /api/appstore/download/report/earnings/<year>/<month> /api/appstore/download/report/subscription/<year>/<month> /api/appstore/download/report/subscriptions_overview/<year>/<month> Parameters
YearThe four-digit year of the report file to be downloaded
MonthTwo digit month value for the report file

Example

The following example shows how to request the sales report for April 2024. Request:
Response:

Errors

If your token request results in an error, the response message body includes one of the following error messages:
ErrorDetails
{“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:

You may receive one of the following error messages from the API: Report Not Available: You try to copy a file, but a file with the specified name does not exist in the S3 folder: fatal error: An error occurred (403) when calling the HeadObject operation: Forbidden User not authorized: If you try to use the Reporting API without a valid access token. Server Unavailable: If the API server is unavailable when you send a request, or 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

Sales report fields

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 following table describes the fields for each entry (row) in the CSV file.
FieldTypeDescriptionExample
MarketplaceStringThe Amazon marketplaceAmazon.com
Country/Region CodeStringStandard two-digit ISO country/region code for the origin of the transaction. Refer to this listUS
Invoice IdStringThe unique Id for the invoice. This field is set to NA for 2017 and older summary data8dd921637-b092f385a7ee4- 62c6494b3ed702
Transaction IdIntegerThe 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 day21854260140446
Transaction TimeStringThe 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 TypeStringThe transaction type is either Charge, Refund, , or Charge
AdjustmentYes or NoThis 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
ASINAlphanumeric StringAmazon Standard Identification Number (ASIN) for the App/In-App/Subscription.C00006M4PF
Vendor SKUStringString 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
TitleStringThe title of the app or game.Smashemup Truck Game
Item NameStringName of the app, game, subscription, in-app item or in-game item.Smashemup Truck Game
Item TypeStringThe type of the item. Values include Subscription, In-App, Game, In-Game, or Application. An Application refers to an app purchase, which is a new app installation that is unique to an Amazon account. Application items do not include app updates.Application
In-App Subscription TermStringThe term of the subscription. The term can be Weekly, BiWeekly, Monthly, BiMonthly, Quarterly, SemiAnnually, or Annually. This field is applicable only if the item type is Subscription.
This field is not applicable to Twitch.
Weekly
In-App Subscription StatusStringThe status can be TRIAL, PAID, Introductory Price - All Customers, or Promotional Price - Lapsed Customers. This field is applicable only if the item type is Subscription. For more details, see In-App Subscription Status.
This field is not applicable to Twitch.
TRIAL
UnitsIntegerNumber of units included in this transaction.1
Usage TimeStringThe usage time for an Underground app (in seconds). 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 CurrencyStringThe marketplace determines the currency of the transaction. See the Marketplace Timezones table.USD
Sales PriceMarketplace CurrencySelling 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, the sales price for the original item is shown. The actual adjusted amount or absolute refunded amount might be different than the sales price (such as a partial refund). For refunds and chargebacks (Transaction type - Refund, Chargeback), the equivalent sales price will be negative.4.99
Estimated EarningsMarketplace CurrencyEstimate 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. Refunds that are deducted from vendor’s account are shown as negative values for reports having earnings corresponding to period from Nov’19 onwards.3.49
App User IDStringUnique customer identification for the transaction. App User ID is not available in the following scenarios:
  • Item Type is “Application”
  • Adjustment (Yes/No) is “Yes”
  • The subscription is in “Paused” status
hQygC+MjonyR2Z0TMY03nyxeVxqIHq3+rK39TGzhkk0=
Receipt IDStringUnique receipt identification for the transaction. Receipt ID is not available in the following scenarios:
  • Item Type is “Application”
  • Adjustment (Yes/No) is “Yes”
  • The subscription is in “Paused” status
EgL-HstEAXhMfTuQ5_NkhQicjp_sRpJ5Lic78cF-3HY=:1:13
Digital Order IDStringUnique order identification for the transaction.d01-6680198-0475238
Device TypeStringThe type of device in which the customer makes purchases. The type category ‘Others’ includes app purchases made on uncategorized device types (eg., app purchases through the web).Fire TV
Sales channelStringIdentifier field used to delineate Quick Subscribe related purchases (Subscription and Application). Field value ‘QS’ indicates that the transaction is Quick Subscribe related.QS
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.

Earnings and payments reports fields

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 following table describes the fields for each entry (row) in the CSV file.
FieldTypeDescriptionExample
MarketplaceStringThe Amazon marketplace.Amazon.com
Invoice Group IDStringThe unique Id for the invoice.8dd921637-b092f385a7ee4-62c6494b3ed702f113
Invoice IDStringThe sub invoice Id for the invoice.Default value is “NA”
Payment IDIntegerThe unique Id associated with this payment.119399812
Earning Period Start DateStringThe date and time of the start of the earning period. Format is YYYY-MM-DD HH:MM:SS XST, with 00-23 as the range of hours. Times are shown in the in the time zone associated with the marketplace of the transaction.2017-11-01 00:00:00 EDT
Earning Period End DateStringThe date and time of the end of the earning period. Format is YYYY-MM-DD HH:MM:SS XST, with 00-23 as the range of hours. Times are shown in the in the time zone associated with the marketplace of the transaction.2017-12-01 00:00:00 EDT
Earnings Pre-Tax and AdjustmentsNumber (currency)Earnings amount during the earning period.218.92
Earnings Pre-Tax and Adjustments CurrencyStringThree letter currency value of the earnings amount.EUR
AdjustmentsNumber (currency)Adjustments to the earnings.218.92
Adjustments CurrencyStringThree letter currency of the adjustments value.EUR
Tax WithheldNumber (currency)Amount of tax withheld from the earnings.218.92
Tax Withheld CurrencyStringThree letter currency of the Tax Withheld value.EUR
Exchange RateNumberExchange rate used to convert the earnings amount into the home currency.0.88804
Mode of PaymentStringThe type of the payment. Values include EFT, Check, or WireEFT
Payment AmountNumber (currency)Payment amount in the currency determined by your bank’s location.218.92
Payment Amount CurrencyStringThree letter currency of the Payment Amount value.GBP
Payment StatusStringStatus of the payment. Values include Issued, Not Issued, and RejectedIssued
Payment Issue DateStringThe date and time when Amazon issued this payment. Format is YYYY-MM-DD HH:MM:SS XST, with 00-23 as the range of hours. Times are shown in the time zone of the associated marketplace.2017-11-01 00:00:00 EDT
Payment Failure DateStringThe date that the payment failed to process.2017-11-01 00:00:00 EDT
Aws Credit EarnedNumber (currency)AWS credit earnings amount. Ten percent of total earnings for the associated marketplace. Excludes refunds and chargebacks.218.92
Aws Credit Earned CurrencyStringThree letter currency of the AWS credits earned.GBP
fx_rateNumberForeign exchange rate used to convert the AWS credit earnings amount from the home currency into USD.1.2124
Aws Credit Earned In USDNumber (currency)AWS credit earnings amount in USD.1005.37
AWS Credit Issued CurrencyStringThree letter currency of the AWS credits issued. The value is always USD.USD
Aws Credit Issued in USDNumber (currency)Amount of AWS credits issued in USD.1005.37
Aws Credit Issued Date TimeStringThe date and time of when the AWS credits were issued. Format is YYYY-MM-DD HH:MM:SS XST, with 00-23 as the range of hours. Times are shown in GMT.2023-01-29 00:00:00 GMT
Credit StatusStringStatus of the AWS credits. Values include Successful and Not Issued.Successful

Subscription report fields

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 following table describes the fields for each entry (row) in the CSV file.
FieldDescriptionExample
DateThe subscription data for this record was collected on this date.12/29/18
MarketplaceThe Amazon marketplace associated with the data in this record.Amazon.com
App TitleThe subscription is for the app with this title.My Test App
ASINAmazon Standard Identification Number (ASIN) for the subscription.C00006M4PF
Vendor SKUThe SKU of the subscription.com.test.monthly
Subscription TitleThe title of the subscription.Test Monthly Subscription
Subscription DurationThe duration of the subscription.Monthly
Subscription TypeThe subscription type has the value trial or paid.paid
ActiveThe total number of active subscriptions at the end of the specified day (11:59 PM UTC).7261
StartedThe number of subscriptions initiated during the specified day163
EndedThe number of subscriptions that were cancelled or ended without renewal during the specified day.163
RefundedThe number of subscriptions that were refunded during the specified day.163

Subscriptions overview downloadable report fields

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 following table describes the fields for each entry (row) in the CSV file.
FieldTypeDescriptionExample
DateStringThe date and time when the event was triggered. Format is MM-DD-YYYY.03-13-2023
Device TypeStringThe device type on which the event was triggered. The Amazon Fire TV device type contains separate data for Amazon Fire TV (Fire OS) and Amazon Fire TV (Vega OS).Fire TV
MarketplaceStringThe Amazon marketplace in which the event occurred. Valid values: Amazon.com, Amazon.co.uk, Amazon.de, Amazon.fr, Amazon.it, Amazon.es, Amazon.co.jp, Amazon.ca, Amazon.com.br, Amazon.com.au, Amazon.in, Amazon.com.mx, ALL.Amazon.com
App ASINAlphanumeric StringAmazon Standard Identification Number (ASIN) for the app.C00006M4PF
App NameStringName of the app that corresponds to the ASIN.
Subscription SKUAlphanumeric StringUnique alphanumeric code for the subscription.
Subscription ASINAlphanumeric StringAmazon Standard Identification Number (ASIN) for the specific subscription. Note: One app ASIN can have multiple Subscription ASINs.
Subscription durationStringPlan duration offered for a specific Subscription ASIN. Values: Day, Week, Month, Year.Month
Subscription titleStringTitle of the subscription that corresponds to the subscription ASIN.Standard Monthly
Total subscriptions revenueIntegerTotal revenue generated on the specific day in USD. This includes all amounts paid by users (excluding taxes).2908800
Active subscriptionsIntegerNumber of subscriptions that were active on the day. This includes users with free trials.153396
New subscriptionsIntegerNumber of subscriptions that started on the specific day. This includes users with free trials.5623
Renewed subscriptionsIntegerNumber of subscriptions that were renewed on the day. This includes users with free trials.10938
Cancelled subscriptionsIntegerNumber of subscriptions that were canceled on the specific day. This includes cancellations within a free trial.850
Reactivated subscriptionsIntegerNumber of subscriptions that were active at an earlier time period (prior to the specific day), canceled, and reactivated on the specific day.1879

Marketplace information

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

API Data Security

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 responsible for any access to or use of API data by those third parties. 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).
Last modified on June 29, 2026