> ## 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.
# Invoice
## Event List
| **Event Name** | **Event Type** | **Trigger Condition** | **Data Structure** |
| :--------------------- | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------- |
| Invoice Paid | invoice.paid | When an invoice is paid successfully. | [Invoice](/en/webhook/invoice) |
| Invoice Payment Failed | invoice.payment\_failed | When an attempt to pay an invoice fails | [Invoice](/en/webhook/invoice) |
| Invoice Refunded | invoice.refunded | Notify when the transaction order generated by the subscription is successfully refunded, for obtaining subscription refund information | [Invoice](/en/webhook/invoice) |
## Event Object
| **Field** | **Type** | **Description** | **Example** |
| --------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| id | uint64 | Unique identifier for the invoice | 529582021580696491 |
| subscription\_id | uint64 | ID of the associated subscription plan | 529582012596497323 |
| customer\_id | string | Unique identifier for the customer on Subotiz | 529582012424532946 |
| sub\_merchant\_id | string | Merchant ID | 123061 |
| amount | string | Invoice amount | 0 |
| currency | string | Currency | USD |
| status | string | Invoice status:
open- Initiated/Open
success- Paid
failed- Payment failed
refunded- Fully refunded
partially\_refunded-Partially refunded | success |
| paid\_at | string | Invoice payment time | 2025-07-01T08:49:53Z |
| invoice\_type | string | Invoice type:
initial-Initial payment
trail- Trial period
renewal-Renewal
refund-Refund | trial |
| created\_at | string | Creation time | 2025-07-01T08:49:50Z |
| updated\_at | string | Last update time | 2025-07-01T08:49:50Z |
| cycle\_index | Int | Index of billing cycle. For trial, the index is 0. | 1 |
| cycle\_start | string | Start time of the billing cycle | 2025-07-01T08:49:50Z |
| cycle\_end | string | End time of the billing cycle | 2025-07-01T08:49:50Z |
| order\_id | string | Your platform's external order ID | order\_123456 |
| refund\_id | string | Refund order ID | 20250807542984743692553415 |
| trade\_id | string | Trade ID | 572677233903157186 |
| original\_invoice\_id | string | When the `invoice.refunded` event has a value, it indicates a positive refund transaction. | 572677233903157182 |
| metadata | map\[string]string | A set of key-value pairs that can be attached to an object, allowing you to store additional information in a structured format. | `{
"key": "value"
}` |
| subscription\_data | SubscriptionData | Subscription data associated with the invoice | `{
"metadata": {
"key": "value"
}
}` |
| discounts | Discounts | Discounts applied to the invoice, including all discount information for this invoice | `{"current_period":[{"discount_id":"562218353725276866","discount_amount":"5.00","discount_code":"555"}]}` |
### Discounts
| Field | Type | Desc |
| :-------------- | :----------------------- | :------------------------------------ |
| current\_period | CurrentPeriodDiscount\[] | The current period's discount details |
### CurrentPeriodDiscount
| Field | Type | Desc |
| :--------------- | :----- | :------------------------------------- |
| discount\_id | string | The unique identifier for the discount |
| discount\_amount | string | The amount discounted |
| discount\_code | string | The discount code used |
## Example
```json invoice.paid theme={null}
{
"id": 583564654786128554,
"type": "invoice.paid",
"created": "2025-11-27T07:57:35Z",
"data": {
"sub_merchant_id": "100010",
"subscription_id": 583564651824940742,
"status": "success",
"customer_id": "537465921338359803",
"id": 583564651824957126,
"created_at": "2025-11-27T07:57:35Z",
"order_id": "order_1764230244388418776",
"original_invoice_id": "",
"cycle_end": "2025-11-27T13:07:00Z",
"amount": "10",
"updated_at": "2025-11-27T07:57:35Z",
"trade_id": "583564647529987790",
"refund_id": "",
"cycle_index": 1,
"cycle_start": "2025-11-27T07:57:00Z",
"currency": "USD",
"paid_at": "2025-11-27T07:57:34Z",
"invoice_type": "initial"
}
}
```
```json invoice.payment_failed theme={null}
{
"id": 583570614258772650,
"type": "invoice.payment_failed",
"created": "2025-11-27T08:20:59Z",
"data": {
"customer_id": "537465921338359803",
"updated_at": "2025-11-27T08:20:59Z",
"order_id": "order_1764230244388418776",
"original_invoice_id": "",
"status": "pending",
"cycle_index": 1,
"currency": "USD",
"paid_at": null,
"trade_id": "583570322570100430",
"id": 583570320951084742,
"invoice_type": "upgrade",
"created_at": "2025-11-27T08:20:06Z",
"amount": "9.26",
"subscription_id": 583564651824940742,
"cycle_start": "2025-11-27T07:57:00Z",
"cycle_end": "2025-11-27T13:07:00Z",
"refund_id": "",
"sub_merchant_id": "100010"
}
}
```
```json invoice.refunded theme={null}
{
"id": 583625562099034794,
"type": "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"
}
}
```