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
Subscription Paused	v2.subscription.paused	When a subscription is paused	Subscription
Subscription Resumed	v2.subscription.resumed	When a subscription is resumed	Subscription
Subscription Past Due	v2.subscription.past_due	When a subscription payment is past due	Subscription
Subscription Unpaid	v2.subscription.unpaid	When a subscription is marked as unpaid	Subscription
Cancellation Revoked	v2.subscription.cancellation_revoked	When a subscription cancellation is revoked	Subscription
Cancellation Requested	v2.subscription.cancellation_requested	When a subscription cancellation is requested	Subscription
Fixed Term Updated	v2.subscription.fixed_term_updated	When a subscription's fixed term is modified	Subscription
Price Change Revoked	v2.subscription.price_change_revoked	When a subscription price change is revoked	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. May be a timestamp, a descriptive string (e.g. "Charged when usage-based fees reach $2.00"), or empty depending on the billing mode.	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" }`
paused_at	string	The period of subscription suspension	2025-07-01T13:40:25Z
initiate_cancel_at	string	The time when the subscription cancellation was initiated	2025-07-01T13:40:25Z
expected_cancel_at	string	The expected date of subscription cancellation	2025-07-01T13:40:25Z
price_version_id	string	Product pricing plan version unique identifier	585661231470226668
first_source_channel	string	The source where this checkout session was initially created
last_source_channel	string	The source where this checkout session was last accessed
is_renewable	bool	Whether the subscription automatically converts to an ongoing subscription upon expiration	false
end_at	string	Subscription end time. An empty string indicates an ongoing subscription (no end time)
current_period_num	string	Current period number	1
previous_fixed_term_info	object	Previous fixed-term information before the change. Only present in the `v2.subscription.fixed_term_updated` event. Contains sub-fields: `previous_fixed_term` (string), `previous_is_renewable` (bool), `previous_end_at` (string)	`null`

NextPriceInfo

Field	Type	Description	Example
price_id	string	Pricing ID after price change	516816656060660549
effective_type	string	The effective timing of the price change immediate: takes effect immediately end_of_period: takes effect at the end of the current billing period	immediate
expected_effective_date	string	The expected effective time of the price change	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-v2
    [*] --> Trial : Order placed with trial period
    [*] --> Active : Order placed without trial period

    Trial --> Active : Prepaid： Charge successful after trial ends
    Trial --> Active : Postpaid：First period activated after trial ends
    Trial --> PastDue : First charge failed after trial ends
    Trial --> Canceled : Subscription canceled

    Active --> Paused : Subscription paused
    Active --> PastDue : Renewal failed, retrying payment
    Active --> Canceled : Subscription canceled

    Paused --> Active : Subscription resumed
    Paused --> Canceled : Subscription canceled

    PastDue --> Active : Retry payment successful
    PastDue --> Unpaid : Max retries reached or grace period expired
    PastDue --> Canceled : Subscription canceled or grace period expired

    Unpaid --> Canceled : Subscription canceled
    Unpaid --> Canceled : Grace period expired
    Unpaid --> Unpaid : Grace period expired, marked as unpaid
    Unpaid --> Active : Payment method updated and charged successfully

    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": "654282672553592775",
  "type": "v2.subscription.price_changed",
  "created": "2026-07-10T11:23:00Z",
  "data": {
    "status": "active",
    "end_at": "",
    "previous_fixed_term_info": null,
    "current_period_start": "2026-06-10T11:23:00Z",
    "order_id": "test_order_00111",
    "next_price_info": {
      "proration": "none",
      "change_invoice_id": "",
      "change_refund_ids": null,
      "usage_invoice_id": "",
      "price_id": "608934085099784585",
      "price_version_id": "608934085099784585",
      "effective_type": "end_of_period",
      "expected_effective_date": "Charged when usage-based fees reach $20.00"
    },
    "initiate_cancel_at": "",
    "customer_id": "539729972764360694",
    "price_version_id": "629136800761259429",
    "cancel_reason": "",
    "is_renewable": true,
    "created_at": "2026-06-10T11:23:32Z",
    "source_trade_id": "654281916278652917",
    "first_source_channel": "",
    "cycle_index": "0",
    "next_invoice_date": "Charged when usage-based fees reach $20.00",
    "updated_at": "2026-06-10T11:23:32Z",
    "expected_cancel_at": "",
    "price_id": "608933940362740418",
    "current_period_end": "2026-06-10T11:23:00Z",
    "last_source_channel": "",
    "id": "654282114438533136",
    "total_cycles": "2",
    "sub_merchant_id": "364861",
    "cancel_at": null,
    "paused_at": "",
    "current_period_num": "1"
  }
}

{
  "id": "604229309149746453",
  "type": "v2.subscription.past_due",
  "created": "2026-01-23T07:50:55Z",
  "data": {
    "customer_id": "541822454956310498",
    "total_cycles": "0",
    "created_at": "2026-01-23T07:44:32Z",
    "initiate_cancel_at": "",
    "first_source_channel": "",
    "last_source_channel": "",
    "current_period_start": "2026-01-23T07:44:00Z",
    "next_invoice_date": "Charged when usage-based fees reach $20.00",
    "cancel_at": null,
    "cancel_reason": "",
    "source_trade_id": "604217431497390041",
    "metadata": null,
    "expected_cancel_at": "",
    "price_id": "585661231470226668",
    "order_id": "order_1769154252871463378",
    "paused_at": "",
    "updated_at": "2026-01-23T07:50:55Z",
    "next_price_info": null,
    "id": "604217479710908319",
    "sub_merchant_id": "2816433",
    "status": "past_due",
    "price_version_id": "585661231470226668",
    "cycle_index": "1",
    "current_period_end": "2026-01-23T07:50:01Z"
  }
}

