> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 订阅
## 事件列表
| **事件名称** | **事件类型** | **触发时机** | **通知数据结构** |
| --------- | ------------------------------------ | -------------- | ------------------------------------------ |
| 试用期即将到期通知 | subscription.trial\_period\_expiring | 试用期剩余时间小于 3 天时 | [Subscription](/zh/webhook/subscription-1) |
| 首次订阅通知 | subscription.first | 订阅首次生效时 | [Subscription](/zh/webhook/subscription-1) |
| 终止订阅通知 | subscription.canceled | 主动终止订阅时 | [Subscription](/zh/webhook/subscription-1) |
| 订阅价格变更 | subscription.price\_changed | 订阅价格变更时 | [Subscription](/zh/webhook/subscription-1) |
## 事件对象
| **属性** | **类型** | **描述** | **示例** |
| ---------------------- | ------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| id | uint64 | 订阅计划唯一标识 | 516816656060660549 |
| customer\_id | string | Subotiz 平台顾客唯一标识 | 516816656060660549 |
| sub\_merchant\_id | string | 商户唯一标识 | 123061 |
| status | string | 订阅业务状态：init - 待生效trial - 试用期active - 生效中canceled - 已终止incomplete - 未完成 | init |
| price\_id | uint64 | 商品定价的唯一标识 | 516816656060660549 |
| total\_cycles | int | 总周期数，0表示无限期 | 0 |
| current\_period\_start | string | 当前计费周期开始时间 | 2025-07-01T13:40:25Z |
| current\_period\_end | string | 当前计费周期结束时间 | 2025-07-01T13:40:25Z |
| next\_invoice\_date | string | 下一次收费日期 | 2025-07-01T13:40:25Z |
| created\_at | string | 创建时间 | 2025-07-01T13:40:25Z |
| updated\_at | string | 更新时间 | 2025-07-01T13:40:25Z |
| order\_id | string | 接入方订单 ID | order\_123456 |
| cycle\_index | int | 当前周期数 | 1 |
| next\_price\_info | NextPriceInfo | 价格变更信息 | `{
"price_id": "516816656060660549",
"expected_effective_date": "2025-09-30T15:33:00Z",
"proration":"none"
}` |
| cancel\_at | string | 订阅实际取消时间 | 2025-07-01T13:40:25Z |
| cancel\_reason | string | 订阅取消原因 | Customer cancellation |
| source\_trade\_id | string | 订阅的来源交易单 | 516816656060660549 |
| metadata | map\[string]string | 订阅上附带的元数据 | `{
"key": "value"
}` |
### NextPriceInfo
| **属性** | **类型** | **描述** | **示例** |
| ------------------------- | ------ | ---------------------------------------------- | --------------------------------------------------------------------------- |
| price\_id | string | 价格变更之后的定价 ID | 516816656060660549 |
| expected\_effective\_date | string | 预计生效时间 | 2025-09-30T15:33:00Z |
| proration | string | 结算类型
none: 无需结算分摊额
immediate:立即结算分摊额 | immediate |
| change\_invoice\_id | string | 由订阅变更产生的 invoice 的 id | 516816656060660541 |
| change\_refund\_ids | string | 由订阅变更产生的退款单id，可关联 invoice.refund\_id 字段 | `[
"20250807542984743692553411"
"20250807542984743692553415"
]` |
## Subscription 生命周期
```mermaid theme={null}
stateDiagram-v2
[*] --> Trial : 下单成功享受试用期
[*] --> Active : 下单不可享受试用期/无试用期
Trial --> Active : 先付费：试用期结束后扣款成功
Trial --> Active : 后付费：试用期结束后直接激活首期
Trial --> PastDue : 试用期结束首次扣款失败
Trial --> Canceled : 取消订阅
Active --> Paused : 暂停订阅
Active --> PastDue : 续订失败仍在重试
Active --> Canceled : 取消订阅
Paused --> Active : 重启订阅
Paused --> Canceled : 取消订阅
PastDue --> Active : 重试收款成功
PastDue --> Unpaid : 重试收款达到最大次数/宽限期到期
PastDue --> Canceled : 取消订阅/宽限期到期
Unpaid --> Canceled : 取消订阅
Unpaid --> Canceled : 到了宽限期/取消订阅
Unpaid --> Unpaid : 到了宽限期/标记为未支付
Unpaid --> Active : 宽限期内修改支付方式支付成功
Canceled --> [*]
```
### 动作对应的事件
* **有试用期 & 首次订阅：** `subscription.first` 事件，且事件对象中的 `subscription.status = trial`
* **首次订阅**: `subscription.first `事件，且事件对象中的 `subscription.status = active`
* **终止订阅**：`subscription.canceled` 事件
* **试用期结束 & 支付成功：** `invoice.paid` 事件，且事件对象中的 `invoice.invoice_type = initial`
* **续订支付成功**：`invoice.paid` 事件，且事件对象中的 `invoice.invoice_type = renewal`
* **支付失败**：`invoice.payment_failed` 事件
## 示例数据
```json subscription.first theme={null}
{
"id": 583564652533787306,
"type": "subscription.first",
"created": "2025-11-27T07:57:35Z",
"data": {
"sub_merchant_id": "100010",
"customer_id": "537465921338359803",
"total_cycles": 0,
"current_period_start": "2025-11-27T07:57:00Z",
"next_invoice_date": "2025-11-27T13:08:00Z",
"cancel_at": null,
"created_at": "2025-11-27T07:57:35Z",
"id": 583564651824940742,
"next_price_info": null,
"cancel_reason": "",
"order_id": "order_1764230244388418776",
"cycle_index": 1,
"current_period_end": "2025-11-27T13:07:00Z",
"price_id": 582401938335740273,
"updated_at": "2025-11-27T07:57:35Z",
"source_trade_id": "583564647529987790",
"status": "active"
}
}
```
```json subscription.canceled theme={null}
{
"id": 572682701203579940,
"type": "subscription.canceled",
"created": "2025-10-28T07:16:35Z",
"data": {
"price_id": 572349625697058751,
"created_at": "2025-10-28T06:54:56Z",
"updated_at": "2025-10-28T07:16:35Z",
"next_price_info": null,
"current_period_start": "2025-10-28T06:54:00Z",
"current_period_end": "2025-10-28T07:25:00Z",
"next_invoice_date": "2025-10-28T07:26:00Z",
"cancel_at": "2025-10-28T07:16:00Z",
"id": 572677251968024511,
"total_cycles": 0,
"cycle_index": 1,
"cancel_reason": "cancel",
"order_id": "order_1761634475936438746",
"sub_merchant_id": "2816433",
"status": "canceled",
"customer_id": "547766341013094363",
"source_trade_id": "572677233903157186"
}
}
```
```json subscription.trial_period_expiring theme={null}
{
"id": 572670992330012613,
"type": "subscription.trial_period_expiring",
"created": "2025-10-28T06:30:01Z",
"data": {
"id": 572664015193371988,
"customer_id": "567609424412263252",
"price_id": 563378244649234223,
"current_period_start": "2025-10-28T06:02:00Z",
"updated_at": "2025-10-28T06:02:20Z",
"total_cycles": 0,
"current_period_end": "2025-10-31T06:02:00Z",
"cancel_at": null,
"created_at": "2025-10-28T06:02:20Z",
"source_trade_id": "572663537512178624",
"sub_merchant_id": "1216433",
"status": "trial",
"next_invoice_date": "2025-10-31T06:03:00Z",
"cancel_reason": "",
"cycle_index": 0,
"order_id": "order_1761631220208894185"
}
}
```
```json subscription.price_changed theme={null}
{
"id": 583570323576728234,
"type": "subscription.price_changed",
"created": "2025-11-27T08:20:07Z",
"data": {
"id": 583564651824940742,
"price_id": 582401938335740273,
"cycle_index": 1,
"current_period_end": "2025-11-27T13:07:00Z",
"next_invoice_date": "2025-11-27T13:08:00Z",
"cancel_at": null,
"total_cycles": 0,
"cancel_reason": "",
"created_at": "2025-11-27T07:57:35Z",
"source_trade_id": "583564647529987790",
"sub_merchant_id": "100010",
"status": "active",
"customer_id": "537465921338359803",
"current_period_start": "2025-11-27T07:57:00Z",
"next_price_info": {
"price_id": 582402035266105713,
"expected_effective_date": "2025-11-27T08:20:00Z",
"proration": "immediate",
"change_invoice_id": "583570320951084742",
"change_refund_ids": null
},
"updated_at": "2025-11-27T07:57:35Z",
"order_id": "order_1764230244388418776"
}
}
```