Event List

Event Name	Event Type	Trigger Condition	Data Structure
Trial Period Expiring Soon	subscription.trial_period_expiring	When a trial period expires in 3 days (single reminder)	Subscription
First Subscription Activated	subscription.first	When a subscription is activated for the first time	Subscription
Subscription Cancelled	subscription.canceled	When a subscription is actively cancelled	Subscription

Event Object

Attribute	Type	Description	Example
id	uint64	Unique identifier for the subscription plan	516816656060660549
customer_id	string	Unique identifier for the customer on Subotiz	516816656060660549
sub_merchant_id	string	Unique identifier for the merchant	123061
status	string	Subscription status: init-Pending activation trial- Trial period active-Active canceled- Terminated incomplete- Incomplete	init
price_id	uint64	Unique identifier for the product pricing	516816656060660549
total_cycles	int	Total number of billing cycles. 0 indicates an indefinite subscription.	0
current_period_start	string	Start time of the current billing period.	2025-07-01T13:40:25Z
current_period_end	string	End time of the current billing period.	2025-07-01T13:40:25Z
next_invoice_date	string	Next charge date	2025-07-01T13:40:25Z
created_at	string	Creation time	2025-07-01T13:40:25Z
updated_at	string	Last update time	2025-07-01T13:40:25Z
order_id	string	Your platform's order ID	order_123456
cycle_index	int	Index of the current billing cycle	1

Subscription Lifecycle

stateDiagram
    [*] --> init
    init --> trial : Has Trial & First Subscription
    init --> active : First Subscription
    init --> incomplete : Payment Failed
    trial --> active : Trial Ends & Payment Succeeds
    trial --> incomplete : Payment Failed
    active --> incomplete : Payment Failed
    active --> canceled : Subscription Canceled
    incomplete --> canceled : Subscription Canceled
    canceled --> [*]

Actions and Corresponding Events

Has Trial & First Subscription: Triggerssubscription.first event, with subscription.status = trial in the event object.
First Subscription: Triggerssubscription.first , with subscription.status = active in the event object.
Subscription Canceled: Triggers subscription.canceled event.
Trial Ends & Payment Succeeds: Triggers invoice.paid event, with invoice.invoice_type = renewal in the event object.
Payment Succeeds： Triggers invoice.paid event, with invoice.invoice_type = renewal in the event object.
Payment Fails: Triggersinvoice.payment_failed event.

Example

{
  "id": 572677252513276964,
  "type": "subscription.first",
  "created": "2025-10-28T06:54:56Z",
  "data": {
    "price_id": 572349501902208959,
    "total_cycles": 0,
    "current_period_start": "2025-10-28T06:54:00Z",
    "cancel_at": null,
    "source_trade_id": "572677233903157186",
    "id": 572677251968024511,
    "customer_id": "547766341013094363",
    "cancel_reason": "",
    "updated_at": "2025-10-28T06:54:56Z",
    "current_period_end": "2025-10-28T07:25:00Z",
    "next_price_info": null,
    "cycle_index": 1,
    "next_invoice_date": "2025-10-28T07:26:00Z",
    "created_at": "2025-10-28T06:54:56Z",
    "order_id": "order_1761634475936438746",
    "sub_merchant_id": "2216433",
    "status": "active"
  }
}

{
  "id": 572682701203579940,
  "type": "subscription.canceled",
  "created": "2025-10-28T07:16:35Z",
  "data": {
    "price_id": 572349625697058751,
    "created_at": "2025-10-28T06:54:56Z",
    "updated_at": "2025-10-28T07:16:35Z",
    "next_price_info": null,
    "current_period_start": "2025-10-28T06:54:00Z",
    "current_period_end": "2025-10-28T07:25:00Z",
    "next_invoice_date": "2025-10-28T07:26:00Z",
    "cancel_at": "2025-10-28T07:16:00Z",
    "id": 572677251968024511,
    "total_cycles": 0,
    "cycle_index": 1,
    "cancel_reason": "cancel",
    "order_id": "order_1761634475936438746",
    "sub_merchant_id": "2816433",
    "status": "canceled",
    "customer_id": "547766341013094363",
    "source_trade_id": "572677233903157186"
  }
}

{
    "id": 572670992330012613,
    "type": "subscription.trial_period_expiring",
    "created": "2025-10-28T06:30:01Z",
    "data": {
        "id": 572664015193371988,
        "customer_id": "567609424412263252",
        "price_id": 563378244649234223,
        "current_period_start": "2025-10-28T06:02:00Z",
        "updated_at": "2025-10-28T06:02:20Z",
        "total_cycles": 0,
        "current_period_end": "2025-10-31T06:02:00Z",
        "cancel_at": null,
        "created_at": "2025-10-28T06:02:20Z",
        "source_trade_id": "572663537512178624",
        "sub_merchant_id": "1216433",
        "status": "trial",
        "next_invoice_date": "2025-10-31T06:03:00Z",
        "cancel_reason": "",
        "cycle_index": 0,
        "order_id": "order_1761631220208894185"
    }
}