{
  "id": "604230206634333461",
  "type": "v2.subscription.unpaid",
  "created": "2026-01-23T08:30:08Z",
  "data": {
    "expected_cancel_at": "",
    "sub_merchant_id": "2816433",
    "price_id": "600585046541216169",
    "cycle_index": "1",
    "cancel_reason": "",
    "first_source_channel": "",
    "source_trade_id": "603856934524690415",
    "customer_id": "541822454956310498",
    "total_cycles": "0",
    "cancel_at": null,
    "created_at": "2026-01-22T07:52:13Z",
    "order_id": "order_1769068305139700301",
    "price_version_id": "600585046541216169",
    "next_invoice_date": "2026-01-22T08:16:00Z",
    "next_price_info": null,
    "metadata": null,
    "paused_at": "",
    "last_source_channel": "",
    "initiate_cancel_at": "",
    "id": "603857024144389364",
    "status": "unpaid",
    "current_period_start": "2026-01-22T07:52:00Z",
    "current_period_end": "2026-01-22T09:02:00Z",
    "updated_at": "2026-01-23T08:30:08Z"
  }
}

{
  "id": "603927306368453965",
  "type": "v2.subscription.paused",
  "created": "2026-01-22T12:31:30Z",
  "data": {
    "price_version_id": "585661231470226668",
    "cycle_index": "1",
    "next_price_info": null,
    "first_source_channel": "",
    "paused_at": "2026-01-22T12:31:00Z",
    "total_cycles": "0",
    "updated_at": "2026-01-22T12:31:30Z",
    "source_trade_id": "603889788398876633",
    "initiate_cancel_at": "",
    "expected_cancel_at": "",
    "id": "603889808367951518",
    "price_id": "585661231470226668",
    "current_period_start": "2026-01-22T10:02:00Z",
    "current_period_end": "-",
    "cancel_reason": "",
    "last_source_channel": "",
    "metadata": null,
    "sub_merchant_id": "2816433",
    "status": "paused",
    "customer_id": "541822454956310498",
    "next_invoice_date": "-",
    "cancel_at": null,
    "created_at": "2026-01-22T10:02:30Z",
    "order_id": "order_1769076135405830680"
  }
}

{
  "id": "603928258563542349",
  "type": "v2.subscription.resumed",
  "created": "2026-01-22T12:35:17Z",
  "data": {
    "cancel_at": null,
    "price_id": "585661231470226668",
    "price_version_id": "585661231470226668",
    "total_cycles": "0",
    "next_invoice_date": "Charged when usage-based fees reach $20.00",
    "created_at": "2026-01-22T10:02:30Z",
    "source_trade_id": "603889788398876633",
    "next_price_info": null,
    "last_source_channel": "",
    "id": "603889808367951518",
    "cycle_index": "1",
    "current_period_start": "2026-01-22T10:02:00Z",
    "paused_at": "",
    "initiate_cancel_at": "",
    "customer_id": "541822454956310498",
    "current_period_end": "2026-01-22T10:10:02Z",
    "metadata": null,
    "updated_at": "2026-01-22T12:35:17Z",
    "order_id": "order_1769076135405830680",
    "first_source_channel": "",
    "expected_cancel_at": "",
    "sub_merchant_id": "2816433",
    "status": "active",
    "cancel_reason": ""
  }
}

{
  "id": "605206977064209227",
  "type": "v2.subscription.cancellation_requested",
  "created": "2026-01-26T01:16:27Z",
  "data": {
    "paused_at": "",
    "expected_cancel_at": "2026-01-26T01:16:00Z",
    "sub_merchant_id": "2816433",
    "total_cycles": "0",
    "current_period_start": "2026-01-22T13:05:00Z",
    "source_trade_id": "603889788398876633",
    "first_source_channel": "",
    "last_source_channel": "",
    "price_id": "597247070985830078",
    "current_period_end": "2026-01-26T01:16:27Z",
    "cancel_at": "2026-01-26T01:16:00Z",
    "updated_at": "2026-01-26T01:16:27Z",
    "order_id": "order_1769076135405830680",
    "id": "603889808367951518",
    "next_invoice_date": "Charged when usage-based fees reach $30.00",
    "created_at": "2026-01-22T10:02:30Z",
    "initiate_cancel_at": "2026-01-26T01:16:00Z",
    "next_price_info": null,
    "metadata": null,
    "status": "canceled",
    "customer_id": "541822454956310498",
    "price_version_id": "597247070985830078",
    "cycle_index": "1",
    "cancel_reason": ""
  }
}

{
  "id": "603909739125935437",
  "type": "v2.subscription.cancellation_revoked",
  "created": "2026-01-22T11:21:41Z",
  "data": {
    "current_period_end": "2026-01-22T12:30:00Z",
    "next_invoice_date": "2026-01-22T12:31:00Z",
    "cancel_reason": "",
    "updated_at": "2026-01-22T11:21:41Z",
    "order_id": "order_1769080829192130135",
    "paused_at": "",
    "total_cycles": "0",
    "current_period_start": "2026-01-22T11:20:00Z",
    "sub_merchant_id": "2816433",
    "expected_cancel_at": "",
    "customer_id": "541822454956310498",
    "price_id": "594101578214976042",
    "cycle_index": "1",
    "cancel_at": null,
    "source_trade_id": "603909473999796185",
    "next_price_info": null,
    "id": "603909515594702494",
    "status": "active",
    "metadata": null,
    "first_source_channel": "",
    "last_source_channel": "",
    "initiate_cancel_at": "",
    "price_version_id": "599077413057465741",
    "created_at": "2026-01-22T11:20:48Z"
  }
}