Prerequisites
You need the following before you can call the API:- An Amazon Developer Account with Admin level credentials
- A Security Profile mapped to the Reporting API (created through the Developer Console > My Settings > API Access)
- The Client ID and Client Secret from the profile’s Web Settings tab
- Your app’s package name
How it works
Data flows from raw subscription events into daily and hourly aggregation tables.- Daily metrics provide one data point per day, available at T-1 day.
- Hourly metrics provide one data point per hour, available at T-3 hours. This is useful for early trend detection after a promotion or pricing change.
Freshness
Each metric set offers a standardGET method to retrieve the timestamp of the latest available data, known as freshness. Since a metric set can support multiple granularities (daily, hourly), the operation returns one freshness value per supported granularity.
latestDataTimestamp: The value is an ISO 8601 UTC instant labeling the latest fully-complete aggregation bucket. The label is the bucket’s start instant, and the entire bucket is complete. For HOURLY, Thh:00:00Z means the hh:00–hh:59 hour is complete (for example, 2026-07-06T14:00:00Z means the 14:00–14:59 hour is done). For DAILY, YYYY-MM-DDT00:00:00Z means that whole UTC day is complete (for example, 2026-07-06T00:00:00Z means all of July 6 is done).
Data queries
To access the data in a metric set, use thePOST :query method. Each query must specify a granularity and a time range. Together with the metrics you want to access, you can specify dimensions to break down the aggregations or specify filters to narrow results without adding breakdowns.
The results differ depending on whether you do or don’t specify dimensions with your query.
- With dimensions: You get one row per unique dimension combination per time period.
- Without dimensions: You get a single aggregate number per time period.
HOURLY queries, specify the hour directly in the ISO 8601 timestamp, for example "2026-08-30T14:00:00Z". Both bounds are inclusive. To cover a full day, set startTime to T00:00:00Z and endTime to T23:00:00Z. Fields finer than the aggregation period are ignored. Minutes and seconds are dropped to the enclosing hour on HOURLY queries, and hours and finer are dropped on DAILY queries.
Available metric sets
The following table lists all available metric sets and their descriptions.| Metric Set | Description | Supported Metrics |
|---|---|---|
subsSignupMetricSet | Subscription signups and signup revenue. | signups (Number): New subscriptions started in the period. signupRevenue (Number): Revenue from those signups. |
subsRenewalMetricSet | Subscription renewals and renewal revenue. | renewals (Number): Subscriptions renewed in the period. renewalRevenue (Number): Revenue from those renewals. |
subsCancellationMetricSet | Voluntary and involuntary cancellations, and refund amounts. | cancellations (Number): Subscriptions canceled in the period. cancellationRefunds (Number): Refunds issued against those cancellations. |
subsReactivationMetricSet | Previously canceled subscriptions that were reactivated. | reactivations (Number): Subscriptions that had been canceled earlier and were restarted in the period. reactivationRevenue (Number): Revenue from those reactivations. |
subsActiveMetricSet | Active subscription counts. DAILY granularity only. | activeSubscriptions (Number): Subscriptions active at the end of that day. |
subsHealthMetricSet | Auto-renewal and grace period events. | autoRenewalOff (Number): Subscriptions where the auto-renew feature was turned off. autoRenewalOn (Number): Subscriptions where the auto-renew feature was turned on. gracePeriodEntries (Number): Subscriptions entering a payment grace period. gracePeriodRecoveries (Number): Subscriptions that recovered from a grace period after payment issue/failure is fixed. |
subsCancellationSurveyMetricSet | Cancellation survey responses. DAILY granularity only. | surveyedCancellations (Number): Cancellations attributed to each survey response, broken down by cancellationReason. |
subsFulfillmentMetricSet | Receipt delivery health and acknowledgment latency. | totalReceipts (Number): Receipts issued in the period. fulfilled (Number): Receipts your app acknowledged successfully. unavailable (Number): Receipts your app marked as unavailable. pending (Number): Receipts delivered but not yet acknowledged. notEligible (Number): Receipts not eligible for fulfillment. existingPurchase (Number): Receipts for a subscription the customer already owned. notDelivered (Number): Receipts never delivered to the app. p50AcknowledgementDelay, p90AcknowledgementDelay, p95AcknowledgementDelay (Number): Acknowledgment delay in seconds. |
Working with metric values
A few things to know when interpreting metric values:-
activeSubscriptionsis a point-in-time count of subscriptions active on each day, not a total of events during the period. Summing it across days double-counts the same subscribers. -
Revenue or refunds always pair with a count metric in the same metric set -
signups/signupRevenue,renewals/renewalRevenue,cancellations/cancellationRefunds,reactivations/reactivationRevenue. Use the counts for volume and the revenue metric for monetary value. -
In
subsFulfillmentMetricSet,totalReceiptsequals the sum offulfilled,unavailable,pending,notEligible,existingPurchase, andnotDelivered. Use this to reconcile a breakdown against the total. -
The percentile metrics on
subsFulfillmentMetricSetreturnnull, not0, when no receipt in the requested period was acknowledged. Anullmeans there was no data to compute a percentile over;0would incorrectly assert an instantaneous acknowledgement. Count and revenue metrics are never null. They return0and0.00respectively. -
subsCancellationMetricSetandsubsCancellationSurveyMetricSetboth report cancellations but answer different questions.- Use
subsCancellationMetricSetfor how many subscriptions were canceled and whether the cancellation was voluntary or involuntary. - Use
subsCancellationSurveyMetricSetto break the cancellations down by the reason the customer selected in the cancellation survey. Survey responses are optional, so survey totals can be lower than cancellation totals for the same period.
- Use
Dimensions
Each metric set supports a common set of dimensions for filtering and breakdowns. Each dimension is available on the metric sets listed in the Available on column.Dimension values
Some dimensions use coded values. This section explains what each value stands for. subscriptionType — The pricing type of the subscription. Whether it’s a standard paid subscription, a free trial, or on an introductory price.REGULAR: A subscription being charged the standard price.FREE_TRIAL: A subscription in its free-trial period; the customer hasn’t yet been charged.INTRO: A subscription in an introductory-price period, charged at a discounted rate before switching to the standard price.
REGULAR: A routine renewal of a paid subscription at its existing price.FREE_TRIAL_CONVERSION: The renewal that converted a free trial into a paid subscription. The customer’s first charge.INTRO_CONVERSION: The renewal that moved a subscription from its introductory price to the standard price.
QS(Quick Subscribe): The customer subscribed outside the app, for example with one click from the app’s detail page on a Fire device or from the app’s Amazon retail web page.IAP(In-App Purchase): The customer signed in to the app and purchased from within the app using the standard in-app purchasing flow.
VOLUNTARY: The subscription was canceled by an explicit customer action, such as turning off auto-renewal or contacting customer support to cancel.INVOLUNTARY: The subscription was canceled without an explicit customer action, such as a failed or incomplete payment, including expiration of the payment grace period.
PRICE_RELATED: Price-related dissatisfaction. “Subscription too expensive/price increased”, “Subscription price increased”, “Too expensive compared to other services”, or “Price is too high”.NOT_USING_RELATED: “Not using the streaming service enough”.SPECIFIC_SHOW_RELATED: “I signed up to watch one specific show/movie/sports event”.CONTENT_RELATED: Content dissatisfaction. “Not enough TV shows, sports, and movies to watch” or “Dissatisfied with the content/service”.TECHNICAL_ISSUE_RELATED: Technical or device problems. “Too many crashes/freezes/issue logging in”, “Issue logging into the streaming service”, “Too many crashes or freezes”, or “Dissatisfied with my device”.DISCOUNT_RELATED: A promotional price ended. “Free trial/discounted subscription price ended” or “Discounted subscription price ended”.SERVICE_RELATED: “Switching to another service”.PREFER_NOT_TO_SAY: Declined to give a specific reason. “Prefer not to say”, “None of the above”, or “Something else”.
Related topics
- Monetization Metrics API Reference: Prerequisites, authentication, API endpoints, code examples, error handling, and best practices
- Reporting API: Sales, earnings, and subscription report downloads
- Explore the API: Link to the API Explorer in the Developer Console

