> ## 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 | subscription.trial\_period\_expiring | When a trial period expires in 3 days | [Subscription](/en/webhook/subscription-1) |
| First Subscription Activated | subscription.first | When a subscription is activated for the first time | [Subscription](/en/webhook/subscription-1) |
| Subscription Cancelled | subscription.canceled | When a subscription is actively cancelled | [Subscription](/en/webhook/subscription-1) |
| Subscription changed | subscription.price\_changed | when a subscription is upgraded or downgraded. | [Subscription](/en/webhook/subscription-1) |
## Event Object
| **Field** | **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 |
| 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
```mermaid theme={null}
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**: Triggers`subscription.first` event, with `subscription.status = trial` in the event object.
* **First Subscription**: Triggers`subscription.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 = initial` in the event object.
* **Payment Succeeds**: Triggers `invoice.paid` event, with `invoice.invoice_type = renewal` in the event object.
* **Payment Fails**: Triggers`invoice.payment_failed` event.
## Example
```json subscription.first theme={null}
{
"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"
}
}
```
```json subscription.canceled theme={null}
{
"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"
}
}
```
```json subscription.trial_period_expiring theme={null}
{
"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"
}
}
```
```json subscription.price_changed theme={null}
{
"id": 583570323576728234,
"type": "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"
}
}
```