预览订阅更新

约 169 字小于 1 分钟

View as Markdown

2026-06-30

OpenAPI 总览

Request Body Parameters

application/json

公共请求参数

bizContent

durationObject必填
goodsArray可选
merchantSubscriptionIdString(64)必填
商户定义的订阅计划的唯一ID。
subscriptionIdString(64)必填
PingPong 订阅单号。
requestIdString(64)必填
商户请求唯一编号。
amountString(12)必填
更新后的每期扣款金额。
currencyString(3)必填
更新后的每期扣款币种。
startAtString(64)可选
更新后的订阅开始时间，10 位秒级时间戳字符串。
endAtString(64)可选
更新后的订阅结束时间，10 位秒级时间戳字符串。
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 调整金额和方向，而不让系统按剩余周期自动计算差价。
remarkString(255)可选
商户扩展字段。

请求报文示例

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

Responses Body Parameters

application/json

公共返回参数

bizContent

previewQuoteIdString(64)必填
本次订阅更新预览报价 ID，可用于正式提交更新。
requestIdString(64)必填
商户请求唯一编号。
subscriptionIdString(64)必填
PingPong 订阅单号。
merchantSubscriptionIdString(64)必填
商户定义的订阅计划的唯一ID。
subscriptionChangeResultString(32)必填
订阅计划变更预览结果，示例值为 SUCCESS。
chargeResultString(32)可选
变更带来的补扣或退款处理结果，示例值为 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": "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"
  }
}