--- title: Scenarios & Best Practices permalink: /en/notes/integrate/subscription/best-practices/ createTime: '2026/10/21 10:00:00' nosearch: true llm: exclude: true description: 'Subscription free trials, plan upgrades, period-end cancellation, field persistence, notification idempotency and compensation query recommendations.' --- This page collects common subscription business scenarios and merchant-side implementation recommendations. For the main integration flow, read the [Subscription Integration Guide](/en/notes/integrate/subscription/integration/) first. ## Typical Business Scenarios ### Scenario 1: 7-day free trial with automatic conversion Suitable for membership trials, SaaS new-user trials, etc. Recommended approach: 1. Pass `trial.periodDays=7` when creating the subscription; `trial` only configures the trial time — no amount or currency — and the regular billing price goes in `flatPrice`. 2. When you receive `status=IN_TRIAL` with `currentPeriod=0`, activate the trial entitlement immediately. 3. After the trial ends, PingPong automatically initiates the first formal charge. 4. If you later receive `status=ACTIVE`, the trial conversion succeeded — keep providing the formal service. 5. If the user cancels during the trial, PingPong will not initiate the first formal billing charge. 6. If the trial conversion fails and the subscription enters `PAST_DUE`, handle it per your grace-period or recovery-charge rules. ### Scenario 2: Monthly plan upgrade with immediate price difference charge Suitable for upgrading from a basic plan to a premium plan with immediate effect. Recommended approach: 1. Call [Preview Subscription Update](/en/notes/subscription/api/preview/) first to see whether the upgrade requires a surcharge and its amount. 2. If you accept the estimate, call [Update Subscription](/en/notes/subscription/api/update/) with appropriate settings: - `effectiveMode=IMMEDIATE` - `billingAction=IMMEDIATE_CHARGE_AND_KEEP_CYCLE` or another action your business needs 3. When you receive the `notifyType=SUBSCRIPTION_PLAN_CHANGED` notification, update the local plan version and entitlements (use `previousAttributes` to diff the change). 4. If the related surcharge is `PENDING`, wait for the payment or notification final status before confirming the entitlement change. 5. If the subscription was created via checkout and the Update response returns `action.paymentRedirectUrl`, redirect the buyer to that cashier address to complete the surcharge payment. Preview request example (showing `bizContent` only): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "requestId": "REQ_SUB_PREVIEW_202607150001", "flatPrice": { "amount": "29.99", "currency": "USD" }, "period": { "unit": "MONTH", "count": 1 }, "totalPeriodCount": 12, "effectiveMode": "IMMEDIATE", "billingAction": "IMMEDIATE_CHARGE_AND_KEEP_CYCLE", "prorationMode": "PRORATED", "description": "Premium monthly membership" } ``` Update request example (showing `bizContent` only): ```json { "previewQuoteId": "SUPD-2607150312100000000900141522", "merchantSubscriptionId": "SUB_PLAN_202607150001", "requestId": "REQ_SUB_UPDATE_202607150001", "flatPrice": { "amount": "29.99", "currency": "USD" }, "goods": { "name": "Premium membership", "description": "Monthly membership service", "sku": "MEMBERSHIP-001", "unitPrice": "29.99", "number": "1", "imgUrl": "https://merchant.example.com/images/membership.png", "virtualProduct": "Y", "itemType": "3" }, "effectiveMode": "IMMEDIATE", "billingAction": "IMMEDIATE_CHARGE_AND_KEEP_CYCLE", "prorationMode": "PRORATED", "description": "Premium monthly membership" } ``` ### Scenario 3: The user chooses "cancel at the end of this period" Suitable for users who want to turn off auto-renewal but keep using the current paid period. Recommended approach: 1. First confirm whether the subscription has a plan change still restricted by the Update gate; even period-end cancellation cannot bypass the Update gate. 2. Call [Cancel Subscription](/en/notes/subscription/api/cancel/) with `cancelAtPeriodEnd=true`. 3. After Cancel succeeds, record "cancellation scheduled" locally, but do not stop service. The synchronous response usually still shows `status=ACTIVE` and returns the future `cancelAt`. 4. Keep providing service under the current status until the current billing period ends. 5. Wait for the final `notifyType=SUBSCRIPTION_CANCELLED` (`status=CANCELLED`) notification before stopping renewal and service. Period-end cancellation request example (showing `bizContent` only): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "requestId": "REQ_SUB_CANCEL_202607150001", "cancelAtPeriodEnd": true } ``` If the final query or notification returns the following, it usually means "the current period has been fulfilled and the subscription has truly ended": ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "subscriptionId": "SUB-2607140720100000000500111522", "status": "CANCELLED", "cancelReason": "merchant_requested", "cancelAtPeriodEnd": true, "cancelAt": "1785159999000" } ``` ## Implementation Recommendations To make the Subscription integration more robust, merchants should at least do the following: ### 1. Persist key mappings It is recommended to store at least the following fields locally: | Field | Purpose | |:---|:---| | `merchantSubscriptionId` | Merchant-side subscription primary key | | `subscriptionId` | PingPong subscription primary key | | `customerId` | Customer-to-subscription binding (from the Create Customer API) | | `status` | Current subscription status | | `currentPeriod` | Current period number; interpret it together with `status`, `trial` and payment records — never judge the trial state from this field alone | | `flatPrice.amount` / `flatPrice.currency` | Current plan's regular billing amount and currency | | `period.unit` / `period.count` | Single billing cycle configuration | | `totalPeriodCount` | Total number of billing periods; does not include the trial | | `trial` related fields | Identify whether the subscription is still in trial | | `autoRecovery.enabled` | Whether automatic retry is enabled | | Latest `notifyType` / `updateAt` / `requestId` | Idempotency and compensation handling | ### 2. Make notification handling idempotent It is recommended to apply idempotency at least along these dimensions: - Subscription notifications: by `subscriptionId + notifyType + updateAt`, or your own idempotency key. - Payment notifications: by the payment notification's own transaction primary key. - Refund notifications: by `merchantRefundId` or `refundId` at refund level. - Within the same subscription period, keep subscription, payment and refund notifications idempotent separately — do not let them overwrite each other. ### 3. Keep compensation queries as a fallback Even with notifications integrated, keep active query logic: - When no notification arrives for a long time after creating a subscription, call [Query Subscription](/en/notes/subscription/api/query/). - To verify per-period payment details, call [Query Subscription Payments](/en/notes/subscription/api/paymentsQuery/). - After a plan change, verify the result by querying the subscription details against your local plan version. - After an Update or Cancel refund, verify the refund final status via payment records combined with refund notifications. Query subscription response example (showing `bizContent` only): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "subscriptionId": "SUB-b7679cac22864072866fce3bf5ee6ba5", "requestId": "REQ_SUB_QUERY_202607150001", "status": "ACTIVE", "cancelReason": "", "currentPeriod": 1, "startAt": "1782711886000", "notifyUrl": "https://merchant.example.com/notify/subscription", "period": { "unit": "MONTH", "count": 1 }, "totalPeriodCount": 12, "autoRecovery": { "enabled": true }, "paymentRecords": [ { "period": 1, "merchantTransactionId": "SUB-b7679cac22864072866fce3bf5ee6ba5_P1" } ], "flatPrice": { "amount": "9.99", "currency": "USD" }, "goods": { "name": "Premium membership", "description": "Monthly membership service", "sku": "MEMBERSHIP-001", "unitPrice": "9.99", "number": "1", "imgUrl": "https://merchant.example.com/images/membership.png", "virtualProduct": "Y", "itemType": "3" } } ``` ### 4. Base service activation on the subscription status Whether to keep providing service should follow the subscription-level status; single payment and refund results are for finance, reconciliation and exception compensation. For the consumption matrix and idempotency key definitions of the three kinds of results, see [Integration Guide · Step 3: Get subscription and payment results](/en/notes/integrate/subscription/integration/#step-3-get-subscription-and-payment-results).