---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/subscription/api/preview/index.md
description: 预览订阅更新接口用于在正式提交订阅变更前，预估本次变更带来的订阅计划调整结果、补扣或退款金额及生效版本等信息。
---
# 预览订阅更新

```apidef
endpoint: POST /v4/subscriptions/preview
name: 预览订阅更新
summary: 预览订阅计划变更结果
tags: Subscription, Update
```

预览订阅更新接口用于在正式提交订阅变更前，预估本次变更带来的订阅计划调整结果、补扣或退款金额及生效版本等信息。

## 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| accId | string | M | 店铺唯一标识 |
| clientId | string | M | PingPong 商户号 |
| signType | string | M | 支持 MD5 、 SHA256 ，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/一栏 |
| sign | string | M | 签名，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/，所有参数均参与签名 |
| version | string | M | 版本号，当前固定为1.0，后续随接口变动可能有调整 |
| bizContent | string | M | 请求参数的集合，最大长度不限，除公共请求参数外所有请求参数都必须放在这个参数中传递，格式：JSON字符串。该字段内容为 JSON 字符串，反序列化后的结构见 contentSchema。 |
| └─ merchantSubscriptionId | string | M | 商户定义的订阅计划的唯一ID。 |
| └─ subscriptionId | string | M | PingPong 订阅单号。 |
| └─ requestId | string | M | 商户请求唯一编号。 |
| └─ amount | string | M | 更新后的每期扣款金额。 |
| └─ currency | string | M | 更新后的每期扣款币种。 |
| └─ duration | object | M | 更新后的订阅周期信息。 |
| └─ └─ periodCount | integer | M | 订阅周期数量，必须大于等于 1。例如，如果 periodUnit 的值为 MONTH ， periodCount 的值为 1 ，则表示订阅周期为一个月。支持 1 - 无限。 |
| └─ └─ periodUnit | string | M | 订阅周期单位类型，有效值包括： YEAR ：表示订阅周期以年为单位。; MONTH ：表示订阅周期以月为单位。; WEEK ：表示订阅周期以周为单位。; DAY ：表示订阅周期以天为单位。; |
| └─ startAt | string | O | 更新后的订阅开始时间，10 位秒级时间戳字符串。 |
| └─ endAt | string | O | 更新后的订阅结束时间，10 位秒级时间戳字符串。 |
| └─ description | string | O | 更新后的订阅计划描述。 |
| └─ goods | array | O | 更新后的商品信息。 |
| └─ └─ name | string | M | 商品名称。 |
| └─ └─ description | string | O | 商品描述。 |
| └─ └─ sku | string | O | 商品编号，产品SKU。 |
| └─ └─ unitPrice | string | M | 商品单价。 |
| └─ └─ unitTaxAmount | string | C | 单个商品税费，订单总金额包含税费时必填。 |
| └─ └─ taxRate | string | O | 税率。 |
| └─ └─ totalDiscountAmount | string | C | 单个商品总优惠金额，订单总金额涉及优惠时必填。 |
| └─ └─ number | string | M | 商品购买数量。 |
| └─ └─ imgUrl | string | M | 商品主图链接。 |
| └─ └─ virtualProduct | string | O | 是否是虚拟产品，虚拟商品（ Y / N ）。 |
| └─ └─ itemType | string | O | 商品类型，枚举值： 1 / 2 / 3 ，对应含义如下： 1 DIGITAL：数字商品; 2 PHYSICAL：实物商品; 3 SERVICE：服务; |
| └─ effectiveMode | string | O | 计划变更的生效模式。未填默认取 IMMEDIATE 。若定义 NEXT_CYCLE ，在下周期生效前，不允许再进行 update。有效值包括： IMMEDIATE 表示订阅计划变更即刻生效。; NEXT_CYCLE 表示订阅计划下周期开始时生效。; |
| └─ billingAction | string | O | 账单处理动作。有效值包括： IMMEDIATE_CHARGE_AND_KEEP_CYCLE ：即刻执行扣款/退款并保持现有的扣款节点，并保持现有的扣款频次和时间。; IMMEDIATE_CHARGE_AND_RESET_CYCLE ：即刻执行扣款/退款并将扣款节点调整至当前时间，允许扣款频次发生变化。; NEXT_CYCLE_CHARGE_KEEP_CYCLE ：在下一个扣款日执行扣款/退款，并保持现有的扣款频次和时间。; |
| └─ prorationMode | string | O | 按比例计费模式。不填默认 PRORATED 。有效值包括： PRORATED ：考虑未兑现时间的残值并根据剩余时间折算需要额外扣款/退款的部分。; NONE ：不考虑未兑现时间的残值。; CUSTOM ：商户自定义本次 proration 调整金额和方向，而不让系统按剩余周期自动计算差价。; |
| └─ remark | string | O | 商户扩展字段。 |

