Query Subscription

About 112 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

merchantSubscriptionIdString(64)Conditional
Merchant-defined unique subscription plan ID. At least one of merchantSubscriptionId or subscriptionId is required.
subscriptionIdString(64)Conditional
PingPong subscription ID. At least one of subscriptionId or merchantSubscriptionId is required.
requestIdString(64)Required
Merchant request ID.

Request Body Example

{
  "clientId": "2024061100000000001",
  "accId": "20240611000000000010001",
  "signType": "SHA256",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": {
    "merchantSubscriptionId": "SUB_M_202606110001",
    "subscriptionId": "PP_SUB_001",
    "requestId": "REQ_SUB_QUERY_001"
  }
}

Responses Body Parameters

application/json

Common Response Parameters

bizContent

flatPriceObjectRequired
Current recurring amount and currency for each formal billing cycle. Note: a change scheduled via NEXT_CYCLE is not reflected in this field until it takes effect; the current price is shown before then.
- 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
Current effective subscription discount configuration. 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.
periodObjectRequired
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.
trialObjectOptional
Trial settings. An empty object {} is returned when no trial is configured.
- startAtString(10)Optional
  Trial start time as a 10-digit second-level timestamp string.
- endAtString(10)Conditional
  Trial end time as a 10-digit second-level timestamp string.
- periodDaysIntegerConditional
  Trial duration in days.
autoRecoveryObjectOptional
Automatic retry settings.
- enabledBooleanOptional
  Whether automatic retry is enabled. Automatic retry is enabled by default.
  true: retry enabled
  false: retry disabled
goodsObjectRequired
Goods information for the subscription plan.
- 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
paymentRecordsArrayOptional
Simplified payment record list. Covers recurring cycle charges only; top-up charges or refunds caused by subscription updates are not included here — query them via the Invoice Details API with the invoiceId.
- periodIntegerRequired
  Subscription period number.
- merchantTransactionIdString(64)Required
  Merchant transaction ID for that period.
refundRecordsArrayOptional
Refund record list.
- merchantRefundIdString(64)Required
  Merchant refund ID.
- originalMerchantTransactionIdString(64)Required
  Original merchant transaction ID associated with the refund.
merchantSubscriptionIdString(64)Required
Merchant-defined unique subscription plan ID.
subscriptionIdString(64)Required
PingPong subscription ID.
requestIdString(64)Required
Merchant request ID.
descriptionString(255)Optional
Subscription description.
statusString(32)Required
Subscription plan status. Valid values include:
- PENDING: the subscription has been created but is not yet active.
- IN_TRIAL: the subscription is in the trial period and service is available, but the first formal charge has not completed yet.
- ACTIVE: the subscription is currently active and the user is entitled to the service.
- PAST_DUE: the subscription reached its charge time but the current charge failed, entering the dunning or retry stage.
- CANCELLED: the subscription has ended and will not renew automatically.
cancelAtPeriodEndBooleanOptional
Whether the subscription is scheduled to cancel at period end. true means it will be canceled at the end of the current billing cycle.
cancelReasonString(64)Optional
Returned when the subscription status is CANCELLED, indicating why the subscription ended.
- user_requested: canceled by the user
- merchant_requested: canceled by the merchant
- payment_retry_exhausted: retry attempts exhausted
- plan_ended: plan naturally ended
currentPeriodIntegerRequired
Current subscription period, such as 0, 1, 2, 3..., where 0 represents the trial period.
startAtString(13)Optional
Subscription start time as a 13-digit millisecond timestamp string.
endAtString(13)Optional
Subscription end time as a 13-digit millisecond timestamp string.
notifyUrlString(255)Required
Subscription notification URL.
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.
resultCodeStringRequired
Business result code.
resultMessageStringRequired
Business result message.

Request Body Example

{
  "clientId": "2025050971820281024",
  "accId": "2025050971820281024001",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": {
    "flatPrice": {
      "amount": "9.99",
      "currency": "USD"
    },
    "discount": {
      "type": "fixedAmount",
      "amountOff": "1.00",
      "durationCount": "3"
    },
    "merchantSubscriptionId": "SUB_MER_001",
    "subscriptionId": "SUB-1234567890abcdef",
    "requestId": "REQ_SUB_QUERY_001",
    "description": "monthly membership plan",
    "status": "ACTIVE",
    "cancelReason": "",
    "currentPeriod": 1,
    "cancelAtPeriodEnd": false,
    "startAt": "1792152473588",
    "endAt": "1823688473588",
    "notifyUrl": "https://merchant.example.com/notify/subscription",
    "period": {
      "count": 1,
      "unit": "MONTH"
    },
    "totalPeriodCount": 12,
    "trial": {
      "startAt": "1785152760",
      "endAt": "1785757560",
      "periodDays": 7
    },
    "autoRecovery": {
      "enabled": true
    },
    "goods": {
      "name": "Membership",
      "description": "Monthly membership",
      "sku": "SKU_SUB_001",
      "unitPrice": "9.99",
      "number": "1",
      "imgUrl": "https://merchant.example.com/goods/sub.png",
      "virtualProduct": "Y",
      "itemType": "1"
    },
    "paymentRecords": [
      {
        "period": 1,
        "merchantTransactionId": "SUB-1234567890abcdef_P1"
      }
    ],
    "refundRecords": [
      {
        "merchantRefundId": "SREF-1234567890",
        "originalMerchantTransactionId": "SUB-1234567890abcdef_P1"
      }
    ],
    "resultCode": "000000",
    "resultMessage": "SUCCESS"
  },
  "code": "000000",
  "description": "SUCCESS"
}

Customer APIs

Invoice APIs

Query Subscription

Request Body Parameters

Request Body Example

Responses Body Parameters

Request Body Example