---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/subscription/api/update/index.md
description: >-
  The Update Subscription API submits a subscription plan change, supporting
  updates to amount, billing cycle, goods information and billing strategy, and
  returns the change result plus any follow-up payment action.
---
# Update Subscription

```apidef
endpoint: POST /v4/subscriptions/update
name: Update Subscription
summary: Submit a subscription plan change
tags: Subscription, Update
```

The Update Subscription API submits a subscription plan change, supporting updates to amount, billing cycle, goods information and billing strategy, and returns the change result plus any follow-up payment action.

## Request Parameters

| Parameter | Type | Required | Description |
|--------|------|------|------|
| accId | string | M | Unique identifier for the store, which will appear in the response message after creation; inputting it means modifying the data |
| clientId | string | M | PingPong Merchant ID |
| signType | string | M | Supports MD5 , SHA256; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document |
| sign | string | M | Signature; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document. All parameters participate in the signature |
| version | string | M | Version number, currently fixed at 1.0, may be adjusted with changes to the interface in the future |
| bizContent | string | M | Collection of request parameters, with no limit on maximum length. Except for common request parameters, all other request parameters must be passed within this parameter, format: JSON string |
| └─ previewQuoteId | string | O | Preview quote ID returned by the preview API. Note: when using the quote path, the requestId in subsequent subscription change notifications is attributed to the Preview request instead of this Update request (known issue). |
| └─ merchantSubscriptionId | string | C | Merchant-defined unique subscription plan ID. At least one of this field or subscriptionId is required. |
| └─ subscriptionId | string | C | PingPong subscription ID. At least one of this field or merchantSubscriptionId is required. |
| └─ requestId | string | M | Unique merchant request ID. |
| └─ flatPrice | object | O | Updated recurring amount and currency for each formal billing cycle. |
| └─ └─ amount | string | O | Updated recurring amount for each billing cycle. |
| └─ └─ currency | string | O | Updated recurring billing currency. |
| └─ period | object | O | Updated subscription billing cycle. |
| └─ └─ count | integer | M | Number of units in one formal billing cycle. Must be at least 1 . For example, unit = MONTH and count = 1 means monthly billing. This is not the total number of billing cycles. |
| └─ └─ unit | string | M | Subscription period unit type. Valid values include: YEAR : the subscription cycle is measured in years.; MONTH : the subscription cycle is measured in months.; WEEK : the subscription cycle is measured in weeks.; DAY : the subscription cycle is measured in days.; |
| └─ totalPeriodCount | integer | O | Total number of formal billing cycles in the subscription plan. Must be at least 1 and excludes the trial period. If omitted, the number of formal billing cycles is unlimited. |
| └─ discount | object | O | Subscription discount change. Omit: keep the current discount unchanged.; Pass null : remove the current discount.; Pass an object: replace the current discount configuration.; The discount applies only to future formal billing cycles, not to the trial period or completed cycles. |
| └─ └─ type | string | M | Discount type. Valid values: fixedAmount : fixed-amount discount.; percentage : percentage discount.; |
| └─ └─ amountOff | string | C | Fixed discount amount. Provide only when type is fixedAmount; mutually exclusive with percentOff . |
| └─ └─ percentOff | string | C | Percentage discount value. Provide only when type is percentage; mutually exclusive with amountOff . |
| └─ └─ durationCount | string | M | Number of formal billing cycles for which the discount applies, excluding the trial period. |
| └─ startAt | string | O | Updated subscription start time as a 10-digit second-level timestamp string. |
| └─ endAt | string | O | Updated subscription end time as a 10-digit second-level timestamp string. |
| └─ cancelAtPeriodEnd | boolean | O | Used to revoke a scheduled period-end cancellation. If a subscription has already been scheduled for period-end cancellation through the Cancel API, pass false to cancel that schedule and keep the subscription active under the current plan. This field is not used to initiate cancellation; use the Cancel API for immediate or period-end cancellation. Setting this field to true through Update is currently not supported. |
| └─ description | string | M | Updated subscription description. (Mandatory per gateway validation.) |
| └─ goods | object | O | Updated goods information. Can be omitted when the change does not alter goods, e.g. merely revoking a scheduled period-end cancellation (cancelAtPeriodEnd=false). |
| └─ └─ name | string | M | Product name. |
| └─ └─ description | string | O | Product description. |
| └─ └─ sku | string | O | Product number, product SKU. |
| └─ └─ unitPrice | string | M | Unit price of the product. Note: the sum of unitPrice × number must equal flatPrice.amount , otherwise 301012 is returned. |
| └─ └─ unitTaxAmount | string | C | Tax per item, mandatory when the total order amount includes tax. |
| └─ └─ taxRate | string | O | Tax rate. |
| └─ └─ totalDiscountAmount | string | C | Total discount amount per item, mandatory when the total order amount involves discounts. |
| └─ └─ number | string | M | Quantity of the product purchased. |
| └─ └─ imgUrl | string | M | Main image link of the product. |
| └─ └─ virtualProduct | string | O | Whether it is a virtual product, virtual goods ( Y / N ). |
| └─ └─ itemType | string | O | Product type, enumerated values: 1 / 2 / 3 , corresponding meanings are as follows: 1 DIGITAL: Digital products; 2 PHYSICAL: Physical products; 3 SERVICE: Services; |
| └─ effectiveMode | string | M | Effective mode of the subscription change. Defaults to IMMEDIATE if not provided. If NEXT_CYCLE is specified, another update is not allowed before the change takes effect in the next billing cycle. Valid values include: IMMEDIATE : the subscription change takes effect immediately.; NEXT_CYCLE : the subscription change takes effect at the beginning of the next billing cycle.; |
| └─ billingAction | string | M | Billing action. Valid values include: IMMEDIATE_CHARGE_AND_KEEP_CYCLE : charge or refund immediately and keep the current billing anchor, frequency, and schedule.; IMMEDIATE_CHARGE_AND_RESET_CYCLE : charge or refund immediately and reset the billing anchor to the current time, allowing the billing frequency to change.; NEXT_CYCLE_CHARGE_KEEP_CYCLE : charge or refund on the next billing date while keeping the current billing frequency and schedule.; |
| └─ prorationMode | string | M | Proration mode. Defaults to PRORATED if not provided. Valid values include: PRORATED : considers the residual value of the unused service time and calculates any extra charge or refund based on the remaining time.; NONE : does not consider the residual value of the unused service time.; CUSTOM : the merchant defines the proration adjustment amount and direction for this change instead of letting the system calculate the price difference based on the remaining cycle automatically.; |
| └─ customAmount | string | C | Custom amount passed when prorationMode is CUSTOM . |
| └─ customChargeDirection | string | C | Amount direction passed when prorationMode is CUSTOM , used to indicate whether the change requires a charge or a refund. Example: REFUND . |
| └─ customCurrency | string | C | Required when prorationMode is CUSTOM : the currency of the custom amount (ISO 4217). customAmount , customChargeDirection and customCurrency are all mandatory in CUSTOM mode, otherwise 910001 is returned. |
| └─ expiresAt | string | O | Expiration time for the payment related to this update. The user must complete the payment before this time to support the plan change. |
| └─ redirectUrl | string | M | Redirect URL back to the merchant after checkout/3DS interaction completes during the update, typically the merchant's payment or subscription result page. (Mandatory per gateway validation.) |
| └─ refundNotifyUrl | string | O | Merchant-defined asynchronous notification URL for refund results.
URL recommendation: use a complete URL with a publicly reachable domain name. Standard web ports are recommended (HTTPS defaults to 443 and HTTP defaults to 80). Ensure the URL can reliably receive PingPongCheckout asynchronous notifications. |
| └─ remark | string | O | Merchant extension field. |

