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.	`{ "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

{
  "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"
  }
}