---
title: "订阅生命周期与计费"
description: "本页说明订阅在其生命周期中如何流转、计费周期和续订如何计算，以及失败的付款如何处理。"
source: "https://docs.tokenz.one/zh-CN/v2/subscriptions/lifecycle"
api_version: "v2"
locale: "zh-CN"
version_status: "current"
docs_stage: "prod"
---

# 订阅生命周期与计费

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

## 状态

| 状态 | 含义 |
| --- | --- |
| `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 在当前计费周期结束时自动管理。

```mermaid
sequenceDiagram;
autonumber;
participant T as Tokenz;
participant PSP as 卡组织 / PSP;
participant W as 商户 webhook 处理程序;
T->>T: 为该计费周期创建续订订单;
T->>PSP: 向已保存的卡扣款;
alt 支付成功
PSP-->>T: 已授权;
T->>T: 推进计费周期，订阅保持 active;
T->>W: webhook: subscription.renewed;
else 支付失败
PSP-->>T: 已拒绝;
T->>T: 将订阅标记为 unpaid，开始催收;
T->>W: webhook: subscription.unpaid;
end
```

## 试用期

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

1. 消费者通过提供卡片信息开始试用。Tokenz 会在支付网络中登记支付授权——参见[支付方式与授权](https://docs.tokenz.one/zh-CN/v2/subscriptions/payment-methods)。
2. 订阅进入 `trialing` 状态，并发送 `subscription.trial_started` webhook。
3. 当试用达到 `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` 状态，商户即可代表消费者取消订阅。取消操作会：

- 设置 `canceledAt` 并停止生成后续的续订订单
- 取消该订阅任何处理中的订单（例如仍在等待付款的订单）
- 发送 `subscription.canceled` webhook

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

## 续订提醒

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