Event List

Event Name	Event Type	Trigger Condition	Data Structure
Trial Period Expiring Soon	v2.subscription.trial_period_expiring	When a trial period expires in 3 days	Subscription
First Subscription Activated	v2.subscription.first	When a subscription is activated for the first time	Subscription
Subscription Cancelled	v2.subscription.canceled	When a subscription is actively cancelled	Subscription
Subscription changed	v2.subscription.price_changed	when a subscription is upgraded or downgraded.	Subscription

Event Object

Field	Type	Description	Example
id	string	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	string	Unique identifier for the product pricing	516816656060660549
total_cycles	string	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	string	Index of the current billing cycle	1
cancel_at	string	The actual time of subscription cancellation	2025-07-01T13:40:25Z
cancel_reason	string	The reason for unsubscribing	Customer cancellation
next_price_info	NextPriceInfo	Subscription change information	`{ "price_id": "516816656060660549", "expected_effective_date": "2025-09-30T15:33:00Z", "proration":"none" }`
source_trade_id	string	The trade ID of the first payment for the subscription	516816656060660549
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" }`

NextPriceInfo

Field	Type	Description	Example
price_id	string	Pricing ID after price change	516816656060660549
expected_effective_date	string	Subscription change effective time	2025-09-30T15:33:00Z
proration	string	Settlement type none: No need to settle the allocation amount immediate:Immediate settlement of the allocation amount	immediate
change_invoice_id	string	The ID of the invoice resulting from the subscription change	516816656060660541
change_refund_ids	string	The refund ID generated due to subscription changes can be associated with the invoice.refund_id field.	`[ "20250807542984743692553411" "20250807542984743692553415" ]`

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: Triggersv2.subscription.first event, with subscription.status = trial in the event object.
First Subscription: Triggersv2.subscription.first , with subscription.status = active in the event object.
Subscription Canceled: Triggers v2.subscription.canceled event.
Trial Ends & Payment Succeeds: Triggers v2.invoice.paid event, with invoice.invoice_type = initial in the event object.
Payment Succeeds： Triggers v2.invoice.paid event, with invoice.invoice_type = renewal in the event object.
Payment Fails: Triggersv2.invoice.payment_failed event.

Example

{
  "id": "572677252513276964",
  "type": "v2.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": "v2.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": "v2.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"
    }
}

{
  "id": "583570323576728234",
  "type": "v2.subscription.price_changed",
  "created": "2025-11-27T08:20:07Z",
  "data": {
    "id": "583564651824940742",
    "price_id": "582401938335740273",
    "cycle_index": "1",
    "current_period_end": "2025-11-27T13:07:00Z",
    "next_invoice_date": "2025-11-27T13:08:00Z",
    "cancel_at": null,
    "total_cycles": "0",
    "cancel_reason": "",
    "created_at": "2025-11-27T07:57:35Z",
    "source_trade_id": "583564647529987790",
    "sub_merchant_id": "100010",
    "status": "active",
    "customer_id": "537465921338359803",
    "current_period_start": "2025-11-27T07:57:00Z",
    "next_price_info": {
      "price_id": "582402035266105713",
      "expected_effective_date": "2025-11-27T08:20:00Z",
      "proration": "immediate",
      "change_invoice_id": "583570320951084742",
      "change_refund_ids": null
    },
    "updated_at": "2025-11-27T07:57:35Z",
    "order_id": "order_1764230244388418776"
  }
}