Update & Cancel Rules
This page covers the business rules for plan changes and subscription cancellation. For the main integration flow, read the Subscription Integration Guide first.
Previewing and Executing a Plan Change
To upgrade/downgrade a plan, change the amount, adjust the cycle or modify goods information, follow this order:
- Call Preview Subscription Update first to estimate the surcharge, refund and effective version brought by this change.
- Then call Update Subscription to formally submit the change.
- Design the appropriate
effectiveMode,billingActionandprorationModefor your business needs.
Required fields in an Update request (gateway-enforced)
The following five fields are required in an Update request; missing any of them returns a 102000 parameter error:
description(subscription plan description)redirectUrl(redirect address when the change involves cashier/3DS interaction)effectiveMode(effective mode)billingAction(billing action)prorationMode(proration mode)
Understand these three capabilities:
effectiveMode: decides whether the change takes effect immediately or at the next cycle.billingAction: decides when the fund action happens, and whether the existing billing anchor is kept or reset.prorationMode: Preview supportsPRORATEDandNONE; Update additionally supportsCUSTOM(merchant-defined amount and direction — requirescustomAmount/customChargeDirection/customCurrencytogether).cancelAtPeriodEndin an Update request is not used to initiate a cancellation; it is used to revoke a period-end cancellation previously scheduled via the Cancel API. Onlyfalse(revoke the schedule) is currently supported — creating a period-end cancellation by passingtruethrough Update is not supported.
Currently supported combinations are listed below; combinations not listed are not supported:
| Change content | effectiveMode | billingAction | Result |
|---|---|---|---|
| Amount only | IMMEDIATE | IMMEDIATE_CHARGE_AND_RESET_CYCLE | ✅ Success; prorated surcharge/refund immediately |
| Amount only | IMMEDIATE | IMMEDIATE_CHARGE_AND_KEEP_CYCLE | ⚠️ May occasionally return 500 in sandbox (fix in progress; see handling notes below) |
| Amount only | NEXT_CYCLE | NEXT_CYCLE_CHARGE_KEEP_CYCLE | ✅ Success; returns chargeResult=NOT_REQUIRED, executed at next cycle |
startAt, charge day or cycle anchor | IMMEDIATE | IMMEDIATE_CHARGE_AND_RESET_CYCLE | ✅ Success (anchor reset to the current time) |
startAt, charge day or cycle anchor | IMMEDIATE | IMMEDIATE_CHARGE_AND_KEEP_CYCLE | Not supported |
startAt, charge day or cycle anchor | NEXT_CYCLE | NEXT_CYCLE_CHARGE_KEEP_CYCLE | Not supported |
Handling a 500 with the KEEP_CYCLE combination
In the sandbox environment, an Update with the IMMEDIATE + KEEP_CYCLE combination may occasionally return a synchronous 500; a fix is in progress. If you receive a 500, do not retry immediately with a new request: first call Query Subscription to confirm the current subscription status; once you confirm the change did not take effect, retry with the original request (same requestId). For immediate-charge changes, you can also prefer the IMMEDIATE + RESET_CYCLE combination to avoid this path.
Beyond the request parameters, it is recommended to split the update result into two layers — "did the plan change succeed" and "did a fund movement actually happen":
| Layer | Key fields | How to interpret |
|---|---|---|
| Subscription level | resultCode, status, effectivePlanVersion | resultCode=910000 means the change is accepted/executed; status is the current subscription status; effectivePlanVersion is the plan version after the change |
| Payment level | chargeResult, chargeAmount, chargeCurrency, chargeDirection | Whether this upgrade/downgrade produced a surcharge or refund, and whether that fund action has completed |
Common Update results can be consumed with this matrix:
| Scenario | resultCode | chargeResult | How to handle |
|---|---|---|---|
| Surcharge needed and succeeded | 910000 | SUCCEEDED | Record the plan change as successful; activate or adjust entitlements per the payment result |
| Surcharge needed but failed | 910000 | FAILED | Do not activate upgraded entitlements directly; prompt the user to pay again or re-initiate the change |
| No fund action needed | 910000 | NOT_REQUIRED | Record the plan change as successful; no need to wait for payment or refund finality |
| Refund needed, processing | 910000 | PENDING | The plan change succeeded, but the refund still needs confirmation via refund notification or query |
| Refund needed and succeeded | 910000 | SUCCEEDED | Record the plan change as successful and complete refund reconciliation |
| Refund needed but failed | 910000 | FAILED | The plan change is not rolled back automatically on refund failure; handle the refund failure as a separate refund exception |
Note in particular:
previewis only an estimate, not the final execution result.- A synchronous
resultCode=910000fromupdateonly means the plan change request was accepted or executed — it does not mean the fund action has reached its final state. - If
chargeResult=PENDING, the surcharge or refund involved in this update is still processing; do not complete the final financial confirmation from this synchronous response alone. chargeResultonly describes the fund action of this change, not whether the subscription change task is still processing.
Update subscription response example (showing bizContent only):
{
"previewQuoteId": "SUPD-2607150336100000001000141522",
"requestId": "REQ_SUB_UPDATE_202607150001",
"subscriptionId": "SUB-2607140846100000000900111522",
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"status": "ACTIVE",
"effectiveMode": "IMMEDIATE",
"billingAction": "IMMEDIATE_CHARGE_AND_RESET_CYCLE",
"prorationMode": "PRORATED",
"chargeDirection": "CHARGE",
"chargeAmount": "5.32",
"chargeCurrency": "USD",
"chargeResult": "SUCCEEDED",
"effectivePlanVersion": 2,
"resultCode": "910000",
"resultMessage": "success",
"period": {
"unit": "MONTH",
"count": 1
},
"totalPeriodCount": 12,
"flatPrice": {
"amount": "15.00",
"currency": "USD"
},
"notifyUrl": "https://merchant.example.com/notify/subscription",
"startAt": "1792152613237",
"endAt": "1823688613237",
"updatedAt": "1792152608933",
"currentPeriod": 1,
"cancelAtPeriodEnd": false,
"proratedCurrency": "USD",
"action": {
"type": "PAYMENT_REDIRECT_URL",
"paymentRedirectUrl": "https://sandbox-safepay.pingpongx.com?token=...",
"jsSdkUrl": "https://payssr-cdn.pingpongx.com/.../pp-checkout.js?token=..."
}
}Consume this result as follows:
- Subscription level: record that the change was accepted together with
effectivePlanVersion; when a paid upgrade involves entitlement activation, still combine it with notifications and fund finality. - Payment level: since
chargeResult=SUCCEEDED, the surcharge is complete; if it werePENDING, you would keep waiting for the payment notification, subscription notification or a later query result before the final refund/surcharge confirmation.
Cashier-created subscriptions: redirect to complete the surcharge
For subscriptions created via a checkout session, if the surcharge produced by an Update requires the buyer to complete a payment action, the response returns an action object:
{
"action": {
"type": "PAYMENT_REDIRECT_URL",
"paymentRedirectUrl": "https://sandbox-safepay.pingpongx.com?token=...",
"jsSdkUrl": "https://payssr-cdn.pingpongx.com/.../pp-checkout.js?token=..."
}
}Recommended merchant handling:
- When
action.type=PAYMENT_REDIRECT_URL, redirect the buyer toaction.paymentRedirectUrl(or open it embedded viajsSdkUrl) to complete the surcharge payment on the checkout page — the same way the first payment was launched. - Treat the payment / subscription notification as the final surcharge result; do not activate the upgraded entitlements before a success notification arrives.
- An empty
actionobject means no buyer follow-up is needed — handle the result directly perchargeResult.
If this Update may produce a refund, pass refundNotifyUrl in the Update request:
{
"previewQuoteId": "SUPD-2607150336100000001000141522",
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"requestId": "REQ_SUB_UPDATE_REFUND_202607150001",
"description": "Downgrade to basic plan",
"redirectUrl": "https://merchant.example.com/subscription/result",
"flatPrice": {
"amount": "5.00",
"currency": "USD"
},
"goods": {
"name": "Membership",
"description": "Monthly membership service",
"sku": "MEMBERSHIP-001",
"unitPrice": "5.00",
"number": "1",
"imgUrl": "https://merchant.example.com/images/membership.png",
"virtualProduct": "Y",
"itemType": "3"
},
"effectiveMode": "IMMEDIATE",
"billingAction": "IMMEDIATE_CHARGE_AND_RESET_CYCLE",
"prorationMode": "PRORATED",
"refundNotifyUrl": "https://merchant.example.com/notify/refund"
}It is recommended to confirm an Update refund through this chain:
- The Update synchronous response confirms the plan change result with
resultCode=910000. - When
chargeDirection=REFUNDandchargeResult=PENDING, wait for the asynchronous refund processing. - Use Query Subscription to get
refundRecords[].merchantRefundIdand the associated original payment order information. - Use Query Subscription Payments or the refund notification to confirm the amount, currency and final refund status.
Note that both interfaces use refundNotifyUrl to receive the asynchronous refund result.
requestId compatibility
Per the interface contract, the requestId in an Update response corresponds to this Update request. To confirm whether a change took effect, do not rely on the response requestId alone — combine the outer business code, resultCode, previewQuoteId, subscription notifications and query results.
The Relationship Between Update and Cancel
Whether Cancel can execute depends not only on cancelAtPeriodEnd, but also on whether there is an unfinished change task on the plan. When judging: first determine "whether Cancel is allowed", then decide immediate vs period-end cancellation by cancelAtPeriodEnd, and finally handle the refund per prorationMode.
Both effectiveMode=IMMEDIATE and effectiveMode=NEXT_CYCLE follow the Cancel gate below — you cannot infer that Cancel is always allowed just because an Update is immediate or next-cycle.
| Subscription status | In-flight change task? | Cancel allowed? | Error code | Notes |
|---|---|---|---|---|
ACTIVE | None | Allowed | — | Normal cancellation (immediate or period-end) |
ACTIVE | Yes (in-flight update task) | Blocked | 910008 | "subscription has in-flight update task" — wait for the change task to complete before cancelling |
Not ACTIVE (e.g. PENDING) | — | Blocked | 910005 | "only active subscription supports update" — changes/cancellations are not allowed before the first payment completes |
The prorationMode Relationship Between Update and Cancel
The following rules apply only after passing the Cancel gate above. Update and Cancel each use their own prorationMode to control the fund adjustment of their own request: Cancel does not inherit or reuse Update's prorationMode, amount or direction — it calculates independently at the cancellation moment.
prorationMode | Meaning in Update | Meaning in Cancel (immediate) |
|---|---|---|
NONE | No residual-value calculation for the unused period; no fund adjustment for this change | No refund (when Cancel omits prorationMode, NONE applies) |
PRORATED | Prorated surcharge or refund by remaining period; result in chargeDirection / chargeAmount / chargeResult | Refund recalculated by remaining period at the cancellation moment; Update's chargeAmount is not reused |
CUSTOM | Use customAmount + customChargeDirection to define this adjustment's amount and direction | Use customRefundAmount + customCurrency to specify the refund amount |
Period-end cancellation (cancelAtPeriodEnd=true) produces no refund action, and prorationMode does not take effect.
Note in particular:
cancelAtPeriodEndonly decides when a successful Cancel takes effect; it cannot bypass the Update gate.chargeResult=PENDINGonly means the fund action is processing; it cannot alone prove the change task's state — the Cancel gate is governed by the change task state.- Gate failures currently return
910005(operation not allowed in non-ACTIVE status) or910008(an in-flight change task exists); do not retry these errors at high frequency.
Cancelling a Subscription
Cancelling a subscription and refunding are two independent business outcomes:
- Cancel changes whether the subscription plan keeps renewing and when it stops;
- A refund targets a payment sub-order of a specific period — there is no "refund the subscription master order";
- A standalone refund does not automatically terminate the subscription. If the merchant also needs to stop future renewals, Cancel must be completed as well;
- The Cancel API can currently trigger an associated refund on immediate cancellation via
prorationMode, but that refund is still a fund action at the payment sub-order level and its finality must be confirmed independently.
Therefore, a successful Cancel response only means the cancellation request was executed or scheduled — not that any related refund has completed.
Merchant-Side Cancellation
Merchants can call Cancel Subscription to terminate a subscription proactively.
Common handling:
- Immediate cancellation: pass
cancelAtPeriodEnd=false; the subscription terminates immediately after the request succeeds; whether a refund happens is decided byprorationMode. - Period-end cancellation: pass
cancelAtPeriodEnd=true; service continues within the current period and the subscription is cancelled automatically when the current billing period ends, usually without an immediate refund.
The following cancellation scenarios need special handling:
| Subscription scenario | Cancel result | Subsequent charges / retries |
|---|---|---|
| Cancel during trial | Effective immediately by default | The first formal period charge is not initiated |
Cancel during PAST_DUE or recovery | Subscription transitions to CANCELLED | Automatic retries stop |
| Period-end cancellation of a healthy subscription | Transitions to CANCELLED when the current period ends | Service continues until the period ends; no new charge is generated after the end |
| Fixed term ends naturally | Transitions to CANCELLED after the last period, with cancelReason=plan_ended | No next-period charge is generated |
| cancelAtPeriodEnd | prorationMode | Cancellation result | Refund behavior |
|---|---|---|---|
true | Not passed (field omitted entirely) | Cancelled when the current period ends | No immediate refund; service continues until the period ends |
false | Not passed or NONE | Immediate cancellation | No prorated refund for the remaining period |
false | PRORATED | Immediate cancellation | The system calculates a refund by the remaining value of the current period |
false | CUSTOM | Immediate cancellation | Refund of the specified amount using customRefundAmount and customCurrency |
No refund fields for period-end cancellation
prorationMode, customRefundAmount, customCurrency and refundNotifyUrl are only for immediate cancellation (cancelAtPeriodEnd=false). For period-end cancellation (cancelAtPeriodEnd=true), all four fields must be omitted from the request body; passing them is rejected (102000).
A correct period-end cancellation request body contains only merchantSubscriptionId, requestId, cancelAtPeriodEnd (optionally subscriptionId) — no refund-related fields.
Correct period-end cancellation request example (note: no prorationMode field):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"requestId": "REQ_SUB_CANCEL_EOP_202607150001",
"cancelAtPeriodEnd": true
}For immediate Cancel, a missing prorationMode defaults to NONE — no prorated refund for the remaining period; to have the system calculate a refund, pass PRORATED explicitly. When an immediate cancellation may produce a refund, pass refundNotifyUrl to receive the asynchronous refund result for this Cancel:
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"requestId": "REQ_SUB_CANCEL_NOW_202607150001",
"cancelAtPeriodEnd": false,
"prorationMode": "PRORATED",
"refundNotifyUrl": "https://merchant.example.com/notify/refund"
}CUSTOM immediate cancellation example:
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"requestId": "REQ_SUB_CANCEL_CUSTOM_202607150001",
"cancelAtPeriodEnd": false,
"prorationMode": "CUSTOM",
"customRefundAmount": "1.00",
"customCurrency": "USD",
"refundNotifyUrl": "https://merchant.example.com/notify/refund"
}The final result of a Cancel refund should be confirmed via the refund notification or Query Subscription Payments. refundRecords in the subscription query can provide the merchantRefundId and the associated original payment order information, but its current content is not sufficient to confirm the refund amount and finality alone. The completion of a refund itself does not change the already-determined cancellation mode.
Merchant-side cancellation recommendations:
- Record the cancellation action and mode in your own system first.
- After calling the Cancel API, use the Subscription Notification or Query Subscription as the final confirmation.
- When
cancelAtPeriodEnd=true, keep fulfilling under the current subscription status until the period ends. - If the subscription has an unfinished change, first confirm the Cancel gate per "The Relationship Between Update and Cancel" (
910005/910008).
Buyer / Payment-Method-Side Authorization Cancellation
For payment methods that support buyer-side authorization cancellation or auto-renewal closure, the buyer may stop future charge authorization directly on the payment method or wallet side.
In such cases, merchants should:
- Receive the Subscription Notification;
- Update the local subscription status based on
statusandcancelReason; - When receiving
status=CANCELLEDwithcancelReason=user_requested, stop future auto-renewal and handle the membership or service status per your business rules.
For the meaning of each cancelReason value and per-scenario recommended actions, see Subscription Status & Notifications · Notification event types.
