--- 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 |