订阅生命周期与计费

本页说明订阅在其生命周期中如何流转、计费周期和续订如何计算，以及失败的付款如何处理。

状态

可按需左右滚动

状态	含义
`created`	订阅已创建，但消费者尚未完成授权。
`trialing`	消费者正处于试用期。尚未发生任何扣款。
`active`	订阅正常计费。每个计费周期结束时会自动创建新订单并扣款。
`unpaid`	当前计费周期的订单未能支付成功。订阅正处于催收状态，之后将恢复为 `active` 或终止为 `expired`。
`canceled`	由商户代表消费者取消。终止状态——不会再产生扣款。
`expired`	因始终无法收款（初始扣款失败，或催收已耗尽）而非自愿终止。终止状态——不会再产生扣款。

canceled 和 expired 都是终止状态，但含义不同：canceled 是商户代表消费者主动取消，而 expired 反映的是付款失败。在您自己的流失分析中应区分这两者。

每个处于活跃状态的订阅都有一个 currentBillingPeriodEnd 时间戳，处于试用状态的订阅还会有一个 trialEnd 时间戳。

间隔（Interval）：一个包含 unit（WEEK、MONTH 或 YEAR）和 count（两次续订之间的单位数）的对象。按月和按年的周期会顺延至与订阅的计费锚点（首次成功扣款）相同的日期；若锚点当天在目标月份中不存在（例如锚点为 31 号，而目标月较短），则顺延至该月最后一天（30 号或 28/29 号）。
续订（Renewal）：由 Tokenz 在当前计费周期结束时自动管理。

流程图

如果在创建订阅时设置了 trialPeriodDays（1–365），结账时不会创建初始订单。而是按以下流程进行：

消费者通过提供卡片信息开始试用。Tokenz 会在支付网络中登记支付授权——参见支付方式与授权。
订阅进入 trialing 状态，并发送 subscription.trial_started webhook。
当试用达到 trialEnd 时，系统会创建订单并使用已保存的卡进行扣款。成功后，订阅变为 active，并发送 subscription.activated webhook。

如果未配置试用期，初始订单会在结账时创建并扣款，授权成功后订阅立即变为 active。

每个订阅在创建时都会配置一个催收策略，用于控制计划扣款失败时的处理方式：

RETRY（默认）：未支付的订单会在其到期窗口（dunningExpireAfterHours，默认 24 小时）耗尽之前，最多重试 dunningMaxAttempts 次（默认 3 次），并按一定间隔分散进行。消费者还会收到一封包含恢复结账链接的邮件，以便在需要时更新卡片。如果某次重试成功，订阅会恢复为 active。如果所有重试均失败且订单过期，订阅将变为 expired。
CANCEL_IMMEDIATELY：首次扣款失败会立即使订阅过期——没有重试窗口。

可按需左右滚动

字段	说明
`dunningMode`	`RETRY` 或 `CANCEL_IMMEDIATELY`。默认值为 `RETRY`。
`dunningMaxAttempts`	当 `dunningMode` 为 `RETRY` 时的最大重试次数。1–10，默认 3。
`dunningExpireAfterHours`	当 `dunningMode` 为 `RETRY` 时，未支付订单过期前的小时数。1–168，默认 24。

注意： 从 unpaid 恢复到 active 不会移动原有的计费周期——下一次续订仍按原始锚点日期排期，而不是按恢复日期排期。

只要订阅处于 trialing、active 或 unpaid 状态，商户即可代表消费者取消订阅。取消操作会：

取消是最终操作——目前没有办法恢复已取消的订阅。消费者需要重新开始一个新的订阅。

在部分地区，法规要求在特定扣款前发出通知（例如试用转正式扣款之前，或年度续订之前）；在有此要求时，Tokenz 会自动发送这些通知。