更新订阅

约 225 字小于 1 分钟

View as Markdown

2026-06-30

OpenAPI 总览

Request Body Parameters

application/json

公共请求参数

bizContent

durationObject可选
goodsArray可选
previewQuoteIdString(64)可选
预览接口返回的报价 ID。
merchantSubscriptionIdString(64)按条件选
商户定义的订阅计划的唯一ID。与 subscriptionId 至少传一个。
subscriptionIdString(64)按条件选
PingPong 订阅单号。与 merchantSubscriptionId 至少传一个。
requestIdString(64)必填
商户请求唯一编号。
amountString(12)可选
更新后的每期扣款金额。
currencyString(3)可选
更新后的每期扣款币种。
startAtString(64)可选
更新后的订阅开始时间，10 位秒级时间戳字符串。
endAtString(64)可选
更新后的订阅结束时间，10 位秒级时间戳字符串。
cancelAtPeriodEndBoolean可选
用于撤销已预约的周期末取消。若订阅已通过 Cancel 接口设置为周期末取消，可传入 false 取消该预约，使订阅继续按当前计划生效。该字段不用于发起取消；发起立即取消或周期末取消请调用 Cancel 接口。当前不支持通过 Update 将该字段改为 true。
descriptionString(256)可选
更新后的订阅计划描述。
effectiveModeString(64)可选
计划变更的生效模式。未填默认取 IMMEDIATE。若定义 NEXT_CYCLE，在下周期生效前，不允许再进行 update。有效值包括：
- IMMEDIATE 表示订阅计划变更即刻生效。
- NEXT_CYCLE 表示订阅计划下周期开始时生效。
billingActionString(64)可选
账单处理动作。有效值包括：
- IMMEDIATE_CHARGE_AND_KEEP_CYCLE：即刻执行扣款/退款并保持现有的扣款节点，并保持现有的扣款频次和时间。
- IMMEDIATE_CHARGE_AND_RESET_CYCLE：即刻执行扣款/退款并将扣款节点调整至当前时间，允许扣款频次发生变化。
- NEXT_CYCLE_CHARGE_KEEP_CYCLE：在下一个扣款日执行扣款/退款，并保持现有的扣款频次和时间。
prorationModeString(64)可选
按比例计费模式。不填默认 PRORATED。有效值包括：
- PRORATED：考虑未兑现时间的残值并根据剩余时间折算需要额外扣款/退款的部分。
- NONE：不考虑未兑现时间的残值。
- CUSTOM：商户自定义本次 proration 调整金额和方向，而不让系统按剩余周期自动计算差价。
customAmountString(12)按条件选
当 prorationMode 为 CUSTOM 时上送的自定义金额。
customChargeDirectionString(32)按条件选
当 prorationMode 为 CUSTOM 时上送的金额方向，用于定义需要扣款还是退款。示例值为 REFUND。
expiresAtString(64)可选
本次变更支付的关单时间。用户需在该时间前完成支付以支持套餐变更。
redirectUrlString(255)可选
订阅修改若涉及到收银台，可传成功后的重定向地址，一般指商户的支付或订阅结果页。
refundNotifyUrlString(255)可选
商户自定义的退款结果异步通知地址。
地址建议：请填写基于公网域名的完整 URL，推荐使用标准 Web 端口（HTTPS 默认 443，HTTP 默认 80），并确保该地址可稳定接收 PingPongCheckout 的异步通知。
remarkString(255)可选
商户扩展字段。

请求报文示例

{
  "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"
  }
}

Responses Body Parameters

application/json

公共返回参数

bizContent

actionObject可选
previewQuoteIdString(64)可选
本次订阅更新对应的预览报价 ID。
requestIdString(64)必填
商户请求唯一编号。
subscriptionIdString(64)必填
PingPong 订阅单号。
merchantSubscriptionIdString(64)必填
商户定义的订阅计划的唯一ID。
statusString(32)必填
订阅计划状态。有效值包括：
- PENDING 订阅已创建，但尚未进入正式生效阶段。
- IN_TRIAL 订阅处于试用期内，当前服务可用，但尚未完成首次正式收费。
- ACTIVE 订阅当前正常生效中，用户有权使用服务。
- PAST_DUE 订阅已到应扣款时间，但本次扣款失败，进入欠费/补扣阶段。
- CANCELLED 订阅已终止，不再继续自动续费。
subscriptionChangeResultString(32)必填
订阅计划变更处理结果，示例值为 SUCCESS。
chargeResultString(32)必填
本次变更涉及的扣款或退款处理结果。有效值包括：
- SUCCEEDED
- FAILED
- NOT_REQUIRED
- PENDING
chargeAmountString(12)按条件选
本次变更涉及的补扣或退款金额，仅返回正数。
chargeCurrencyString(3)按条件选
本次变更涉及的补扣或退款币种。
chargeDirectionString(32)可选
费用方向，示例值为 CHARGE 或 REFUND。
effectiveModeString(32)可选
计划变更的生效模式。未填默认取 IMMEDIATE。若定义 NEXT_CYCLE，在下周期生效前，不允许再进行 update。有效值包括：
- IMMEDIATE 表示订阅计划变更即刻生效。
- NEXT_CYCLE 表示订阅计划下周期开始时生效。
billingActionString(64)可选
账单处理动作。有效值包括：
- IMMEDIATE_CHARGE_AND_KEEP_CYCLE：即刻执行扣款/退款并保持现有的扣款节点，并保持现有的扣款频次和时间。
- IMMEDIATE_CHARGE_AND_RESET_CYCLE：即刻执行扣款/退款并将扣款节点调整至当前时间，允许扣款频次发生变化。
- NEXT_CYCLE_CHARGE_KEEP_CYCLE：在下一个扣款日执行扣款/退款，并保持现有的扣款频次和时间。
prorationModeString(32)必填
按比例计费模式。不填默认 PRORATED。有效值包括：
- PRORATED：考虑未兑现时间的残值并根据剩余时间折算需要额外扣款/退款的部分。
- NONE：不考虑未兑现时间的残值。
- CUSTOM：商户自定义本次 proration 调整金额和方向，而不让系统按剩余周期自动计算差价。
effectivePlanVersionInteger可选
生效后的订阅计划版本号。
resultCodeString必填
业务处理结果码。
resultMessageString必填
业务处理结果描述。

响应报文示例

{
  "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"
  }
}