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 Fails: Triggersinvoice.payment_failed event.