---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/subscription/api/update/index.md
description: 更新订阅接口用于提交订阅计划变更，支持更新金额、周期、商品信息和账单处理策略，并返回变更结果及可能的后续支付动作。
---
# 更新订阅

```apidef
endpoint: POST /v4/subscriptions/update
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。 |
| └─ previewQuoteId | string | O | 预览接口返回的报价 ID。 |
| └─ merchantSubscriptionId | string | C | 商户定义的订阅计划的唯一ID。与 subscriptionId 至少传一个。 |
| └─ subscriptionId | string | C | PingPong 订阅单号。与 merchantSubscriptionId 至少传一个。 |
| └─ requestId | string | M | 商户请求唯一编号。 |
| └─ amount | string | O | 更新后的每期扣款金额。 |
| └─ currency | string | O | 更新后的每期扣款币种。 |
| └─ duration | object | O | 更新后的订阅周期信息。 |
| └─ └─ periodCount | integer | M | 订阅周期数量，必须大于等于 1。例如，如果 periodUnit 的值为 MONTH ， periodCount 的值为 1 ，则表示订阅周期为一个月。支持 1 - 无限。 |
| └─ └─ periodUnit | string | M | 订阅周期单位类型，有效值包括： YEAR ：表示订阅周期以年为单位。; MONTH ：表示订阅周期以月为单位。; WEEK ：表示订阅周期以周为单位。; DAY ：表示订阅周期以天为单位。; |
| └─ startAt | string | O | 更新后的订阅开始时间，10 位秒级时间戳字符串。 |
| └─ endAt | string | O | 更新后的订阅结束时间，10 位秒级时间戳字符串。 |
| └─ cancelAtPeriodEnd | boolean | O | 传入 true 表示该订阅计划不会立即取消，而是在当前计费周期结束时自动取消；在周期结束前，订阅仍按当前状态继续生效，商户应继续提供服务。传入 false 表示按本次请求立即执行取消或按其他变更参数处理。默认为 false 。 |
| └─ 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 调整金额和方向，而不让系统按剩余周期自动计算差价。; |
| └─ customAmount | string | C | 当 prorationMode 为 CUSTOM 时上送的自定义金额。 |
| └─ customChargeDirection | string | C | 当 prorationMode 为 CUSTOM 时上送的金额方向，用于定义需要扣款还是退款。示例值为 REFUND 。 |
| └─ expiresAt | string | O | 本次变更支付的关单时间。用户需在该时间前完成支付以支持套餐变更。 |
| └─ redirectUrl | string | O | 订阅修改若涉及到收银台，可传成功后的重定向地址，一般指商户的支付或订阅结果页。 |
| └─ refundNotifyUrl | string | O | 商户自定义的退款结果异步通知地址。 |
| └─ remark | string | O | 商户扩展字段。 |

### 请求示例

```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\",\"amount\":\"60.00\",\"currency\":\"USD\",\"description\":\"qa update template description\",\"duration\":{\"periodCount\":1,\"periodUnit\":\"MONTH\"},\"prorationMode\":\"CUSTOM\",\"customAmount\":\"58.06\",\"customChargeDirection\":\"REFUND\"}"
}
```

## 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| 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。 |
| └─ status | string | 订阅计划状态。有效值包括： PENDING 订阅已创建，但尚未进入正式生效阶段。; IN_TRIAL 订阅处于试用期内，当前服务可用，但尚未完成首次正式收费。; ACTIVE 订阅当前正常生效中，用户有权使用服务。; PAST_DUE 订阅已到应扣款时间，但本次扣款失败，进入欠费/补扣阶段。; CANCELLED 订阅已终止，不再继续自动续费。; |
| └─ subscriptionChangeResult | string | 订阅计划变更处理结果，示例值为 SUCCESS 。 |
| └─ chargeResult | string | 本次变更涉及的扣款或退款处理结果。有效值包括： SUCCEEDED; FAILED; NOT_REQUIRED; 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 | 生效后的订阅计划版本号。 |
| └─ action | object | 支付后续动作信息。 |
| └─ └─ type | string | 下一步动作类型。 |
| └─ └─ qrCode | string | 二维码内容。 |
| └─ └─ qrUrl | string | 二维码链接。 |
| └─ └─ paymentRedirectUrl | string | 支付跳转地址。 |
| └─ └─ jsSdkUrl | string | JS SDK 地址。 |
| └─ resultCode | string | 业务处理结果码。 |
| └─ resultMessage | string | 业务处理结果描述。 |

### 响应示例

```json
{
  "accId": "2023121216311410287522",
  "clientId": "2023121216311410287",
  "code": "910000",
  "description": "success",
  "sign": "5C3D9FF88B91C968ADFA8E834ACD59C9",
  "signType": "MD5",
  "bizContent": "{\"resultCode\":\"910000\",\"billingAction\":\"IMMEDIATE_CHARGE_AND_KEEP_CYCLE\",\"requestId\":\"AUTO988778009\",\"status\":\"ACTIVE\",\"chargeAmount\":\"58.06\",\"subscriptionChangeResult\":\"SUCCESS\",\"merchantSubscriptionId\":\"autocaseSubMerId_178401881002391785\",\"effectiveMode\":\"IMMEDIATE\",\"resultMessage\":\"success\",\"chargeDirection\":\"REFUND\",\"effectivePlanVersion\":3,\"previewQuoteId\":\"SUPD-2607150336100000001000141522\",\"chargeResult\":\"PENDING\",\"chargeCurrency\":\"USD\",\"subscriptionId\":\"SUB-2607140846100000000900111522\",\"prorationMode\":\"CUSTOM\"}"
}
```