事件列表

事件名称	事件类型	触发时机	通知数据结构
账单支付成功	v2.invoice.paid	当订阅产生的交易单支付成功才会通知，用于获取续订支付成功相关信息。	Invoice
账单支付失败	v2.invoice.payment_failed	当订阅产生的交易单支付失败才会通知，用于获取续订支付失败相关信息。	Invoice
账单退款	v2.invoice.refunded	当订阅产生的交易单退款成功时通知，用于获取订阅退款信息	Invoice

事件对象

属性	类型	描述	示例
id	string	账单唯一标识	529582021580696491
subscription_id	string	所属订阅计划的 ID	529582012596497323
customer_id	string	Subotiz 平台顾客唯一标识	529582012424532946
sub_merchant_id	string	商户ID	123061
amount	string	账单金额	0
currency	string	币种	USD
status	string	发票状态： open：初始化 success：已支付 failed：支付失败 refunded：全额退款 partially_refunded：部分退款	success
paid_at	string	支付时间	2025-07-01T08:49:53Z
invoice_type	string	发票类型： initial：首次支付 trial：试用期 renewal：续费 refund：退款	trial
created_at	string	创建时间	2025-07-01T08:49:50Z
updated_at	string	更新时间	2025-07-01T08:49:50Z
cycle_index	string	订阅周期序号，当为试用期时，周期为0。	1
cycle_start	string	周期开始时间	2025-07-01T08:49:50Z
cycle_end	string	周期结束时间	2025-07-01T08:49:50Z
order_id	string	外部订单 ID	order_123456
refund_id	string	退款id	20250807542984743692553415
trade_id	string	交易单 id	572677233903157186
original_invoice_id	string	invoice.refunded 事件中有值，关联退款的正向单	572677233903157182
metadata	map[string]string	发票上附带的元数据	`{ "key": "value" }`
subscription_data	SubscriptionData	发票所属的订阅数据	`{ "metadata": { "key": "value" } }`
discounts	Discounts	发票上的折扣，包括此发票的所有折扣信息	`{"current_period":[{"discount_id":"562218353725276866","discount_amount":"5.00","discount_code":"555"}]}`

SubscriptionData

属性	类型	描述
metadata	map[string]string	订阅上附带的元数据	`{ "key": "value" }`

Discounts

属性名	类型	描述
current_period	CurrentPeriodDiscount[]	当前时期的折扣详情

CurrentPeriodDiscount

属性名	类型	描述
discount_id	string	折扣的唯一标识符
discount_amount	string	折扣金额
discount_code	string	使用的折扣代码

示例数据

{
  "id": "572677256258790436",
  "type": "v2.invoice.paid",
  "created": "2025-10-28T06:54:56Z",
  "data": {
    "subscription_id": "572677251968024511",
    "order_id": "order_1761634475936438746",
    "sub_merchant_id": "2816433",
    "cycle_start": "2025-10-28T06:54:00Z",
    "status": "success",
    "invoice_type": "initial",
    "cycle_index": "1",
    "amount": "30",
    "updated_at": "2025-10-28T06:54:56Z",
    "trade_id": "572677233903157186",
    "id": "572677251968040895",
    "cycle_end": "2025-10-28T07:25:00Z",
    "customer_id": "547766341013094363",
    "currency": "USD",
    "paid_at": "2025-10-28T06:54:55Z",
    "created_at": "2025-10-28T06:54:56Z",
		"refund_id": "20250807542984743692553415"
  }
}

{
    "id": "572670998545971191",
    "type": "v2.invoice.payment_failed",
    "created": "2025-10-28T06:30:04Z",
    "data": {
        "sub_merchant_id": "2816514",
        "subscription_id": "570837058398981116",
        "cycle_start": "2025-10-26T05:03:00Z",
        "status": "failed",
        "customer_id": "570836074111455077",
        "created_at": "2025-10-26T05:20:01Z",
        "currency": "USD",
        "paid_at": null,
        "invoice_type": "initial",
        "updated_at": "2025-10-28T06:30:04Z",
        "id": "571928511522097676",
        "cycle_index": "1",
        "cycle_end": "2025-11-26T05:03:00Z",
        "amount": "199",
        "order_id": "order_1761195526005115801",
        "trade_id": "571928589088117469"
    }
}

{
  "id": "583625562099034794",
  "type": "v2.invoice.refunded",
  "created": "2025-11-27T11:59:37Z",
  "data": {
    "order_id": "order_1764230244388418776",
    "refund_id": "20251127583625544336174077",
    "original_invoice_id": "583564651824957126",
    "subscription_id": "583564651824940742",
    "cycle_start": "",
    "status": "refunded",
    "paid_at": null,
    "updated_at": "2025-11-27T11:59:36Z",
    "cycle_index": "0",
    "cycle_end": "",
    "customer_id": "537465921338359803",
    "amount": "2",
    "currency": "USD",
    "invoice_type": "refund",
    "id": "583602027389549049",
    "sub_merchant_id": "100010",
    "created_at": "2025-11-27T11:59:36Z"
  }
}