### 请求示例

```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\",\"amount\":\"19.99\",\"currency\":\"USD\",\"duration\":{\"periodCount\":1,\"periodUnit\":\"MONTH\"},\"startAt\":\"1785152760\",\"endAt\":\"1816688760\",\"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\"}"
}
```

## 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| accId | string | 店铺唯一标识 |
| clientId | string | PingPong 商户号 |
| signType | string | 支持 MD5 、 SHA256 ，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/一栏 |
| sign | string | 签名，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/，所有参数均参与签名 |
| code | string | 结果状态码，见附录状态码表: /notes/zh/appendix/successCodeList/ |
| description | string | 结果描述 |
| bizContent | string | 业务响应参数。该字段内容为 JSON 字符串，反序列化后的结构见 contentSchema。 |
| └─ previewQuoteId | string | 本次订阅更新预览报价 ID，可用于正式提交更新。 |
| └─ requestId | string | 商户请求唯一编号。 |
| └─ subscriptionId | string | PingPong 订阅单号。 |
| └─ merchantSubscriptionId | string | 商户定义的订阅计划的唯一ID。 |
| └─ subscriptionChangeResult | string | 订阅计划变更预览结果，示例值为 SUCCESS 。 |
| └─ chargeResult | string | 变更带来的补扣或退款处理结果，示例值为 PENDING 。 |
| └─ chargeAmount | string | 本次变更涉及的补扣或退款金额。 |
| └─ chargeCurrency | string | 本次变更涉及的补扣或退款币种。 |
| └─ chargeDirection | string | 费用方向，示例值为 CHARGE 或 REFUND 。 |
| └─ effectiveMode | string | 计划变更的生效模式。未填默认取 IMMEDIATE 。若定义 NEXT_CYCLE ，在下周期生效前，不允许再进行 update。有效值包括： IMMEDIATE 表示订阅计划变更即刻生效。; NEXT_CYCLE 表示订阅计划下周期开始时生效。; |
| └─ billingAction | string | 账单处理动作。有效值包括： IMMEDIATE_CHARGE_AND_KEEP_CYCLE ：即刻执行扣款/退款并保持现有的扣款节点，并保持现有的扣款频次和时间。; IMMEDIATE_CHARGE_AND_RESET_CYCLE ：即刻执行扣款/退款并将扣款节点调整至当前时间，允许扣款频次发生变化。; NEXT_CYCLE_CHARGE_KEEP_CYCLE ：在下一个扣款日执行扣款/退款，并保持现有的扣款频次和时间。; |
| └─ prorationMode | string | 按比例计费模式。不填默认 PRORATED 。有效值包括： PRORATED ：考虑未兑现时间的残值并根据剩余时间折算需要额外扣款/退款的部分。; NONE ：不考虑未兑现时间的残值。; CUSTOM ：商户自定义本次 proration 调整金额和方向，而不让系统按剩余周期自动计算差价。; |
| └─ effectivePlanVersion | integer | 预览后的订阅计划版本号。 |
| └─ resultCode | string | 业务处理结果码。 |
| └─ resultMessage | string | 业务处理结果描述。 |

### 响应示例

```json
{
  "accId": "2023121216311410287522",
  "clientId": "2023121216311410287",
  "code": "910000",
  "description": "success",
  "sign": "3DD05643B2CF10B3B675A02D0152EBEF",
  "signType": "MD5",
  "bizContent": "{\"resultCode\":\"910000\",\"billingAction\":\"IMMEDIATE_CHARGE_AND_KEEP_CYCLE\",\"requestId\":\"AUTO-1231231343212\",\"chargeAmount\":\"58.06\",\"subscriptionChangeResult\":\"SUCCESS\",\"merchantSubscriptionId\":\"autocaseSubMerId_178408500235065016\",\"effectiveMode\":\"IMMEDIATE\",\"resultMessage\":\"success\",\"chargeDirection\":\"CHARGE\",\"effectivePlanVersion\":2,\"previewQuoteId\":\"SUPD-2607150312100000000900141522\",\"chargeResult\":\"PENDING\",\"chargeCurrency\":\"USD\",\"subscriptionId\":\"SUB-2607150310100000001300111522\",\"prorationMode\":\"NONE\"}"
}
```