> ## 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.
# 发票
## 事件列表
| **事件名称** | **事件类型** | **触发时机** | **通知数据结构** |
| :------- | :------------------------- | :-------------------------------- | :----------------------------- |
| 账单支付成功 | v2.invoice.paid | 当订阅产生的交易单支付成功才会通知，用于获取续订支付成功相关信息。 | [Invoice](/zh/webhook/invoice) |
| 账单支付失败 | v2.invoice.payment\_failed | 当订阅产生的交易单支付失败才会通知，用于获取续订支付失败相关信息。 | [Invoice](/zh/webhook/invoice) |
| 账单退款 | v2.invoice.refunded | 当订阅产生的交易单退款成功时通知，用于获取订阅退款信息 | [Invoice](/zh/webhook/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 | 使用的折扣代码 |
## 示例数据
```json v2.invoice.paid theme={null}
{
"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"
}
}
```
```json v2.invoice.payment_failed theme={null}
{
"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"
}
}
```
```json v2.invoice.refunded theme={null}
{
"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"
}
}
```