--- title: Overview permalink: /en/notes/integrate/subscription/ createTime: '2026/10/21 10:00:00' nosearch: true llm: exclude: true description: 'Introduces what Subscription is, its applicable scenarios, and how to choose between Subscription, Recurring and CodeGrant.' --- `Subscription` is the plan-based subscription capability provided by PingPongCheckout. It applies to goods or services with a fixed amount and a fixed billing cycle, such as membership auto-renewal, SaaS monthly/annual plans, trial-to-paid conversion, content subscriptions, periodic shipping or periodic entitlement delivery. Unlike [Recurring](/en/notes/integrate/recurring/overview/) for card payments, Subscription maintains the subscription plan, billing cycle, trial, automatic retries and subscription status on the PingPong side, and synchronizes lifecycle changes to the merchant via subscription notifications. If you only need to save a card and initiate subsequent MIT charges in card payment scenarios, see [Recurring](/en/notes/integrate/recurring/overview/); if you need authorization binding for wallets or local payment methods, see [CodeGrant](/en/notes/integrate/tokenization/codeGrant/). ## When to Use Subscription If your business matches any of the following, Subscription is usually the better fit: - A clear billing cycle, such as monthly, yearly or every fixed number of days. - You want PingPong to maintain the subscription status, such as `PENDING`, `IN_TRIAL`, `ACTIVE`, `PAST_DUE`, `CANCELLED`. - You need trial periods, trial-to-paid conversion, and automatic retries after renewal failure. - You need plan upgrades, downgrades and cycle adjustments, with Preview / Update capabilities to estimate additional charges or refunds. - You want lifecycle changes pushed continuously via subscription notifications, rather than only handling single-payment results. If you only need to "store payment credentials or an authorization relationship and decide when to charge by yourself", you usually do not need Subscription: evaluate Recurring for card MIT scenarios, and CodeGrant for wallet or local payment authorization binding scenarios. ## Choosing Between Subscription / Recurring / CodeGrant | Option | Suitable scenarios | Who maintains the billing plan | Maintains subscription status | Trial / auto-retry support | Recommended reading | |:---|:---|:---|:---:|:---:|:---| | `Subscription` | Standard memberships, SaaS plans, fixed-cycle renewal, trial conversion, plan upgrades/downgrades | PingPong + merchant together | Yes | Yes | [Integration Guide](/en/notes/integrate/subscription/integration/) | | `Recurring` | After saving a card, the merchant decides when to initiate subsequent MIT charges | Merchant | No | No | [Recurring](/en/notes/integrate/recurring/overview/) | | `CodeGrant` | Authorize-then-pay for wallets or local payment methods, keeping the authorization relationship and payment credentials | Merchant | No | No | [CodeGrant](/en/notes/integrate/tokenization/codeGrant/) | One sentence for each: - `Subscription`: PingPong maintains the "subscription plan and lifecycle" for you. - `Recurring`: for "subsequent MIT charges" after saving a card; the billing plan is maintained by the merchant. - `CodeGrant`: for "authorization binding" of wallets or local payment methods; how the authorization is used afterwards is maintained by the merchant. ## Quick Decision | Your question | Recommended option | |:---|:---| | I need fixed-cycle auto-renewal and want the platform to maintain subscription status | `Subscription` | | I need a 7-day trial with automatic conversion and charge at the end | `Subscription` | | I need automatic retries after renewal failure plus subscription status notifications | `Subscription` | | I only need to save a card; my own system decides when to initiate MIT charges | `Recurring` | | I mainly do authorization binding on the wallet or local payment side, then get a token / authorization credential | `CodeGrant` | | I am not sure whether I need a full subscription lifecycle; I just want to store payment credentials first | Evaluate `Recurring` for cards, `CodeGrant` for wallets or local payment methods โ€” do not equate credential storage with subscription capability | ## Checkout or API Only After choosing Subscription, you also need to choose how the subscription is created: - Checkout: PingPong hosts the first payment page, 3DS challenges and wallet redirects โ€” better for teams that want to go live quickly. - `API Only`: the merchant builds its own payment page and submits payment elements directly โ€” better for teams that need full control over the payment experience and already have the corresponding compliance and risk-control capabilities. For integration differences, API choices and the first-payment flow, continue with [Integration Guide](/en/notes/integrate/subscription/integration/#recommended-integration-mode). ## The Core Outcomes of Subscription Integration In Subscription scenarios you usually need to understand three kinds of results at the same time: the subscription result (whether the subscription is active / in trial / past due / cancelled), the payment result (whether the first or each period's charge succeeded), and the refund result (whether refunds triggered by Update or Cancel completed). Whether service should continue should primarily follow the subscription-level status; single payment and refund results are for finance, reconciliation and exception compensation. For how to obtain each kind of result, which fields to watch, and idempotency recommendations, see [Integration Guide ยท Get subscription and payment results](/en/notes/integrate/subscription/integration/#step-3-get-subscription-and-payment-results). ## Next Steps | Page | Questions it answers | |:---|:---| | [Integration Guide](/en/notes/integrate/subscription/integration/) | How to create a subscription, complete the first payment, handle notifications, query status, and enter renewal and plan-change flows | | [Subscription Status & Notifications](/en/notes/integrate/subscription/lifecycle/) | How to understand subscription status, `currentPeriod`, `cancelReason`, and the relationship between subscription, payment and refund notifications | | [Update & Cancel Rules](/en/notes/integrate/subscription/update-cancel/) | Plan changes, immediate vs next-cycle effect, Cancel gates, refunds and `prorationMode` | | [Renewal & Auto-Recovery](/en/notes/integrate/subscription/renewal-recovery/) | Renewal failure, `PAST_DUE`, automatic retries, recovery charges and payment record queries | | [Invoice Reconciliation](/en/notes/integrate/subscription/invoice-reconciliation/) | Invoice/receipt generation rhythm, how to obtain `invoiceId` and `receiptId`, query/download APIs and invoice webhook events | | [Scenarios & Best Practices](/en/notes/integrate/subscription/best-practices/) | Free trials, plan upgrades, period-end cancellation, local field mapping, idempotency and compensation query recommendations |