订阅生命周期

本页说明公开订阅对象、状态值以及对应的商户动作。

使用 Subscription 状态控制用户权益，使用 Invoice 状态判断账单事实，使用 Payment Order 状态判断扣款结果。浏览器回跳和 Operation 成功都不能替代这些业务对象状态。

对象关系

Merchant Customer 1 ── N Subscription
Plan              1 ── N Subscription
Checkout Session  1 ── 1 Subscription
Subscription      1 ── N Invoice
Invoice           1 ── N Payment Attempt
Invoice           1 ── 0..1 Payment Order

对象	商户含义
Merchant Customer	使用稳定 merchantCustomerNo 标识的商户客户；当前没有独立 Customer API。
Plan	新建订阅使用的价格、币种和计费周期模板。
Checkout Session	一次托管 Checkout；创建时会同时创建真实 Subscription，初始状态为 PENDING_CHECKOUT。
Subscription	用于判断用户权益是否有效的持续订阅合同。
Invoice	一个订阅周期的账单事实。
Payment Attempt	对一个 Invoice 的一次扣款尝试。
Payment Order	已支付 Invoice 对应的扣款结果对象。

商户必须保存创建响应和事件中的平台编号。当前列表接口不能通过所有商户侧编号反查对象。

Plan 状态

数值	状态	含义
0	UNKNOWN	不用于创建新订阅。
1	CREATING	正在创建。
2	ACTIVE	可创建 Checkout Session。
3	ARCHIVED	不再用于新会话；不会取消已有 Subscription。
4	CREATE_FAILED	创建失败。
5	CHANNEL_UNKNOWN	渠道结果未收敛，查询或联系技术支持。

归档 Plan 还会触发关闭该 Plan 尚未完成的 Checkout Link。归档后不要继续向用户展示此前签发的 checkoutUrl；该操作不会取消已经建立的 Subscription。

更新 Plan 只修改 name、description 和 metadataJson，其中 name 必填。description 省略或传空字符串会保留旧值；metadataJson 省略或传空字符串也保留旧值，传字符串 "{}" 才替换为空对象。

Checkout Session 状态

数值	状态	含义
0	UNKNOWN	会话状态未知。
1	CREATED	托管链接已创建。
2	REDIRECTED	保留枚举，当前不是稳定可观察状态。
3	VERIFYING	已收到完成线索，正在回查确认。
4	COMPLETED	Checkout 已确认；仍需确认 Subscription 状态。
5	FAILED	Checkout 失败。
6	EXPIRED	保留枚举，当前流程不保证主动写入。

使用响应中的 expiresAt 作为 DEEPayment Session 的有效截止时间，超过该时间后不要再跳转。商户请求不能自定义该值。

linkStatus 包含 UNKNOWN(0)、ENABLED(1)、DISABLING(2)、DISABLED(3)、DISABLE_FAILED(4)。不能继续跳转已禁用链接。

Subscription 状态

数值	状态	商户动作
0	UNKNOWN	不开通，继续查询。
1	PENDING_CHECKOUT	等待用户完成 Checkout。
2	ACTIVATING	正在确认，不提前开通。
3	ACTIVE	开通正式订阅权益。
4	PAST_DUE	按宽限策略处理并检查账单。
5	UNPAID	停止或限制正式权益。
6	CANCELED	停止订阅权益。
7	FAILED	订阅创建失败。
8	TRIALING	保留状态。商户当前不能主动创建，也不能据此开通权益。

当前只有 ACTIVE 是正向开通状态。浏览器返回、Checkout Session 完成或 operation=SUCCEEDED 都不能单独作为开通依据。

Subscription 查询和列表返回 statusVersion，状态和版本来自同一次查询快照。版本只能在同一个 subscriptionNo 内比较。

Invoice 状态

数值	状态	含义
0	UNKNOWN	账单状态未知。
1	DRAFT	草稿账单。
2	OPEN	已出账、待支付。
3	PAID	Invoice 已支付。
4	VOID	Invoice 已作废。
5	UNCOLLECTIBLE	Invoice 不可收取。
6	PAYMENT_FAILED	当前账单支付失败。

Payment Attempt 状态

数值	状态	含义
0	UNKNOWN	尝试状态未知。
1	PENDING	等待处理。
2	PROCESSING	正在扣款。
3	SUCCEEDED	本次尝试成功。
4	FAILED	本次尝试失败，结合当前 Invoice 和 Subscription 处理。
5	ACTION_REQUIRED	需要额外用户动作。
6	CANCELED	本次尝试已取消。

Payment Order

订单数值	状态	含义
0	UNKNOWN	未知。
1	CREATED	订单已创建。
2	PAYING	支付处理中。
3	SUCCESS	支付成功。
11	FAILED	支付失败。
12	EXPIRED	保留值，当前渠道结果可能归并为失败。
13	CANCELED	保留值，当前渠道结果可能归并为失败。
14	EXCEPTION	异常终态，需要平台处理。

invoice.paid 表示 Invoice 已支付并关联成功 Payment Order。当前 Subscription API 不公开结算状态，不能使用这些支付状态确认结算完成。

Operation 状态

创建和变更接口可能在 HTTP 200 中返回 Operation。

数值	状态	含义
0	UNKNOWN	Operation 状态未知。
1	PENDING	等待执行。
2	RUNNING	正在执行。
3	SUCCEEDED	已确认成功。
4	FAILED	已确认失败。
5	CHANNEL_UNKNOWN	渠道结果未知，不能换新业务号重建。

HTTP status 表达 API 响应层，Operation status 表达已经落库的副作用操作层。HTTP 200 不会把 FAILED 或 CHANNEL_UNKNOWN 变成成功。

取消订阅

商户动作统一称为“取消订阅”。请求只包含可选的 reason，不支持周期结束后取消。

提交取消请求后，先保持当前权益决策；只有响应、已验签事件或查询确认 Subscription 为 CANCELED，才立即停止权益，不继续保留到 currentPeriodEnd。取消不会退款或撤销历史账单对象。

列表查询规则

所有列表默认 page=1、pageSize=20，单页最大 100；所有时间使用 Unix 毫秒。

列表	支持的业务筛选条件
Plan	status
Subscription	merchantCustomerNo、planNo、merchantPlanNo、status
Invoice	subscriptionNo、merchantSubscriptionNo、status
Payment Order	merchantCustomerNo、subscriptionNo、merchantSubscriptionNo

Subscription 和 Payment Order 列表未提供 owner 条件时，必须同时传 startTime、endTime，查询跨度不超过 90 天。

Payment Order 当前按候选 Invoice 分页，可能出现返回数量少于 pageSize，甚至当前页为空但 paging.total > 0。应按 paging.page、paging.totalPages 继续翻页，不能用 orders.length 提前结束。