Monetization Metrics API概述
您可以使用Monetization Metrics API以编程方式访问Fire TV和Fire平板电脑应用的订阅指标，例如注册、续订、取消和重新激活。这些指标被划分为多个指标集，即相关指标的逻辑分组。同一指标集中的相关指标具有一些共同属性（新鲜度和粒度），可以一起查询。每个指标集都支持多个维度，这些维度可用于筛选结果或生成细分。
Monetization Metrics API的使用须遵守程序材料许可协议。
先决条件
在调用API之前，您需要具备以下条件：
- 具有管理员级别凭证的亚马逊开发者账户
- 映射到报告API的安全配置文件（通过开发者控制台 >“我的设置”>“API访问”创建）
- 配置文件的“Web设置”选项卡中显示的客户端ID和客户端密钥
- 您的应用的程序包名称
工作方式
数据从原始订阅事件流入按日和按小时汇总表。
- 按日指标每天提供一个数据点，对应于T-1天。
- 按小时指标每小时提供一个数据点，对应于T-3小时。这对于在促销或价格变更后及早检测趋势非常有用。
使用开发者控制台中的交互式沙盒来探索API。有关详细信息，请参阅API浏览器。
新鲜度
每个指标集都提供了一种标准GET方法来检索最新可用数据的时间戳，即“新鲜度”。由于一个指标集可以支持多个粒度（按天、按小时），因此对于每个支持的粒度，该操作都会返回一个新鲜度值。
| 汇总时段 | 新鲜度SLA | 留存 | 最大查询范围 |
|---|---|---|---|
DAILY（按日） |
T-1天 | 30天 | 每个请求30天 |
HOURLY（按小时） |
T-3小时 | 15天 | 每个请求15天 |
在查询之前务必要检查新鲜度，以了解返回数据的日期范围。
freshnessInfo会为指标集支持的每个汇总时段返回一个条目。仅支持DAILY的指标集只返回单个条目，因此不要假设始终存在两个条目。解读latestDataTimestamp： 该值为一个ISO 8601 UTC时刻，用于标记最新的完全完整的汇总时段。该标签为时段的开始时刻，且整个时段均已完成。对于HOURLY，Thh:00:00Z表示hh:00–hh:59这一小时已完成（例如，2026-07-06T14:00:00Z表示14:00–14:59这一小时已完成）。对于DAILY，YYYY-MM-DDT00:00:00Z表示整个UTC日已完成（例如，2026-07-06T00:00:00Z表示7月6日全天已完成）。
数据查询
要查看指标集中的数据，请使用POST :query方法。每个查询都必须指定粒度和时间范围。除了要查看的指标外，还可以指定维度以对汇总结果进行细分，或是指定筛选条件以在不添加细分的情况下缩小结果范围。
根据您是否在查询中指定了维度，结果会有所不同。
- 查询包含维度： 对于每个时段的每个唯一维度组合，都会生成一行。
- 查询不包含维度： 对于每个时段，只生成一个汇总数字。
对于HOURLY查询，请在ISO 8601时间戳中直接指定小时，例如"2026-08-30T14:00:00Z"。两个边界值均包含在内。要覆盖一整天，请将startTime设置为T00:00:00Z，将endTime设置为T23:00:00Z。比汇总时段更精细的字段将被忽略。在HOURLY查询中，分钟和秒会被舍去，归入所属小时；在DAILY查询中，小时及更精细的字段会被舍去。
可用指标集
下表列出了所有可用的指标集及其说明。
subsActiveMetricSet和subsCancellationSurveyMetricSet仅支持DAILY粒度。对任一指标集执行HOURLY查询都会返回错误。| 指标集 | 描述 | 支持的指标 |
|---|---|---|
subsSignupMetricSet |
订阅注册量和注册收入。 | signups（数字）： 该时段内新开始的订阅数。 signupRevenue（数字）： 这些注册带来的收入。 |
subsRenewalMetricSet |
订阅续订量和续订收入。 | renewals（数字）： 该时段内续订的订阅数。 renewalRevenue（数字）： 这些续订带来的收入。 |
subsCancellationMetricSet |
自愿和非自愿取消，以及退款金额。 | cancellations（数字）： 该时段内取消的订阅数。 cancellationRefunds（数字）： 针对这些取消发放的退款。 |
subsReactivationMetricSet |
之前取消但已重新激活的订阅数。 | reactivations（数字）： 之前已取消但在该时段内重新启动的订阅数。 reactivationRevenue（数字）： 这些重新激活带来的收入。 |
subsActiveMetricSet |
活跃订阅数。仅支持DAILY粒度。 |
activeSubscriptions（数字）： 当天结束时处于活跃状态的订阅数。 |
subsHealthMetricSet |
自动续订和宽限期事件。 | autoRenewalOff（数字）： 已关闭自动续订功能的订阅数。 autoRenewalOn（数字）： 已开启自动续订功能的订阅数。 gracePeriodEntries（数字）： 进入付款宽限期的订阅数。 gracePeriodRecoveries（数字）： 在付款问题/失败修复后从宽限期恢复的订阅数。 |
subsCancellationSurveyMetricSet |
取消调查回复。仅支持DAILY粒度。 |
surveyedCancellations（数字）： 归因于每个调查回复的取消数，按cancellationReason细分。 |
subsFulfillmentMetricSet |
收据送达状况和确认延迟。 | totalReceipts（数字）： 该时段内签发的收据数。 fulfilled（数字）： 您的应用已成功确认的收据数。 unavailable（数字）： 您的应用标记为不可用的收据数。 pending（数字）： 已送达但尚未确认的收据数。 notEligible（数字）： 不符合履行条件的收据数。 existingPurchase（数字）： 客户已拥有的订阅对应的收据数。 notDelivered（数字）： 从未送达应用的收据数。 p50AcknowledgementDelay、p90AcknowledgementDelay、p95AcknowledgementDelay（数字）： 确认延迟（以秒为单位）。 |
使用指标值
解读指标值时需要注意以下几点：
activeSubscriptions是每天活跃订阅的时点计数，而非该时段内的事件总数。跨天求和会对同一订阅者重复计数。- 收入或退款始终与同一指标集中的计数指标配对 -
signups/signupRevenue、renewals/renewalRevenue、cancellations/cancellationRefunds、reactivations/reactivationRevenue。使用计数指标衡量量，使用收入指标衡量货币价值。 - 在
subsFulfillmentMetricSet中，totalReceipts等于fulfilled、unavailable、pending、notEligible、existingPurchase和notDelivered之和。使用此方法可将细分与总数进行核对。 - 当请求时段内没有收据被确认时，
subsFulfillmentMetricSet上的百分位数指标返回null，而非0。null表示没有可用于计算百分位数的数据；0会错误地断言确认是瞬时的。计数和收入指标从不为null。它们分别返回0和0.00。 subsCancellationMetricSet和subsCancellationSurveyMetricSet都会报告取消情况，但回答的问题不同。- 使用
subsCancellationMetricSet可了解有多少订阅被取消，以及取消是主动的还是非主动的。 - 使用
subsCancellationSurveyMetricSet可按客户在取消调查中选择的原因来细分取消情况。调查回复为可选项，因此同一时段的调查总数可能低于取消总数。
- 使用
维度
每个指标集都支持一组通用的维度，用于筛选和细分。每个维度都可在“适用于”列中列出的指标集上使用。
| 维度 | 类型 | 适用于 | 值 | 描述 |
|---|---|---|---|---|
市场 |
字符串 | 所有指标集 | US DE JP GB FR IT ES CA BR MX IN AU |
订阅活动发生的市场。由2个字母组成的ISO 3166-1 alpha-2代码。 |
termSku |
字符串 | 所有指标集 | 自由文本，最多256个字符 | 客户购买的订阅项目的术语SKU。 |
deviceType |
字符串 | 所有指标集 | FIRE_TV FIRE_TABLET OTHER |
设备外形规格。 |
deviceOs |
字符串 | 所有指标集 | FIRE_OS VEGA_OS |
设备操作系统类型。 |
subscriptionType |
字符串 | 除subsRenewalMetricSet和subsFulfillmentMetricSet外的所有指标集 |
REGULAR FREE_TRIAL INTRO |
订阅的定价类型。标准付费订阅、免费试用，或采用试销价。 |
purchaseChannel |
字符串 | 仅subsFulfillmentMetricSet |
QS IAP |
购买来源渠道 |
renewalType |
字符串 | 仅subsRenewalMetricSet |
REGULAR FREE_TRIAL_CONVERSION INTRO_CONVERSION |
续订的性质。常规续订，或从免费试用或试销价转换。 |
cancellationType |
字符串 | 仅subsCancellationMetricSet |
VOLUNTARY INVOLUNTARY |
订阅是通过明确的客户操作取消的 (VOLUNTARY)，还是在没有此类操作的情况下失效的，例如付款失败 (INVOLUNTARY)。 |
cancellationReason |
字符串 | subsCancellationSurveyMetricSet only |
PRICE_RELATED NOT_USING_RELATED CONTENT_RELATED SERVICE_RELATED DISCOUNT_RELATED SPECIFIC_SHOW_RELATED TECHNICAL_ISSUE_RELATED PREFER_NOT_TO_SAY |
客户在取消调查中选择的原因。调查回复变体会归一化为这组固定的原因代码。 |
termSku为自由文本，按提供的内容原样传递，因此拼写错误的筛选值会返回空结果集，而不是报错。所有其他维度都会根据一组固定值进行验证，对于无法识别的值，会以400 VALIDATION_ERROR拒绝。400 VALIDATION_ERROR。例如，purchaseChannel仅在subsFulfillmentMetricSet上可用。维度值
某些维度使用编码值。本节说明每个值代表什么。
subscriptionType — 订阅的定价类型。标准付费订阅、免费试用，或采用试销价。
REGULAR： 按标准价格收费的订阅。FREE_TRIAL：处于免费试用期的订阅；尚未向客户收费。INTRO： 处于试销价期的订阅，在切换到标准价格之前按折扣价收费。
renewalType — 续订的性质。常规续订，或从免费试用或试销价转换。
REGULAR： 按现有价格对付费订阅进行的常规续订。FREE_TRIAL_CONVERSION： 将免费试用转换为付费订阅的续订。客户的首次收费。INTRO_CONVERSION： 将订阅从促销价转为标准价格的续订。
purchaseChannel — 订阅购买发生的位置。
QS（快速订阅）： 客户在应用外部订阅，例如在Fire设备上通过应用详情页面一键订阅，或从应用的亚马逊零售网页订阅。IAP（应用内购买）： 客户登录应用后，使用标准应用内购买流程从应用内完成购买。
cancellationType — 取消是如何发生的。
VOLUNTARY： 订阅是通过明确的客户操作取消的，例如关闭自动续订或联系客户支持进行取消。INVOLUNTARY： 订阅在没有明确客户操作的情况下被取消，例如付款失败或不完整付款，包括付款宽限期到期。
cancellationReason — 客户在可选的取消调查中选择的原因。由于调查在不同界面和不同时间呈现的措辞有所不同，因此多个调查回复会映射到同一个原因代码。以下每个代码都列出了其包含的调查回复。
PRICE_RELATED： 与价格相关的不满。“订阅太贵/价格上涨”、“订阅价格上涨”、“相比其他服务太贵”或“价格太高”。NOT_USING_RELATED： “未充分使用该流媒体服务”。SPECIFIC_SHOW_RELATED： “我注册是为了观看某个特定的节目/电影/体育赛事”。CONTENT_RELATED： 内容不满。“可供观看的电视节目、体育赛事和电影不够多”或“对内容/服务不满意”。TECHNICAL_ISSUE_RELATED： 技术或设备问题。“崩溃/卡死/登录问题太多”、“登录流媒体服务时出现问题”、“崩溃或卡死太多”或“对我的设备不满意”。DISCOUNT_RELATED： 促销价格结束。“免费试用/折扣订阅价格结束”或“折扣订阅价格结束”。SERVICE_RELATED： “改用其他服务”。PREFER_NOT_TO_SAY： 拒绝提供具体原因。“不愿透露”、“以上都不是”或“其他原因”。
surveyedCancellations总数低于cancellations总数，且不应期望两者能够核对一致。相关主题
- Monetization Metrics API参考： 先决条件、身份验证、API终结点、代码示例、错误处理和最佳实践
- 报告API： 销售、收益和订阅报表下载
- 探索API： 链接到开发者控制台中的API浏览器
Last updated: 2026年10月13日
