Preview Subscription Update

About 114 wordsLess than 1 minute

View as Markdown

2026-10-21

POST

📍How to choose a site? See API Endpoint Guide

OpenAPI Viewer

Request Body Parameters

application/json

Common Request Parameters

bizContent

flatPriceObjectOptional
Updated recurring amount and currency for each formal billing cycle.
- amountString(12)Required
  Updated recurring amount for each billing cycle.
- currencyString(3)Required
  Updated recurring billing currency.
periodObjectRequired
Updated subscription billing cycle.
- countIntegerRequired
  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.
- unitStringRequired
  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.
discountObjectOptional
Discount configuration for the proposed subscription plan. Applies only to formal billing cycles and not to the trial period.
- typeString(32)Required
  Discount type. Valid values:
  fixedAmount: fixed-amount discount.
  percentage: percentage discount.
- amountOffString(12)Conditional
  Fixed discount amount. Provide only when type is fixedAmount; mutually exclusive with percentOff.
- percentOffString(12)Conditional
  Percentage discount value. Provide only when type is percentage; mutually exclusive with amountOff.
- durationCountString(12)Required
  Number of formal billing cycles for which the discount applies, excluding the trial period.
goodsObjectOptional
Updated goods information.
- nameString(128)Required
  Product name.
- descriptionString(255)Optional
  Product description.
- skuString(255)Optional
  Product number, product SKU.
- unitPriceString(12)Required
  Unit price of the product. Note: the sum of unitPrice × number must equal flatPrice.amount, otherwise 301012 is returned.
- unitTaxAmountString(12)Conditional
  Tax per item, mandatory when the total order amount includes tax.
- taxRateStringOptional
  Tax rate.
- totalDiscountAmountStringConditional
  Total discount amount per item, mandatory when the total order amount involves discounts.
- numberString(12)Required
  Quantity of the product purchased.
- imgUrlString(255)Required
  Main image link of the product.
- virtualProductString(1)Optional
  Whether it is a virtual product, virtual goods (Y/N).
- itemTypeString(1)Optional
  Product type, enumerated values: 1/2/3, corresponding meanings are as follows:
  1 DIGITAL: Digital products
  2 PHYSICAL: Physical products
  3 SERVICE: Services
merchantSubscriptionIdString(64)Required
Merchant-defined unique subscription plan ID.
subscriptionIdString(64)Required
PingPong subscription ID.
requestIdString(64)Required
Unique merchant request ID.
totalPeriodCountIntegerOptional
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.
startAtString(64)Optional
Updated subscription start time as a 10-digit second-level timestamp string.
endAtString(64)Optional
Updated subscription end time as a 10-digit second-level timestamp string.
descriptionString(256)Optional
Updated subscription description.
effectiveModeString(64)Optional
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.
billingActionString(64)Optional
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.
prorationModeString(64)Optional
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.
remarkString(255)Optional
Merchant extension field.

Request Body Example

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

Responses Body Parameters

application/json

Common Response Parameters

bizContent

periodObjectRequired
Updated subscription billing cycle.
- countIntegerRequired
  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.
- unitStringRequired
  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.
flatPriceObjectRequired
Updated recurring amount and currency for each formal billing cycle.
- amountString(12)Required
  Actual recurring amount for each formal billing cycle of the subscription plan.
- currencyString(3)Required
  Billing currency for formal subscription cycles, as a 3-letter ISO 4217 currency code.
discountObjectOptional
Discount configuration in the previewed subscription plan. Not returned when no discount is configured.
- typeString(32)Required
  Discount type. Valid values:
  fixedAmount: fixed-amount discount.
  percentage: percentage discount.
- amountOffString(12)Conditional
  Fixed discount amount. Provide only when type is fixedAmount; mutually exclusive with percentOff.
- percentOffString(12)Conditional
  Percentage discount value. Provide only when type is percentage; mutually exclusive with amountOff.
- durationCountString(12)Required
  Number of formal billing cycles for which the discount applies, excluding the trial period.
currentFlatPriceObjectOptional
Currently effective recurring amount and currency before the change.
- amountString(12)Required
  Current recurring billing amount.
- currencyString(3)Required
  Current recurring billing currency.
currentPeriodObjectOptional
Current subscription cycle. Note: this API returns an object {unit, count}, unlike the integer period number returned by the subscription query API.
- unitStringRequired
  Cycle unit.
- countIntegerRequired
  Number of units.
totalPeriodCountIntegerOptional
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.
previewQuoteIdString(64)Required
Preview quote ID for the subscription update, which can be used in the subsequent update request.
requestIdString(64)Required
Unique merchant request ID.
subscriptionIdString(64)Required
PingPong subscription ID.
merchantSubscriptionIdString(64)Required
Merchant-defined unique subscription plan ID.
chargeResultString(32)Optional
Result of the related charge or refund caused by the change. Example: PENDING.
chargeAmountString(12)Optional
Charge or refund amount involved in the change.
chargeCurrencyString(3)Optional
Currency of the charge or refund involved in the change.
chargeDirectionString(32)Optional
Charge direction. Example: CHARGE or REFUND.
effectiveModeString(32)Optional
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.
billingActionString(64)Optional
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.
prorationModeString(32)Optional
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.
effectivePlanVersionIntegerOptional
Effective subscription plan version after preview.
proratedAmountString(12)Optional
Prorated price difference calculated from the remaining time (unrounded).
proratedCurrencyString(3)Optional
Currency of the prorated amount.
currentDescriptionString(256)Optional
Subscription description before the change.
startAtString(13)Optional
Updated subscription start time as a 13-digit millisecond timestamp string.
endAtString(13)Optional
Updated subscription end time as a 13-digit millisecond timestamp string.
expireAtString(13)Optional
Expiration time of this preview quote as a 13-digit millisecond timestamp string. Preview again after it expires.
resultCodeStringRequired
Business result code.
resultMessageStringRequired
Business result message.

Request Body Example

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

Customer APIs

Invoice APIs

Preview Subscription Update

Request Body Parameters

Request Body Example

Responses Body Parameters

Request Body Example