Monetization Metrics API Overview

You can use the Monetization Metrics API to programmatically access subscription metrics, such as signups, renewals, cancellations, and reactivations, for your Fire TV and Fire tablet apps. These metrics are organized into metric sets, which are logical groupings of related metrics that share common attributes (freshness and granularity) and can be queried together. Each metric set supports dimensions that you can use to filter results or produce breakdowns.

Use of the Monetization Metrics API is subject to the Program Materials License Agreement.

• Prerequisites
• How it works
  • Freshness
• Data queries
• Available metric sets
  • Working with metric values
• Dimensions
  • Dimension values
• Related topics

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.

Explore the API using the interactive sandbox in the Developer Console. For more details, see API Explorer.

Freshness

Each metric set offers a standard GET 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.

Aggregation Period	Freshness SLA	Retention	Max Query Range
DAILY	T-1 Day	30 days	30 days per request
HOURLY	T-3 Hours	15 days	15 days per request

You should always check freshness before querying to know what date range will return data.

Interpreting 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 the POST :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.

For 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:

• activeSubscriptions is 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, totalReceipts equals the sum of fulfilled, unavailable, pending, notEligible, existingPurchase, and notDelivered. Use this to reconcile a breakdown against the total.
• The percentile metrics on subsFulfillmentMetricSet return null, not 0, when no receipt in the requested period was acknowledged. A null means there was no data to compute a percentile over; 0 would incorrectly assert an instantaneous acknowledgement. Count and revenue metrics are never null. They return 0 and 0.00 respectively.
• subsCancellationMetricSet and subsCancellationSurveyMetricSet both report cancellations but answer different questions.
  • Use subsCancellationMetricSet for how many subscriptions were canceled and whether the cancellation was voluntary or involuntary.
  • Use subsCancellationSurveyMetricSet to 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.

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	Type	Available on	Values	Description
marketplace	string	all metric sets	US DE JP GB FR IT ES CA BR MX IN AU	The marketplace where the subscription activity occurred. Two-letter ISO 3166-1 alpha-2 code.
termSku	string	all metric sets	free text, up to 256 characters	The term SKU of the subscription item the customer purchased.
deviceType	string	all metric sets	FIRE_TV FIRE_TABLET OTHER	Device form factor.
deviceOs	string	all metric sets	FIRE_OS VEGA_OS	Device OS type.
subscriptionType	string	all metric sets except subsRenewalMetricSet and subsFulfillmentMetricSet	REGULAR FREE_TRIAL INTRO	The pricing type of the subscription. Whether it's a standard paid subscription, a free trial, or on an introductory price.
purchaseChannel	string	subsFulfillmentMetricSet only	QS IAP	The channel the purchase came through.
renewalType	string	subsRenewalMetricSet only	REGULAR FREE_TRIAL_CONVERSION INTRO_CONVERSION	The nature of the renewal. A routine renewal, or a conversion from a free trial or introductory price.
cancellationType	string	subsCancellationMetricSet only	VOLUNTARY INVOLUNTARY	Whether the subscription was canceled by an explicit customer action (VOLUNTARY) or lapsed without one, such as a failed payment (INVOLUNTARY).
cancellationReason	string	subsCancellationSurveyMetricSet only	PRICE_RELATED NOT_USING_RELATED CONTENT_RELATED SERVICE_RELATED DISCOUNT_RELATED SPECIFIC_SHOW_RELATED TECHNICAL_ISSUE_RELATED PREFER_NOT_TO_SAY	The reason the customer selected in the cancellation survey. Survey response variants are normalized to this fixed set of reason codes.

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.

renewalType — The nature of the renewal. A routine renewal, or a conversion from a free trial or introductory 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.

purchaseChannel — Where the subscription purchase took place.

• 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.

cancellationType — How the cancellation happened.

• 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.

cancellationReason — The reason the customer selected in the optional cancellation survey. The survey has been presented with different wording across surfaces and over time, so multiple survey responses map to a single reason code. Each of the following codes lists the survey responses it includes.

• 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

---

Last updated: Oct 13, 2026