--- title: Renewal & Auto-Recovery permalink: /en/notes/integrate/subscription/renewal-recovery/ createTime: '2026/10/21 10:00:00' nosearch: true llm: exclude: true description: 'Covers Subscription auto-renewal, renewal failure, PAST_DUE, automatic retries, recovery charges and payment record query recommendations.' --- This page covers renewal, failed-charge retry and compensation queries after a subscription becomes active. For the main integration flow, read the [Subscription Integration Guide](/en/notes/integrate/subscription/integration/) first. ## Handling Renewals and Recovery Charges - At the end of each billing period, PingPong automatically initiates the renewal charge according to the subscription plan. - If a renewal charge fails and `autoRecovery.enabled=true`, the subscription enters `PAST_DUE` and retries according to the automatic retry policy. - If `autoRecovery.enabled=false`, there is no automatic retry after a failed charge and the subscription transitions to `CANCELLED`. - Retry counts and intervals use the platform default policy (see [Automatic retry mechanism](#automatic-retry-mechanism-and-the-past-due-recovery-action) below); merchant-defined retry policies are not supported by the current baseline capability. Non-retryable outcomes such as hard declines and risk-control rejections do not enter automatic retry. - When automatic retries are exhausted, the subscription transitions to `CANCELLED` with `cancelReason=payment_retry_exhausted` in the subscription notification. - Based on `status`, `currentPeriod` and your own service policy, decide whether to keep providing service, allow a make-up charge window, or downgrade. ## Automatic Retry Mechanism and the PAST_DUE Recovery Action The default automatic retry policy uses an interval and attempt count based on the subscription period: | Period unit | Retry interval | Default max attempts | |:---|:---:|:---:| | `DAY` | 2 hours | 1 | | `WEEK` | 24 hours | 7 | | `MONTH` | 48 hours | 7 | | `YEAR` | 72 hours | 7 | ### PAST_DUE recovery checkout (action) When a renewal charge fails and the subscription enters `PAST_DUE`, the subscription notification (`SUBSCRIPTION_PAST_DUE`) carries an `action` object for guiding the user back to the PingPong checkout to retry the current period payment: ```json "action": { "redirectUrl": "https://sandbox-safepay.pingpongx.com?token=...", "actionExpiredAt": 1792200000 } ``` - `redirectUrl`: the recovery checkout URL. Merchants can redirect the user to it, or deliver it via in-app messages or email so the user can retry the current bill. - `actionExpiredAt`: the URL expiry (second-level timestamp). Validity = **min(72 hours, remaining automatic retry window)** from generation: effectively about 2 hours for `DAY` subscriptions and up to 72 hours for `WEEK` / `MONTH` / `YEAR`. - Once the automatic retry window is exhausted, `action` is no longer generated (the notification does not carry it), earlier links stop working, and the subscription follows the retries-exhausted flow (`cancelReason=payment_retry_exhausted`). Merchants are advised to deliver `action.redirectUrl` to the user promptly after receiving `SUBSCRIPTION_PAST_DUE` โ€” for `DAY` subscriptions the link is valid for only about 2 hours. It is recommended to evaluate renewal scenarios in two steps: | Look at first | Fields to watch | Typical meaning | Recommended action | |:---|:---|:---|:---| | Subscription level | `status=ACTIVE` | The subscription is in normal fulfillment | Keep providing service | | Subscription level | `status=PAST_DUE` | This period's charge failed; in recovery or grace period | Keep service / downgrade / remind the customer to top up, per your rules | | Subscription level | `status=CANCELLED` + `cancelReason=payment_retry_exhausted` | Automatic retries exhausted; subscription terminated | Stop renewal and service | | Payment level | Current period payment `status=SUCCESS` | This period was actually charged | Book and reconcile normally | | Payment level | Current period payment failed or has no success record | This period's money has not been collected | Enter dunning, grace or suspension flow based on the subscription status | Define at least one of the following renewal-failure policies: - Grace period with continued service: keep serving during `PAST_DUE` and remind the customer to top up. - Grace period with downgraded service: keep the account but close premium entitlements. - Immediate suspension: stop the subscription service right after a renewal failure. When a renewal fails and enters the grace period, the subscription notification pushes `notifyType=SUBSCRIPTION_PAST_DUE` (`status=PAST_DUE`); after a successful recovery charge it pushes `SUBSCRIPTION_RECOVERED`. For full notification payload examples, see [Subscription Status & Notifications ยท Notification payload structure](/en/notes/integrate/subscription/lifecycle/#subscription-notification-payload-structure). When you receive `SUBSCRIPTION_PAST_DUE`, it is recommended to first mark the subscription as "pending recovery" or "in grace period", then decide whether to keep serving based on the payment result. ## Querying the Subscription Plan and Payment Records When notifications are delayed, lost, or you need compensation reconciliation, keep a dual perspective โ€” subscription level and payment level โ€” when querying: | Query API | Best at answering | |:---|:---| | [Query Subscription](/en/notes/subscription/api/query/) | Whether the subscription is `ACTIVE`, still in trial, cancelled, and which period it is in | | [Query Subscription Payments](/en/notes/subscription/api/paymentsQuery/) | How much was charged in each period, whether the charge succeeded, which payment method was used, and whether there were refunds |