事件列表
| 事件名称 | 事件类型 | 触发时机 | 通知数据结构 |
|---|---|---|---|
| 试用期即将到期 | v2.subscription.trial_period_expiring | 试用期剩余时间小于 3 天时 | Subscription |
| 首次订阅 | v2.subscription.first | 订阅首次生效时 | Subscription |
| 终止订阅 | v2.subscription.canceled | 主动终止订阅时 | Subscription |
| 订阅价格变更 | v2.subscription.price_changed | 订阅价格变更时 | Subscription |
| 订阅暂停 | v2.subscription.paused | 订阅暂停时通知 | Subscription |
| 订阅重启 | v2.subscription.resumed | 订阅重启时通知 | Subscription |
| 订阅逾期 | v2.subscription.past_due | 订阅逾期时通知 | Subscription |
| 订阅未支付 | v2.subscription.unpaid | 订阅未支付时通知 | Subscription |
| 撤回取消订阅 | v2.subscription.cancellation_revoked | 撤回取消订阅时通知 | Subscription |
| 请求取消订阅 | v2.subscription.cancellation_requested | 请求取消订阅时通知 | Subscription |
| 固定期限变更 | v2.subscription.fixed_term_updated | 订阅固定期限变更时通知 | Subscription |
| 撤回价格变更 | v2.subscription.price_change_revoked | 撤回订阅价格变更时通知 | Subscription |
事件对象
| 属性 | 类型 | 描述 | 示例 |
|---|---|---|---|
| id | string | 订阅计划唯一标识 | 516816656060660549 |
| customer_id | string | Subotiz 平台顾客唯一标识 | 516816656060660549 |
| sub_merchant_id | string | 商户唯一标识 | 123061 |
| status | string | 订阅业务状态：init - 待生效trial - 试用期active - 生效中canceled - 已终止incomplete - 未完成 | init |
| price_id | string | 商品定价的唯一标识 | 516816656060660549 |
| total_cycles | string | 总周期数，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 | string | 当前周期数 | 1 |
| next_price_info | NextPriceInfo | 价格变更信息 | {<br/>"price_id": "516816656060660549",<br/>"expected_effective_date": "2025-09-30T15:33:00Z",<br/>"proration":"none"<br/>} |
| cancel_at | string | 订阅实际取消时间 | 2025-07-01T13:40:25Z |
| cancel_reason | string | 订阅取消原因 | Customer cancellation |
| source_trade_id | string | 订阅的来源交易单 | 516816656060660549 |
| metadata | map[string]string | 订阅上附带的元数据 | {<br/>"key": "value"<br/>} |
| paused_at | string | 订阅暂停的时间 | 2025-07-01T13:40:25Z |
| initiate_cancel_at | string | 发起取消订阅的时间 | 2025-07-01T13:40:25Z |
| expected_cancel_at | string | 预期取消订阅的时间 | 2025-07-01T13:40:25Z |
| price_version_id | string | 商品定价版本唯一标识 | 585661231470226668 |
| first_source_channel | string | 首次创建结账会话的来源渠道 | |
| last_source_channel | string | 最近一次访问结账会话的来源渠道 | |
| is_renewable | bool | 固定期限到期后是否自动转为长期订阅 | false |
| end_at | string | 订阅结束时间。空字符串表示长期订阅（无结束时间） | |
| current_period_num | string | 当前期数 | 1 |
| previous_fixed_term_info | object | 变更前的固定期限信息。仅在 v2.subscription.fixed_term_updated 事件中存在。包含子字段：previous_fixed_term (string)、previous_is_renewable (bool)、previous_end_at (string) | null |
NextPriceInfo
| 属性 | 类型 | 描述 | 示例 |
|---|---|---|---|
| price_id | string | 价格变更之后的定价 ID | 516816656060660549 |
| effective_type | string | 价格变更的生效时机 immediate:立即生效 end_of_period:当前计费周期结束时生效 | immediate |
| 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 字段 | [<br/>"20250807542984743692553411"<br/>"20250807542984743692553415"<br/>] |
Subscription 生命周期
动作对应的事件
- 有试用期 & 首次订阅：
v2.subscription.first事件，且事件对象中的subscription.status = trial - 首次订阅:
v2.subscription.first事件，且事件对象中的subscription.status = active - 终止订阅：
v2.subscription.canceled事件 - 试用期结束 & 支付成功：
v2.invoice.paid事件，且事件对象中的invoice.invoice_type = initial - 续订支付成功：
v2.invoice.paid事件，且事件对象中的invoice.invoice_type = renewal - 支付失败：
v2.invoice.payment_failed事件
示例数据
{
"id": "583564652533787306",
"type": "v2.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"
}
}
{
"id": "572682701203579940",
"type": "v2.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"
}
}
{
"id": "572670992330012613",
"type": "v2.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"
}
}
{
"id": "654282672553592775",
"type": "v2.subscription.price_changed",
"created": "2026-07-10T11:23:00Z",
"data": {
"status": "active",
"end_at": "",
"previous_fixed_term_info": null,
"current_period_start": "2026-06-10T11:23:00Z",
"order_id": "test_order_00111",
"next_price_info": {
"proration": "none",
"change_invoice_id": "",
"change_refund_ids": null,
"usage_invoice_id": "",
"price_id": "608934085099784585",
"price_version_id": "608934085099784585",
"effective_type": "end_of_period",
"expected_effective_date": "Charged when usage-based fees reach $20.00"
},
"initiate_cancel_at": "",
"customer_id": "539729972764360694",
"price_version_id": "629136800761259429",
"cancel_reason": "",
"is_renewable": true,
"created_at": "2026-06-10T11:23:32Z",
"source_trade_id": "654281916278652917",
"first_source_channel": "",
"cycle_index": "0",
"next_invoice_date": "Charged when usage-based fees reach $20.00",
"updated_at": "2026-06-10T11:23:32Z",
"expected_cancel_at": "",
"price_id": "608933940362740418",
"current_period_end": "2026-06-10T11:23:00Z",
"last_source_channel": "",
"id": "654282114438533136",
"total_cycles": "2",
"sub_merchant_id": "364861",
"cancel_at": null,
"paused_at": "",
"current_period_num": "1"
}
}
{
"id": "603927306368453965",
"type": "v2.subscription.paused",
"created": "2026-01-22T12:31:30Z",
"data": {
"price_version_id": "585661231470226668",
"cycle_index": "1",
"next_price_info": null,
"first_source_channel": "",
"paused_at": "2026-01-22T12:31:00Z",
"total_cycles": "0",
"updated_at": "2026-01-22T12:31:30Z",
"source_trade_id": "603889788398876633",
"initiate_cancel_at": "",
"expected_cancel_at": "",
"id": "603889808367951518",
"price_id": "585661231470226668",
"current_period_start": "2026-01-22T10:02:00Z",
"current_period_end": "-",
"cancel_reason": "",
"last_source_channel": "",
"metadata": null,
"sub_merchant_id": "2816433",
"status": "paused",
"customer_id": "541822454956310498",
"next_invoice_date": "-",
"cancel_at": null,
"created_at": "2026-01-22T10:02:30Z",
"order_id": "order_1769076135405830680"
}
}
{
"id": "603928258563542349",
"type": "v2.subscription.resumed",
"created": "2026-01-22T12:35:17Z",
"data": {
"cancel_at": null,
"price_id": "585661231470226668",
"price_version_id": "585661231470226668",
"total_cycles": "0",
"next_invoice_date": "Charged when usage-based fees reach $20.00",
"created_at": "2026-01-22T10:02:30Z",
"source_trade_id": "603889788398876633",
"next_price_info": null,
"last_source_channel": "",
"id": "603889808367951518",
"cycle_index": "1",
"current_period_start": "2026-01-22T10:02:00Z",
"paused_at": "",
"initiate_cancel_at": "",
"customer_id": "541822454956310498",
"current_period_end": "2026-01-22T10:10:02Z",
"metadata": null,
"updated_at": "2026-01-22T12:35:17Z",
"order_id": "order_1769076135405830680",
"first_source_channel": "",
"expected_cancel_at": "",
"sub_merchant_id": "2816433",
"status": "active",
"cancel_reason": ""
}
}
{
"id": "604229309149746453",
"type": "v2.subscription.past_due",
"created": "2026-01-23T07:50:55Z",
"data": {
"customer_id": "541822454956310498",
"total_cycles": "0",
"created_at": "2026-01-23T07:44:32Z",
"initiate_cancel_at": "",
"first_source_channel": "",
"last_source_channel": "",
"current_period_start": "2026-01-23T07:44:00Z",
"next_invoice_date": "Charged when usage-based fees reach $20.00",
"cancel_at": null,
"cancel_reason": "",
"source_trade_id": "604217431497390041",
"metadata": null,
"expected_cancel_at": "",
"price_id": "585661231470226668",
"order_id": "order_1769154252871463378",
"paused_at": "",
"updated_at": "2026-01-23T07:50:55Z",
"next_price_info": null,
"id": "604217479710908319",
"sub_merchant_id": "2816433",
"status": "past_due",
"price_version_id": "585661231470226668",
"cycle_index": "1",
"current_period_end": "2026-01-23T07:50:01Z"
}
}
{
"id": "604230206634333461",
"type": "v2.subscription.unpaid",
"created": "2026-01-23T08:30:08Z",
"data": {
"expected_cancel_at": "",
"sub_merchant_id": "2816433",
"price_id": "600585046541216169",
"cycle_index": "1",
"cancel_reason": "",
"first_source_channel": "",
"source_trade_id": "603856934524690415",
"customer_id": "541822454956310498",
"total_cycles": "0",
"cancel_at": null,
"created_at": "2026-01-22T07:52:13Z",
"order_id": "order_1769068305139700301",
"price_version_id": "600585046541216169",
"next_invoice_date": "2026-01-22T08:16:00Z",
"next_price_info": null,
"metadata": null,
"paused_at": "",
"last_source_channel": "",
"initiate_cancel_at": "",
"id": "603857024144389364",
"status": "unpaid",
"current_period_start": "2026-01-22T07:52:00Z",
"current_period_end": "2026-01-22T09:02:00Z",
"updated_at": "2026-01-23T08:30:08Z"
}
}
{
"id": "603909739125935437",
"type": "v2.subscription.cancellation_revoked",
"created": "2026-01-22T11:21:41Z",
"data": {
"current_period_end": "2026-01-22T12:30:00Z",
"next_invoice_date": "2026-01-22T12:31:00Z",
"cancel_reason": "",
"updated_at": "2026-01-22T11:21:41Z",
"order_id": "order_1769080829192130135",
"paused_at": "",
"total_cycles": "0",
"current_period_start": "2026-01-22T11:20:00Z",
"sub_merchant_id": "2816433",
"expected_cancel_at": "",
"customer_id": "541822454956310498",
"price_id": "594101578214976042",
"cycle_index": "1",
"cancel_at": null,
"source_trade_id": "603909473999796185",
"next_price_info": null,
"id": "603909515594702494",
"status": "active",
"metadata": null,
"first_source_channel": "",
"last_source_channel": "",
"initiate_cancel_at": "",
"price_version_id": "599077413057465741",
"created_at": "2026-01-22T11:20:48Z"
}
}
{
"id": "605206977064209227",
"type": "v2.subscription.cancellation_requested",
"created": "2026-01-26T01:16:27Z",
"data": {
"paused_at": "",
"expected_cancel_at": "2026-01-26T01:16:00Z",
"sub_merchant_id": "2816433",
"total_cycles": "0",
"current_period_start": "2026-01-22T13:05:00Z",
"source_trade_id": "603889788398876633",
"first_source_channel": "",
"last_source_channel": "",
"price_id": "597247070985830078",
"current_period_end": "2026-01-26T01:16:27Z",
"cancel_at": "2026-01-26T01:16:00Z",
"updated_at": "2026-01-26T01:16:27Z",
"order_id": "order_1769076135405830680",
"id": "603889808367951518",
"next_invoice_date": "Charged when usage-based fees reach $30.00",
"created_at": "2026-01-22T10:02:30Z",
"initiate_cancel_at": "2026-01-26T01:16:00Z",
"next_price_info": null,
"metadata": null,
"status": "canceled",
"customer_id": "541822454956310498",
"price_version_id": "597247070985830078",
"cycle_index": "1",
"cancel_reason": ""
}
}