Event List
| Event Name | Event Type | Trigger Condition | Data Structure |
|---|---|---|---|
| Invoice Paid | invoice.paid | When an invoice is paid successfully. | Invoice |
| Invoice Payment Failed | invoice.payment_failed | When an attempt to pay an invoice fails | Invoice |
| Invoice Refunded | invoice.refunded | Notify when the transaction order generated by the subscription is successfully refunded, for obtaining subscription refund information | 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. | {<br/>"key": "value"<br/>} |
| subscription_data | SubscriptionData | Subscription data associated with the invoice | {<br/>"metadata": {<br/>"key": "value"<br/>}<br/>} |
| 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
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}