---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/subscription/api/preview/index.md
description: >-
  The Preview Subscription Update API estimates the plan adjustment result,
  proration charge or refund amount and effective version before a subscription
  change is formally submitted.
---
# Preview Subscription Update

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

The Preview Subscription Update API estimates the plan adjustment result, proration charge or refund amount and effective version before a subscription change is formally submitted.

## 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 |
| └─ merchantSubscriptionId | string | M | Merchant-defined unique subscription plan ID. |
| └─ subscriptionId | string | M | PingPong subscription ID. |
| └─ requestId | string | M | Unique merchant request ID. |
| └─ flatPrice | object | O | Updated recurring amount and currency for each formal billing cycle. |
| └─ └─ amount | string | M | Updated recurring amount for each billing cycle. |
| └─ └─ currency | string | M | Updated recurring billing currency. |
| └─ period | object | M | 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 | Discount configuration for the proposed subscription plan. Applies only to formal billing cycles and not to the trial period. |
| └─ └─ 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. |
| └─ description | string | O | Updated subscription description. |
| └─ goods | object | O | Updated goods information. |
| └─ └─ 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 | O | 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 | O | 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 | O | 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.; |
| └─ remark | string | O | Merchant extension field. |

### Request Example

```json
{
  "clientId": "2025050971820281024",
  "accId": "2025050971820281024001",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": "{\"merchantSubscriptionId\":\"SUB_MER_001\",\"subscriptionId\":\"SUB-1234567890abcdef\",\"requestId\":\"REQ_SUB_PREVIEW_001\",\"flatPrice\":{\"amount\":\"19.99\",\"currency\":\"USD\"},\"period\":{\"count\":1,\"unit\":\"MONTH\"},\"totalPeriodCount\":12,\"discount\":{\"type\":\"percentage\",\"percentOff\":\"10\",\"durationCount\":\"3\"},\"startAt\":\"1785152760\",\"description\":\"updated monthly membership plan\",\"goods\":{\"name\":\"subscription plan\",\"description\":\"qa template goods\",\"sku\":\"QA-SUB-001\",\"unitPrice\":\"19.99\",\"number\":\"1\",\"imgUrl\":\"https://merchant.example.com/goods/subscription-plan.png\",\"virtualProduct\":\"Y\",\"unitTaxAmount\":\"1.60\",\"taxRate\":\"0.08\",\"totalDiscountAmount\":\"0.00\",\"itemType\":\"3\"},\"effectiveMode\":\"IMMEDIATE\",\"billingAction\":\"IMMEDIATE_CHARGE_AND_KEEP_CYCLE\",\"prorationMode\":\"PRORATED\",\"remark\":\"preview-update\"}"
}
```

## 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 | Discount configuration in the previewed subscription plan. 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 for the subscription update, which can be used in the subsequent update request. |
| └─ requestId | string | Unique merchant request ID. |
| └─ subscriptionId | string | PingPong subscription ID. |
| └─ merchantSubscriptionId | string | Merchant-defined unique subscription plan ID. |
| └─ chargeResult | string | Result of the related charge or refund caused by the change. Example: PENDING . |
| └─ chargeAmount | string | Charge or refund amount involved in the change. |
| └─ 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.; |
| └─ effectivePlanVersion | integer | Effective subscription plan version after preview. |
| └─ proratedAmount | string | Prorated price difference calculated from the remaining time (unrounded). |
| └─ proratedCurrency | string | Currency of the prorated amount. |
| └─ currentFlatPrice | object | Currently effective recurring amount and currency before the change. |
| └─ └─ amount | string | Current recurring billing amount. |
| └─ └─ currency | string | Current recurring billing currency. |
| └─ currentDescription | string | Subscription description before the change. |
| └─ currentPeriod | object | Current subscription cycle. Note: this API returns an object {unit, count} , unlike the integer period number returned by the subscription query API. |
| └─ └─ unit | string | Cycle unit. |
| └─ └─ count | integer | Number of units. |
| └─ startAt | string | Updated subscription start time as a 13-digit millisecond timestamp string. |
| └─ endAt | string | Updated subscription end time as a 13-digit millisecond timestamp string. |
| └─ expireAt | string | Expiration time of this preview quote as a 13-digit millisecond timestamp string. Preview again after it expires. |
| └─ resultCode | string | Business result code. |
| └─ resultMessage | string | Business result message. |

### Response Example

```json
{
  "accId": "2023121216311410287522",
  "clientId": "2023121216311410287",
  "code": "910000",
  "description": "success",
  "sign": "3DD05643B2CF10B3B675A02D0152EBEF",
  "signType": "MD5",
  "bizContent": "{\"period\":{\"count\":1,\"unit\":\"MONTH\"},\"totalPeriodCount\":12,\"flatPrice\":{\"amount\":\"19.99\",\"currency\":\"USD\"},\"discount\":{\"type\":\"percentage\",\"percentOff\":\"10\",\"durationCount\":\"3\"},\"resultCode\":\"910000\",\"billingAction\":\"IMMEDIATE_CHARGE_AND_KEEP_CYCLE\",\"requestId\":\"REQ_SUB_PREVIEW_001\",\"chargeAmount\":\"4.84\",\"merchantSubscriptionId\":\"SUB_MER_001\",\"effectiveMode\":\"IMMEDIATE\",\"resultMessage\":\"success\",\"chargeDirection\":\"CHARGE\",\"effectivePlanVersion\":2,\"previewQuoteId\":\"SUPD-2607150312100000000900141522\",\"chargeResult\":\"PENDING\",\"chargeCurrency\":\"USD\",\"proratedAmount\":\"9.677419\",\"proratedCurrency\":\"USD\",\"subscriptionId\":\"SUB-1234567890abcdef\",\"prorationMode\":\"PRORATED\",\"currentFlatPrice\":{\"amount\":\"10.00\",\"currency\":\"USD\"},\"currentDescription\":\"Monthly membership subscription\",\"currentPeriod\":{\"count\":1,\"unit\":\"MONTH\"},\"startAt\":\"1792152180824\",\"endAt\":\"1823688180824\",\"expireAt\":\"1792153080828\"}"
}
```