API Reference
API Reference

订阅

事件列表

事件名称事件类型触发时机通知数据结构
试用期即将到期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

事件对象

属性类型描述示例
idstring订阅计划唯一标识516816656060660549
customer_idstringSubotiz 平台顾客唯一标识516816656060660549
sub_merchant_idstring商户唯一标识123061
statusstring订阅业务状态：init - 待生效trial - 试用期active - 生效中canceled - 已终止incomplete - 未完成init
price_idstring商品定价的唯一标识516816656060660549
total_cyclesstring总周期数，0表示无限期0
current_period_startstring当前计费周期开始时间2025-07-01T13:40:25Z
current_period_endstring当前计费周期结束时间2025-07-01T13:40:25Z
next_invoice_datestring下一次收费日期。非固定周期扣费(如按用量阈值扣费)时,返回的是描述性文字而非时间戳。2025-07-01T13:40:25Z
created_atstring创建时间2025-07-01T13:40:25Z
updated_atstring更新时间2025-07-01T13:40:25Z
order_idstring接入方订单 IDorder_123456
cycle_indexstring当前周期数1
next_price_infoNextPriceInfo价格变更信息{ "price_id": "516816656060660549", "expected_effective_date": "2025-09-30T15:33:00Z", "proration":"none" }
cancel_atstring订阅实际取消时间2025-07-01T13:40:25Z
cancel_reasonstring订阅取消原因Customer cancellation
source_trade_idstring订阅的来源交易单516816656060660549
metadatamap[string]string订阅上附带的元数据{ "key": "value" }
paused_atstring订阅暂停的时间2025-07-01T13:40:25Z
initiate_cancel_atstring发起取消订阅的时间2025-07-01T13:40:25Z
expected_cancel_atstring预期取消订阅的时间2025-07-01T13:40:25Z
price_version_idstring商品定价版本唯一标识585661231470226668
first_source_channelstring首次创建结账会话的来源渠道
last_source_channelstring最近一次访问结账会话的来源渠道
is_renewablebool固定期限到期后是否自动转为长期订阅false
end_atstring订阅结束时间。空字符串表示长期订阅（无结束时间）
current_period_numstring当前期数1
previous_fixed_term_infoobject变更前的固定期限信息。仅在 v2.subscription.fixed_term_updated 事件中存在。包含子字段：previous_fixed_term (string)、previous_is_renewable (bool)、previous_end_at (string)null

NextPriceInfo

属性类型描述示例
price_idstring价格变更之后的定价 ID516816656060660549
effective_typestring价格变更的生效时机
  • immediate:立即生效
  • end_of_period:当前计费周期结束时生效
immediate
expected_effective_datestring预计生效时间2025-09-30T15:33:00Z
prorationstring结算类型
  • none: 无需结算分摊额
  • immediate:立即结算分摊额
immediate
change_invoice_idstring由订阅变更产生的 invoice 的 id516816656060660541
change_refund_idsstring由订阅变更产生的退款单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 --> [*]

动作对应的事件

  • 有试用期 & 首次订阅： 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": ""
  }
}

Updated about 2 months ago

Did this page help you?

Updated about 2 months ago

Did this page help you?
These developer docs retire on 2026-08-30. Visit the new docs: NEW DOCS本开发者文档将于 2026-08-30下线，请访问新版文档: 新文档