Scenarios & Best Practices
This page collects common subscription business scenarios and merchant-side implementation recommendations. For the main integration flow, read the Subscription Integration Guide first.
Typical Business Scenarios
Scenario 1: 7-day free trial with automatic conversion
Suitable for membership trials, SaaS new-user trials, etc.
Recommended approach:
- Pass
trial.periodDays=7when creating the subscription;trialonly configures the trial time — no amount or currency — and the regular billing price goes inflatPrice. - When you receive
status=IN_TRIALwithcurrentPeriod=0, activate the trial entitlement immediately. - After the trial ends, PingPong automatically initiates the first formal charge.
- If you later receive
status=ACTIVE, the trial conversion succeeded — keep providing the formal service. - If the user cancels during the trial, PingPong will not initiate the first formal billing charge.
- 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:
- Call Preview Subscription Update first to see whether the upgrade requires a surcharge and its amount.
- If you accept the estimate, call Update Subscription with appropriate settings:
effectiveMode=IMMEDIATEbillingAction=IMMEDIATE_CHARGE_AND_KEEP_CYCLEor another action your business needs
- When you receive the
notifyType=SUBSCRIPTION_PLAN_CHANGEDnotification, update the local plan version and entitlements (usepreviousAttributesto diff the change). - If the related surcharge is
PENDING, wait for the payment or notification final status before confirming the entitlement change. - 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):
{
"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):
{
"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:
- First confirm whether the subscription has a plan change still restricted by the Update gate; even period-end cancellation cannot bypass the Update gate.
- Call Cancel Subscription with
cancelAtPeriodEnd=true. - After Cancel succeeds, record "cancellation scheduled" locally, but do not stop service. The synchronous response usually still shows
status=ACTIVEand returns the futurecancelAt. - Keep providing service under the current status until the current billing period ends.
- Wait for the final
notifyType=SUBSCRIPTION_CANCELLED(status=CANCELLED) notification before stopping renewal and service.
Period-end cancellation request example (showing bizContent only):
{
"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":
{
"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
merchantRefundIdorrefundIdat 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.
- To verify per-period payment details, call Query Subscription Payments.
- 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):
{
"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.
