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
This guide includes reference information for you to use to integrate the Monetization Metrics API. Use of the Monetization Metrics API is subject to the Program Materials License Agreement.

Prerequisites

Before making API calls, make sure you meet the following requirements:

Base URL

The base URL of the Monetization Metrics API is https://developer.amazon.com/api/appstore.

Operations

The Monetization Metrics API includes the following operations and endpoints: The {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 with 400 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 a freshnessInfo 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
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).

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.
To cover the whole day, set 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 supports DAILY granularity only.

Paginate through results

The following example shows how to fetch all results when the response includes a nextPageToken.

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-level errors[] 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

Last modified on October 13, 2026