### Request Example

```json
{
  "clientId": "2023121216311410287",
  "accId": "2023121216311410287522",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": "{\"merchantSubscriptionId\":\"autocaseSubMerId_178401881002391785\",\"requestId\":\"AUTO988778009\",\"billingAction\":\"IMMEDIATE_CHARGE_AND_KEEP_CYCLE\",\"effectiveMode\":\"IMMEDIATE\",\"flatPrice\":{\"amount\":\"60.00\",\"currency\":\"USD\"},\"description\":\"qa update template description\",\"goods\":{\"name\":\"Membership\",\"description\":\"Monthly membership\",\"sku\":\"SKU_SUB_001\",\"unitPrice\":\"60.00\",\"number\":\"1\",\"imgUrl\":\"https://merchant.example.com/goods/sub.png\",\"virtualProduct\":\"Y\",\"itemType\":\"3\"},\"period\":{\"count\":1,\"unit\":\"MONTH\"},\"totalPeriodCount\":12,\"discount\":{\"type\":\"fixedAmount\",\"amountOff\":\"5.00\",\"durationCount\":\"3\"},\"prorationMode\":\"CUSTOM\",\"customAmount\":\"58.06\",\"customChargeDirection\":\"REFUND\",\"customCurrency\":\"USD\"}"
}
```

