--- title: Update & Cancel Rules permalink: /en/notes/integrate/subscription/update-cancel/ createTime: '2026/10/21 10:00:00' nosearch: true llm: exclude: true description: 'Explains Subscription plan changes, Update effective modes, fund adjustments, Cancel gates, cancellation effect timing and refund handling rules.' --- This page covers the business rules for plan changes and subscription cancellation. For the main integration flow, read the [Subscription Integration Guide](/en/notes/integrate/subscription/integration/) 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: 1. Call [Preview Subscription Update](/en/notes/subscription/api/preview/) first to estimate the surcharge, refund and effective version brought by this change. 2. Then call [Update Subscription](/en/notes/subscription/api/update/) to formally submit the change. 3. Design the appropriate `effectiveMode`, `billingAction` and `prorationMode` for your business needs. ::: warning 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 supports `PRORATED` and `NONE`; Update additionally supports `CUSTOM` (merchant-defined amount and direction — requires `customAmount`/`customChargeDirection`/`customCurrency` together). - `cancelAtPeriodEnd` in 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. Only `false` (revoke the schedule) is currently supported — creating a period-end cancellation by passing `true` through 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 | ::: warning 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](/en/notes/subscription/api/query/) 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: - `preview` is only an estimate, not the final execution result. - A synchronous `resultCode=910000` from `update` only 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. - `chargeResult` only describes the fund action of this change, not whether the subscription change task is still processing. Update subscription response example (showing `bizContent` only): ```json { "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 were `PENDING`, 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: ```json { "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: 1. When `action.type=PAYMENT_REDIRECT_URL`, redirect the buyer to `action.paymentRedirectUrl` (or open it embedded via `jsSdkUrl`) to complete the surcharge payment on the checkout page — the same way the first payment was launched. 2. Treat the payment / subscription notification as the final surcharge result; do not activate the upgraded entitlements before a success notification arrives. 3. An empty `action` object means no buyer follow-up is needed — handle the result directly per `chargeResult`. If this Update may produce a refund, pass `refundNotifyUrl` in the Update request: ```json { "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: 1. The Update synchronous response confirms the plan change result with `resultCode=910000`. 2. When `chargeDirection=REFUND` and `chargeResult=PENDING`, wait for the asynchronous refund processing. 3. Use [Query Subscription](/en/notes/subscription/api/query/) to get `refundRecords[].merchantRefundId` and the associated original payment order information. 4. Use [Query Subscription Payments](/en/notes/subscription/api/paymentsQuery/) 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. ::: warning 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: - `cancelAtPeriodEnd` only decides when a successful Cancel takes effect; it cannot bypass the Update gate. - `chargeResult=PENDING` only 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) or `910008` (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](/en/notes/subscription/api/cancel/) 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 by `prorationMode`. - 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` | ::: warning 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): ```json { "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: ```json { "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: ```json { "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](/en/notes/subscription/api/paymentsQuery/). `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: 1. Record the cancellation action and mode in your own system first. 2. After calling the Cancel API, use the [Subscription Notification](/en/notes/notify/subscription/notify/) or [Query Subscription](/en/notes/subscription/api/query/) as the final confirmation. 3. When `cancelAtPeriodEnd=true`, keep fulfilling under the current subscription status until the period ends. 4. 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: 1. Receive the [Subscription Notification](/en/notes/notify/subscription/notify/); 2. Update the local subscription status based on `status` and `cancelReason`; 3. When receiving `status=CANCELLED` with `cancelReason=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](/en/notes/integrate/subscription/lifecycle/#subscription-notification-event-types).