--- title: Subscription Status & Notifications permalink: /en/notes/integrate/subscription/lifecycle/ createTime: '2026/10/21 10:00:00' nosearch: true llm: exclude: true description: 'Explains Subscription statuses, notifyType events, previousAttributes, currentPeriod, cancelReason, and how to handle subscription, payment and refund notifications.' --- This page helps you understand Subscription status changes and notification results. For the main integration flow, read the [Subscription Integration Guide](/en/notes/integrate/subscription/integration/) first. ## Subscription State Diagram The diagram below is recommended as a shared reference for merchant-side joint debugging, product rule design and customer-service alignment. It describes **subscription plan status** changes and **which webhook event each transition fires** (the edge labels are the `notifyType` values): - `PENDING -> IN_TRIAL`: with a trial, the first authorization succeeds and the subscription enters the trial. - `PENDING -> ACTIVE`: without a trial, the first payment succeeds and the subscription takes effect directly. - `IN_TRIAL -> ACTIVE`: the trial ends and the conversion charge succeeds. - `IN_TRIAL -> PAST_DUE`: the trial ends and the conversion charge fails. - `ACTIVE -> PAST_DUE`: a renewal charge time arrives but the charge fails. - `PAST_DUE -> ACTIVE`: an automatic recovery charge succeeds and the subscription returns to normal. - `PENDING / ACTIVE / PAST_DUE -> CANCELLED`: cancelled after creation, cancelled by user/merchant, ended at term, or automatic retries exhausted. Common subscription status recommendations: - `PENDING`: the subscription is created but has not entered the formal effective stage; service activation is not recommended. - `IN_TRIAL`: the subscription is in trial; the service is currently usable. - `ACTIVE`: the subscription is in good standing; the user is entitled to keep using the service. - `PAST_DUE`: this renewal charge failed and the subscription is in arrears or automatic recovery; whether to keep serving is a merchant-side decision. - `CANCELLED`: the subscription is terminated and will not renew automatically. A consistent way to read `currentPeriod`: | Value | Meaning | Recommended action | |:---|:---|:---| | `0` | Trial period | Normally this should coincide with `status=IN_TRIAL` and a valid `trial` configuration; treat conflicting field combinations as abnormal data | | `1` | The first formal billing period | The first formal activation has completed | | `2` and above | Subsequent renewal periods | Continue fulfillment based on renewal records, status and entitlement rules | ## Subscription Notification Event Types It is recommended to handle subscription notifications by **`notifyType` (event type) + `status` (current status)** together, rather than watching status changes alone: Payment results and the subscription status changes they cause may be delivered through payment notifications and subscription notifications respectively. Verify and deduplicate the two kinds of notifications independently; **do not make your integration depend on the arrival order or spacing of webhooks**. When notifications are missing, duplicated or inconsistent, confirm via the query APIs as compensation. | notifyType | status | Typical meaning | What the merchant should do | Keep serving? | |:---|:---|:---|:---|:---:| | `SUBSCRIPTION_CREATED` | `PENDING` | Subscription created and pending effect (future `startAt`, no immediate charge) | Record the creation; wait for the later charge result | No | | `SUBSCRIPTION_IN_TRIAL` | `IN_TRIAL` | Entered the trial period | Activate trial entitlements; record `currentPeriod=0` | Yes | | `SUBSCRIPTION_ACTIVATED` | `ACTIVE` | First/conversion charge succeeded; subscription activated | Activate formal subscription entitlements | Yes | | `SUBSCRIPTION_PAST_DUE` | `PAST_DUE` | Renewal failed; entered grace period | Enter grace period / downgrade / remind top-up per business rules | Business decision | | `SUBSCRIPTION_RECOVERED` | `ACTIVE` | Recovery charge succeeded within the grace period | Restore formal service | Yes | | `SUBSCRIPTION_PLAN_CHANGED` | `ACTIVE` | Plan change effective (price/cycle change) | Update local plan, amount, cycle and entitlement version; diff the change with `previousAttributes` | Yes | | `SUBSCRIPTION_PLAN_CHANGE_SCHEDULED` | `ACTIVE` | A next-cycle change is registered | Record the scheduled change (`pendingUpdate`); handle it at the effective date | Yes | | `SUBSCRIPTION_PLAN_CHANGE_FAILED` | `ACTIVE` | Plan change failed (change fully rolled back) | Record the failure reason; prompt the user to retry the change | Yes | | `SUBSCRIPTION_CANCELLATION_SCHEDULED` | `ACTIVE` | Period-end cancellation marked | Record `cancelAt` (period end time); keep fulfilling this period | Yes | | `SUBSCRIPTION_CANCELLATION_REVOKED` | `ACTIVE` | Period-end cancellation mark revoked | Clear the local "cancellation scheduled" mark | Yes | | `SUBSCRIPTION_CANCELLED` | `CANCELLED` | Subscription cancelled | Turn off auto-renewal; stop or adjust service per the cancel reason | No | When `status=CANCELLED`, it is recommended to differentiate actions by `cancelReason`: | cancelReason | Scenario | Recommended merchant action | |:---|:---|:---| | `user_requested` | The user cancelled proactively | Stop service at the cancellation effective moment; no further auto-renewal | | `merchant_requested` | The merchant cancelled proactively | Handle per merchant-side cancellation policy; sync membership end time if needed | | `payment_retry_exhausted` | Automatic recovery attempts exhausted | Turn off auto-renewal; decide whether to suspend immediately or end the grace period | | `plan_ended` | The subscription ended naturally at term | Treat as plan expiry; no further renewal | ## Subscription Notification Payload Structure All `bizContent` fields of subscription notifications are camelCase, and time fields are second-level numeric timestamps: | Field | Type | Description | |:---|:---|:---| | `notifyType` | String | Event type (see the table above) | | `merchantSubscriptionId` | String | Merchant-side unique subscription plan ID | | `subscriptionId` | String | PingPong subscription number | | `requestId` | String | The merchant request number that triggered this event | | `status` | String | Current subscription plan status | | `flatPrice` | Object | Current effective per-period charge amount and currency | | `period` | Object | Billing cycle `{count, unit}` | | `totalPeriodCount` | Integer | Total number of billing periods (excluding the trial) | | `currentPeriod` | Integer | Current period number (0 = trial) | | `currentPeriodStartAt` | Long | Start of the current billing period, second-level timestamp | | `currentPeriodEndAt` | Long | End of the current billing period, second-level timestamp | | `startAt` | Long | Subscription start time, second-level timestamp | | `endAt` | Long | Subscription end time, second-level timestamp | | `updateAt` | Long | Generation time of this notification, second-level timestamp | | `cancelAtPeriodEnd` | Boolean | Whether period-end cancellation is scheduled | | `previousAttributes` | Object | **Snapshot of fields before the change** (returned only for change-type events, e.g. `flatPrice`, `endAt`, `status`); can be diffed against current values | | `paymentRecords` | Array | Payment record summary (returned for fund-type events such as renewal charges) | | `refundRecords` | Array | Refund records (returned for refund-type events) | | `action` | Object | PAST_DUE recovery action (returned only in `SUBSCRIPTION_PAST_DUE` notifications when the recovery checkout is available): `redirectUrl` is the recovery checkout URL; `actionExpiredAt` is its expiry (second-level timestamp, min(72 hours, remaining retry window) from generation) | | `discount` | Object | Currently effective discount configuration (returned when a discount is configured) | Future-effective creation notification example (`SUBSCRIPTION_CREATED`, future `startAt`, no immediate charge): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "subscriptionId": "SUB-2607140720100000000500111522", "requestId": "REQ_SUB_SESSION_202607150001", "notifyType": "SUBSCRIPTION_CREATED", "status": "PENDING", "currentPeriod": 0, "currentPeriodStartAt": 1786692039, "currentPeriodEndAt": 1789370439, "startAt": 1786692039, "endAt": 1789370439, "updateAt": 1784013639, "cancelAtPeriodEnd": false, "flatPrice": { "amount": "9.99", "currency": "USD" }, "period": { "count": 1, "unit": "MONTH" }, "totalPeriodCount": 12, "previousAttributes": { "status": "PENDING" } } ``` Trial entry notification example (`SUBSCRIPTION_IN_TRIAL`): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "subscriptionId": "SUB-2607140720100000000500111522", "requestId": "REQ_SUB_SESSION_202607150001", "notifyType": "SUBSCRIPTION_IN_TRIAL", "status": "IN_TRIAL", "currentPeriod": 0, "currentPeriodStartAt": 1784013639, "currentPeriodEndAt": 1784017239, "startAt": 1784013639, "endAt": 1786692039, "updateAt": 1784013639, "cancelAtPeriodEnd": false, "flatPrice": { "amount": "9.99", "currency": "USD" }, "period": { "count": 1, "unit": "MONTH" }, "totalPeriodCount": 12, "trial": { "startAt": 1784013639, "endAt": 1784017239, "periodDays": 7 }, "previousAttributes": { "status": "PENDING" } } ``` Subscription activation notification example (`SUBSCRIPTION_ACTIVATED`, showing `bizContent` only): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "subscriptionId": "SUB-2607140720100000000500111522", "requestId": "REQ_SUB_SESSION_202607150001", "notifyType": "SUBSCRIPTION_ACTIVATED", "status": "ACTIVE", "currentPeriod": 1, "currentPeriodStartAt": 1784013639, "currentPeriodEndAt": 1786692039, "startAt": 1784013639, "endAt": 1786692039, "updateAt": 1784013662, "cancelAtPeriodEnd": false, "flatPrice": { "amount": "9.99", "currency": "USD" }, "period": { "count": 1, "unit": "MONTH" }, "totalPeriodCount": 12, "previousAttributes": { "status": "PENDING" } } ``` Renewal failure entering grace period notification example (`SUBSCRIPTION_PAST_DUE`): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "subscriptionId": "SUB-2607140720100000000500111522", "requestId": "REQ_SUB_RENEW_202607160001", "notifyType": "SUBSCRIPTION_PAST_DUE", "status": "PAST_DUE", "currentPeriod": 2, "currentPeriodStartAt": 1785153662, "currentPeriodEndAt": 1787832062, "startAt": 1784013639, "endAt": 1786692039, "updateAt": 1785153662, "cancelAtPeriodEnd": false, "flatPrice": { "amount": "9.99", "currency": "USD" }, "period": { "count": 1, "unit": "MONTH" }, "totalPeriodCount": 12, "autoRecovery": { "enabled": true, "attemptCount": 1, "maxAttempts": 1, "status": "ACTIVE" }, "action": { "redirectUrl": "https://sandbox-safepay.pingpongx.com?token=...", "actionExpiredAt": 1792200000 } } ``` > `action` is the PAST_DUE recovery checkout URL. See [Renewal & Auto-Recovery · PAST_DUE recovery checkout](/en/notes/integrate/subscription/renewal-recovery/#past-due-recovery-checkout-action). Grace period recovery notification example (`SUBSCRIPTION_RECOVERED`): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "subscriptionId": "SUB-2607140720100000000500111522", "requestId": "REQ_SUB_RECOVER_202607170001", "notifyType": "SUBSCRIPTION_RECOVERED", "status": "ACTIVE", "currentPeriod": 2, "currentPeriodStartAt": 1785153662, "currentPeriodEndAt": 1787832062, "startAt": 1784013639, "endAt": 1786692039, "updateAt": 1785240000, "cancelAtPeriodEnd": false, "flatPrice": { "amount": "9.99", "currency": "USD" }, "period": { "count": 1, "unit": "MONTH" }, "totalPeriodCount": 12, "previousAttributes": { "status": "PAST_DUE" } } ``` Plan change notification example (`SUBSCRIPTION_PLAN_CHANGED`, with previousAttributes diff): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "subscriptionId": "SUB-2607140720100000000500111522", "requestId": "REQ_SUB_UPDATE_202607160001", "notifyType": "SUBSCRIPTION_PLAN_CHANGED", "status": "ACTIVE", "currentPeriod": 1, "currentPeriodStartAt": 1784013639, "currentPeriodEndAt": 1786692039, "startAt": 1784013639, "endAt": 1786692039, "updateAt": 1784015000, "cancelAtPeriodEnd": false, "flatPrice": { "amount": "15.00", "currency": "USD" }, "period": { "count": 1, "unit": "MONTH" }, "totalPeriodCount": 12, "previousAttributes": { "flatPrice": { "amount": "9.99", "currency": "USD" } } } ``` Next-cycle change scheduled notification example (`SUBSCRIPTION_PLAN_CHANGE_SCHEDULED`): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "subscriptionId": "SUB-2607140720100000000500111522", "requestId": "REQ_SUB_UPDATE_202607160001", "notifyType": "SUBSCRIPTION_PLAN_CHANGE_SCHEDULED", "status": "ACTIVE", "currentPeriod": 1, "currentPeriodStartAt": 1784013639, "currentPeriodEndAt": 1786692039, "startAt": 1784013639, "endAt": 1786692039, "updateAt": 1784015000, "cancelAtPeriodEnd": false, "flatPrice": { "amount": "9.99", "currency": "USD" }, "period": { "count": 1, "unit": "MONTH" }, "totalPeriodCount": 12, "pendingUpdate": { "effectiveMode": "NEXT_CYCLE", "flatPrice": { "amount": "15.00", "currency": "USD" } } } ``` > `status` stays `ACTIVE` and the top-level `flatPrice` remains the current period's price; the scheduled change content is in `pendingUpdate`, and a `SUBSCRIPTION_PLAN_CHANGED` will be pushed after it takes effect at the next cycle. Plan change failed notification example (`SUBSCRIPTION_PLAN_CHANGE_FAILED`, change fully rolled back): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "subscriptionId": "SUB-2607140720100000000500111522", "requestId": "REQ_SUB_UPDATE_202607160001", "notifyType": "SUBSCRIPTION_PLAN_CHANGE_FAILED", "status": "ACTIVE", "currentPeriod": 1, "currentPeriodStartAt": 1784013639, "currentPeriodEndAt": 1786692039, "startAt": 1784013639, "endAt": 1786692039, "updateAt": 1784015000, "cancelAtPeriodEnd": false, "flatPrice": { "amount": "9.99", "currency": "USD" }, "period": { "count": 1, "unit": "MONTH" }, "totalPeriodCount": 12, "pendingUpdate": { "effectiveMode": "IMMEDIATE", "flatPrice": { "amount": "15.00", "currency": "USD" } }, "resultCode": "system_internal_gateway_error", "resultMessage": "Internal gateway error" } ``` > The failed intent stays in `pendingUpdate`; the subscription price and status roll back as a whole (price still 9.99, still ACTIVE). Period-end cancellation scheduled notification example (`SUBSCRIPTION_CANCELLATION_SCHEDULED`): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "subscriptionId": "SUB-2607140720100000000500111522", "requestId": "REQ_SUB_CANCEL_202607160001", "notifyType": "SUBSCRIPTION_CANCELLATION_SCHEDULED", "status": "ACTIVE", "currentPeriod": 1, "currentPeriodStartAt": 1784013639, "currentPeriodEndAt": 1786692039, "startAt": 1784013639, "endAt": 1786692039, "updateAt": 1784015000, "cancelAtPeriodEnd": true, "flatPrice": { "amount": "9.99", "currency": "USD" }, "period": { "count": 1, "unit": "MONTH" }, "totalPeriodCount": 12 } ``` > `status` stays `ACTIVE`; `cancelAtPeriodEnd=true` means period-end cancellation is marked. Period-end cancellation revoked notification example (`SUBSCRIPTION_CANCELLATION_REVOKED`): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "subscriptionId": "SUB-2607140720100000000500111522", "requestId": "REQ_SUB_UPDATE_202607170001", "notifyType": "SUBSCRIPTION_CANCELLATION_REVOKED", "status": "ACTIVE", "currentPeriod": 1, "currentPeriodStartAt": 1784013639, "currentPeriodEndAt": 1786692039, "startAt": 1784013639, "endAt": 1786692039, "updateAt": 1784100000, "cancelAtPeriodEnd": false, "flatPrice": { "amount": "9.99", "currency": "USD" }, "period": { "count": 1, "unit": "MONTH" }, "totalPeriodCount": 12, "previousAttributes": { "cancelAtPeriodEnd": true } } ``` > `cancelAtPeriodEnd` changed back from `true` to `false`, meaning the period-end cancellation mark was revoked. Subscription cancelled notification example (`SUBSCRIPTION_CANCELLED`): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "subscriptionId": "SUB-2607140720100000000500111522", "requestId": "REQ_SUB_CANCEL_202607160001", "notifyType": "SUBSCRIPTION_CANCELLED", "status": "CANCELLED", "currentPeriod": 1, "currentPeriodStartAt": 1784013639, "currentPeriodEndAt": 1786692039, "startAt": 1784013639, "endAt": 1784100000, "updateAt": 1784100000, "cancelAtPeriodEnd": false, "cancelReason": "merchant_requested", "flatPrice": { "amount": "9.99", "currency": "USD" }, "period": { "count": 1, "unit": "MONTH" }, "totalPeriodCount": 12, "previousAttributes": { "status": "ACTIVE" } } ``` > `status` becomes `CANCELLED`; `cancelReason` is the cancellation reason (lowercase enum: `merchant_requested` / `user_requested` / `payment_retry_exhausted` / `plan_ended`). ## Payment and Refund Notifications Subscription payment result in a payment notification example (showing `bizContent` only): ```json { "transactionId": "26071400000051156949", "merchantTransactionId": "SUB_PLAN_202607150001_P1", "requestId": "074dbbe1-bb21-4bbd-8223-8dd6757d69b1", "status": "SUCCESS", "amount": "100.000000", "currency": "USD", "invoiceId": "INV-2610161210100000008200011522", "paymentMethod": { "type": "VISA" }, "subscriptionDetail": { "subscriptionId": "SUB-2607140846100000000900111522", "merchantSubscriptionId": "SUB_PLAN_202607150001", "currentPeriod": 1, "autoRecovery": { "enabled": true, "attemptCount": 0, "maxAttempts": 1, "status": "ACTIVE" } } } ``` This example usually means: - This period's payment has succeeded; - The success corresponds to the formal billing period `currentPeriod=1`; - **`invoiceId` is the key field linking to Invoice reconciliation** (use it to call the [Invoice Details](/en/notes/subscription/invoice/query/) API); - Use `merchantTransactionId` / `transactionId` for payment reconciliation; - Use `subscriptionDetail.subscriptionId` to link back to the subscription master record. Subscription refund notification example (showing `bizContent` only): ```json { "amount": "4.840000", "refundTime": "1785293461000", "remark": "subscription update refund, taskId=517", "transactionId": "26072900000151333315", "notifyType": "REFUND", "merchantTransactionId": "SUB-2607290250100000032300111522_P1", "currency": "USD", "merchantRefundId": "SREF-2607290251100000004100151522", "refundEndingTime": "1785293463485", "refundId": "26072900010451333317", "status": "SUCCESS" } ``` This example usually means: - This refund has succeeded; - `merchantRefundId` / `refundId` can be used for refund-level idempotency and reconciliation; - `merchantTransactionId` is the original payment's merchant transaction number associated with the refund; - A successful refund does not mean the subscription is cancelled or a plan has taken effect — the subscription-level status should still come from subscription notifications or the Query Subscription API. Query subscription payments response example (showing `bizContent` only): ```json { "merchantSubscriptionId": "SUB_MER_001", "subscriptionId": "SUB-1234567890abcdef", "requestId": "REQ_SUB_PAYMENT_QUERY_001", "paymentRecords": [ { "period": 1, "merchantTransactionId": "SUB-1234567890abcdef_P1", "transactionId": "PAY-ORDER-1234567890", "requestId": "SPAY-1234567890", "amount": "9.99", "currency": "USD", "status": "SUCCESS", "transactionTime": "1785152760000", "transactionEndingTime": "1785152860000", "paymentMethod": { "type": "VISA" } } ], "resultCode": "000000", "resultMessage": "SUCCESS" } ``` To answer "can this subscription keep receiving service right now", look at the subscription result first; to answer "was this period actually charged, how much, and with which payment method", look at the payment result first. ::: warning Note - `status` at the top level of the subscription query and in subscription notifications is the subscription plan status; `paymentRecords[].status` in payment notifications is the single-payment status. - `currentPeriod` sits at the top level of the notification `bizContent`; `0` means the trial period. Normally this should coincide with `status=IN_TRIAL` and a valid `trial` configuration. - If you receive both payment and subscription notifications, apply idempotency to each independently — do not treat them as the same notification. - If an Update or Cancel triggers a refund but the refund notification is delayed, missing, or lacks a linkable refund number, use [Query Subscription Payments](/en/notes/subscription/api/paymentsQuery/) and [Query Subscription](/en/notes/subscription/api/query/) for compensation confirmation. ::: ::: warning Time field compatibility In **API requests**, `startAt` and `endAt` are 10-digit second-level timestamp strings per the interface definition. In **API responses** (query/update/cancel), `startAt`, `endAt`, `cancelAt`, `transactionTime`, `transactionEndingTime` etc. are 13-digit millisecond timestamp strings. In **subscription notifications** (webhooks), `startAt`, `endAt`, `updateAt`, `currentPeriodStartAt` and `currentPeriodEndAt` are second-level numeric timestamps. Parse per channel, and avoid integer types that can only hold 32 bits. :::