事件列表

事件名称	事件类型	触发时机	通知数据结构
试用期即将到期通知	subscription.trial_period_expiring	试用期剩余时间小于 3 天时	Subscription
首次订阅通知	subscription.first	订阅首次生效时	Subscription
终止订阅通知	subscription.canceled	主动终止订阅时	Subscription
订阅价格变更	subscription.price_changed	订阅价格变更时	Subscription

事件对象

属性	类型	描述	示例
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 生命周期

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 事件

示例数据

{
  "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"
  }
}

{
  "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"
  }
}

{
    "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"
    }
}

{
  "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"
  }
}