## Response Parameters

| Parameter | Type | Description |
|--------|------|------|
| accId | string | Unique store identifier, which will appear in the response message after being added; inputting it means modifying the data |
| clientId | string | PingPong merchant number |
| signType | string | Supports MD5 , SHA256; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document |
| sign | string | Signature; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document. All parameters participate in the signature |
| code | string | Result status code, see the appendix Status Code Table: /en/notes/appendix/successCodeList/ |
| description | string | Result description |
| bizContent | string | Business response parameters |
| └─ period | object | Updated subscription billing cycle. |
| └─ └─ count | integer | Number of units in one formal billing cycle. Must be at least 1 . For example, unit = MONTH and count = 1 means monthly billing. This is not the total number of billing cycles. |
| └─ └─ unit | string | Subscription period unit type. Valid values include: YEAR : the subscription cycle is measured in years.; MONTH : the subscription cycle is measured in months.; WEEK : the subscription cycle is measured in weeks.; DAY : the subscription cycle is measured in days.; |
| └─ totalPeriodCount | integer | Total number of formal billing cycles in the subscription plan. Must be at least 1 and excludes the trial period. If omitted, the number of formal billing cycles is unlimited. |
| └─ flatPrice | object | Updated recurring amount and currency for each formal billing cycle. |
| └─ └─ amount | string | Actual recurring amount for each formal billing cycle of the subscription plan. |
| └─ └─ currency | string | Billing currency for formal subscription cycles, as a 3-letter ISO 4217 currency code. |
| └─ discount | object | Current effective subscription discount configuration after the update. Not returned when no discount is configured. |
| └─ └─ type | string | Discount type. Valid values: fixedAmount : fixed-amount discount.; percentage : percentage discount.; |
| └─ └─ amountOff | string | Fixed discount amount. Provide only when type is fixedAmount; mutually exclusive with percentOff . |
| └─ └─ percentOff | string | Percentage discount value. Provide only when type is percentage; mutually exclusive with amountOff . |
| └─ └─ durationCount | string | Number of formal billing cycles for which the discount applies, excluding the trial period. |
| └─ previewQuoteId | string | Preview quote ID associated with this subscription update. |
| └─ requestId | string | Unique merchant request ID. |
| └─ subscriptionId | string | PingPong subscription ID. |
| └─ merchantSubscriptionId | string | Merchant-defined unique subscription plan ID. |
| └─ status | string | Subscription plan status. Valid values include: PENDING : the subscription has been created but is not yet active.; IN_TRIAL : the subscription is in the trial period and service is available, but the first formal charge has not completed yet.; ACTIVE : the subscription is currently active and the user is entitled to the service.; PAST_DUE : the subscription reached its charge time but the current charge failed, entering the dunning or retry stage.; CANCELLED : the subscription has ended and will not renew automatically.; |
| └─ chargeResult | string | Processing result of the charge or refund caused by this update. Valid values include: SUCCEEDED; FAILED; NOT_REQUIRED; PENDING; |
| └─ chargeAmount | string | Charge or refund amount involved in the change, returned as a positive number only. |
| └─ chargeCurrency | string | Currency of the charge or refund involved in the change. |
| └─ chargeDirection | string | Charge direction. Example: CHARGE or REFUND . |
| └─ effectiveMode | string | Effective mode of the subscription change. Defaults to IMMEDIATE if not provided. If NEXT_CYCLE is specified, another update is not allowed before the change takes effect in the next billing cycle. Valid values include: IMMEDIATE : the subscription change takes effect immediately.; NEXT_CYCLE : the subscription change takes effect at the beginning of the next billing cycle.; |
| └─ billingAction | string | Billing action. Valid values include: IMMEDIATE_CHARGE_AND_KEEP_CYCLE : charge or refund immediately and keep the current billing anchor, frequency, and schedule.; IMMEDIATE_CHARGE_AND_RESET_CYCLE : charge or refund immediately and reset the billing anchor to the current time, allowing the billing frequency to change.; NEXT_CYCLE_CHARGE_KEEP_CYCLE : charge or refund on the next billing date while keeping the current billing frequency and schedule.; |
| └─ prorationMode | string | Proration mode. Defaults to PRORATED if not provided. Valid values include: PRORATED : considers the residual value of the unused service time and calculates any extra charge or refund based on the remaining time.; NONE : does not consider the residual value of the unused service time.; CUSTOM : the merchant defines the proration adjustment amount and direction for this change instead of letting the system calculate the price difference based on the remaining cycle automatically.; |
| └─ effectivePlanVersion | integer | Effective subscription plan version after the update. |
| └─ action | object | Follow-up payment action details. |
| └─ └─ type | string | Next action type. |
| └─ └─ qrCode | string | QR code content. |
| └─ └─ qrUrl | string | QR code URL. |
| └─ └─ paymentRedirectUrl | string | Payment redirect URL. |
| └─ └─ jsSdkUrl | string | JS SDK URL. |
| └─ startAt | string | Updated subscription start time as a 13-digit millisecond timestamp string. With KEEP_CYCLE the billing anchor does not change and this field is only a display value; use currentPeriodStartAt in subscription notifications as the real billing anchor. |
| └─ endAt | string | Updated subscription end time as a 13-digit millisecond timestamp string. |
| └─ updatedAt | string | Time when this change was processed, as a 13-digit millisecond timestamp string. |
| └─ notifyUrl | string | Subscription notification URL, echoed. |
| └─ cancelAtPeriodEnd | boolean | Whether the subscription remains scheduled for period-end cancellation after the change. |
| └─ currentPeriod | integer | Current subscription period; 0 represents the trial period. |
| └─ proratedCurrency | string | Currency of the prorated amount. |
| └─ customAmount | string | Echoed custom amount when prorationMode is CUSTOM . |
| └─ customChargeDirection | string | Echoed amount direction when prorationMode is CUSTOM . |
| └─ customCurrency | string | Echoed custom currency when prorationMode is CUSTOM . |
| └─ resultCode | string | Business result code. |
| └─ resultMessage | string | Business result message. |

