> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Subscription
## 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](/en/webhook/subscription-2) |
| First Subscription Activated | v2.subscription.first | When a subscription is activated for the first time | [Subscription](/en/webhook/subscription-2) |
| Subscription Cancelled | v2.subscription.canceled | When a subscription is actively cancelled | [Subscription](/en/webhook/subscription-2) |
| Subscription changed | v2.subscription.price\_changed | when a subscription is upgraded or downgraded. | [Subscription](/en/webhook/subscription-2) |
| Subscription Paused | v2.subscription.paused | When a subscription is paused | [Subscription](/en/webhook/subscription-2) |
| Subscription Resumed | v2.subscription.resumed | When a subscription is resumed | [Subscription](/en/webhook/subscription-2) |
| Subscription Past Due | v2.subscription.past\_due | When a subscription payment is past due | [Subscription](/en/webhook/subscription-2) |
| Subscription Unpaid | v2.subscription.unpaid | When a subscription is marked as unpaid | [Subscription](/en/webhook/subscription-2) |
| Cancellation Revoked | v2.subscription.cancellation\_revoked | When a subscription cancellation is revoked | [Subscription](/en/webhook/subscription-2) |
| Cancellation Requested | v2.subscription.cancellation\_requested | When a subscription cancellation is requested | [Subscription](/en/webhook/subscription-2) |
| Fixed Term Updated | v2.subscription.fixed\_term\_updated | When a subscription's fixed term is modified | [Subscription](/en/webhook/subscription-2) |
| Price Change Revoked | v2.subscription.price\_change\_revoked | When a subscription price change is revoked | [Subscription](/en/webhook/subscription-2) |
## 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
```mermaid theme={null}
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**: Triggers`v2.subscription.first` event, with `subscription.status = trial` in the event object.
* **First Subscription**: Triggers`v2.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**: Triggers`v2.invoice.payment_failed` event.
## Example
```json v2.subscription.first theme={null}
{
"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"
}
}
```
```json v2.subscription.canceled theme={null}
{
"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"
}
}
```
```json v2.subscription.trial_period_expiring theme={null}
{
"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"
}
}
```
```json v2.subscription.price_changed theme={null}
{
"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"
}
}
```
```json v2.subscription.past_due theme={null}
{
"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"
}
}
```
```json v2.subscription.unpaid theme={null}
{
"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"
}
}
```
```json v2.subscription.paused theme={null}
{
"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"
}
}
```
```json v2.subscription.resumed theme={null}
{
"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": ""
}
}
```
```json v2.subscription.cancellation_requested theme={null}
{
"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": ""
}
}
```
```json v2.subscription.cancellation_revoked theme={null}
{
"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"
}
}
```