Prerequisites
Before making API calls, make sure you meet the following requirements:Base URL
The base URL of the Monetization Metrics API ishttps://developer.amazon.com/api/appstore.
Operations
The Monetization Metrics API includes the following operations and endpoints:{metricSetName} path parameter accepts the following metric sets: subsSignupMetricSet, subsRenewalMetricSet, subsReactivationMetricSet, subsCancellationMetricSet, subsActiveMetricSet, subsHealthMetricSet, subsCancellationSurveyMetricSet, and subsFulfillmentMetricSet.
Request
See the following sections for details on the parameters and validation rules.Request parameters
Every query request must include the following parameters:Validation rules
The API validates every query request before executing it. A request that violates any of the following rules is rejected with400 VALIDATION_ERROR; the response body’s message field describes the violation. The following examples show the message returned for each rule.
Response
The response shape differs by operation. The freshness check (GET) returns afreshnessInfo array with one entry per aggregation period, while the query endpoint (POST) returns a single freshness object matching the requested period.
GET freshness response fields
Successful response (200)
Headers
Body
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).
POST query response fields
Successful response (200)
Headers
Body
Implementation examples
The following examples show Python code for various tasks using the Monetization Metrics API.Obtain access token
Use your client ID and client secret to obtain an auth token. You must add the auth token to the header of each API request. The following example shows how to obtain an auth token and create the Authorization header using the token.Check data freshness
The following example shows how to check the latest available data timestamp before querying.Query signup metrics
The following example shows how to query daily signup metrics.Query with dimensions
The following example shows how to break down signups by subscription type and marketplace.Query with filters
The following example shows how to narrow results to only free trial signups in the US.Query hourly metrics
The following example shows how to query hourly data for near-real-time subscription monitoring.startTime to T00:00:00Z and endTime to T23:00:00Z. One row per hour is returned. Minutes and seconds in either bound are ignored (dropped to the enclosing hour).
Query fulfillment metrics
The following example shows how to query receipt delivery performance.Query subscription health
The following example shows how to track auto-renewal changes and grace period events.Query cancellation survey responses
The following example shows how to break down surveyed cancellations by the reason customers selected in the cancellation survey. This metric set supportsDAILY granularity only.
Paginate through results
The following example shows how to fetch all results when the response includes anextPageToken.
Error handling
All errors return structured JSON. The HTTP status line carries the status class (4xx/5xx); the body carries a machine-readable code, a human-readable message, and (for validation failures) a field-levelerrors[] array identifying each offending field.
Single-error example
Multi-field validation example
Error codes
Common mistakes and fixes
Retries and best practices
See the following sections for retry strategy and best practices.Retry strategy example
Production best practices
Related topics
- Monetization Metrics API Overview: Available metrics and dimensions
- API Explorer: Interactive API explorer on the developer portal
- Explore the API: Link to the API Explorer in the Developer Console