### Response Example

```json
{
  "accId": "2023121216311410287522",
  "clientId": "2023121216311410287",
  "code": "910000",
  "description": "success",
  "sign": "5C3D9FF88B91C968ADFA8E834ACD59C9",
  "signType": "MD5",
  "bizContent": "{\"period\":{\"count\":1,\"unit\":\"MONTH\"},\"totalPeriodCount\":12,\"flatPrice\":{\"amount\":\"60.00\",\"currency\":\"USD\"},\"discount\":{\"type\":\"fixedAmount\",\"amountOff\":\"5.00\",\"durationCount\":\"3\"},\"resultCode\":\"910000\",\"billingAction\":\"IMMEDIATE_CHARGE_AND_RESET_CYCLE\",\"requestId\":\"REQ_SUB_UPDATE_001\",\"status\":\"ACTIVE\",\"chargeAmount\":\"60.00\",\"merchantSubscriptionId\":\"SUB_MER_001\",\"effectiveMode\":\"IMMEDIATE\",\"resultMessage\":\"success\",\"chargeDirection\":\"CHARGE\",\"effectivePlanVersion\":2,\"previewQuoteId\":\"SUPD-2607150336100000001000141522\",\"chargeResult\":\"SUCCEEDED\",\"chargeCurrency\":\"USD\",\"subscriptionId\":\"SUB-1234567890abcdef\",\"prorationMode\":\"NONE\",\"proratedCurrency\":\"USD\",\"currentPeriod\":1,\"cancelAtPeriodEnd\":false,\"notifyUrl\":\"https://merchant.example.com/notify/subscription\",\"startAt\":\"1792152613237\",\"endAt\":\"1823688613237\",\"updatedAt\":\"1792152608933\",\"action\":{\"type\":\"PAYMENT_REDIRECT_URL\",\"paymentRedirectUrl\":\"https://sandbox-safepay.pingpongx.com?token=TOKEN\",\"jsSdkUrl\":\"https://payssr-cdn.pingpongx.com/acquirer-checkout-web/sandbox/pp-checkout.js?token=TOKEN\"}}"
}
```