---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/subscription/api/query/index.md
description: >-
  The Query Subscription API returns the current status, billing cycle
  information, trial configuration and a summary of completed payment records
  for a subscription plan.
---
# Query Subscription

```apidef
endpoint: POST /v4/subscriptions/query
name: Query Subscription
summary: Query subscription plan details
tags: Subscription, Query
```

The Query Subscription API returns the current status, billing cycle information, trial configuration and a summary of completed payment records for a subscription plan.

## Request Parameters

| Parameter | Type | Required | Description |
|--------|------|------|------|
| accId | string | M | Unique identifier for the store, which will appear in the response message after creation; inputting it means modifying the data |
| clientId | string | M | PingPong Merchant ID |
| signType | string | M | Supports MD5 , SHA256; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document |
| sign | string | M | Signature; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document. All parameters participate in the signature |
| version | string | M | Version number, currently fixed at 1.0, may be adjusted with changes to the interface in the future |
| bizContent | string | M | Collection of request parameters, with no limit on maximum length. Except for common request parameters, all other request parameters must be passed within this parameter, format: JSON string |
| └─ merchantSubscriptionId | string | C | Merchant-defined unique subscription plan ID. At least one of merchantSubscriptionId or subscriptionId is required. |
| └─ subscriptionId | string | C | PingPong subscription ID. At least one of subscriptionId or merchantSubscriptionId is required. |
| └─ requestId | string | M | Merchant request ID. |

### Request Example

```json
{
  "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\"}"
}
```

## Response Parameters

| Parameter | Type | Description |
|--------|------|------|
| accId | string | Unique store identifier, which will appear in the response message after being added; inputting it means modifying the data |
| clientId | string | PingPong merchant number |
| signType | string | Supports MD5 , SHA256; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document |
| sign | string | Signature; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document. All parameters participate in the signature |
| code | string | Result status code, see the appendix Status Code Table: /en/notes/appendix/successCodeList/ |
| description | string | Result description |
| bizContent | string | Business response parameters |
| └─ flatPrice | object | 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. |
| └─ └─ amount | string | Actual recurring amount for each formal billing cycle of the subscription plan. |
| └─ └─ currency | string | Billing currency for formal subscription cycles, as a 3-letter ISO 4217 currency code. |
| └─ discount | object | Current effective subscription discount configuration. Not returned when no discount is configured. |
| └─ └─ type | string | Discount type. Valid values: fixedAmount : fixed-amount discount.; percentage : percentage discount.; |
| └─ └─ amountOff | string | Fixed discount amount. Provide only when type is fixedAmount; mutually exclusive with percentOff . |
| └─ └─ percentOff | string | Percentage discount value. Provide only when type is percentage; mutually exclusive with amountOff . |
| └─ └─ durationCount | string | Number of formal billing cycles for which the discount applies, excluding the trial period. |
| └─ merchantSubscriptionId | string | Merchant-defined unique subscription plan ID. |
| └─ subscriptionId | string | PingPong subscription ID. |
| └─ requestId | string | Merchant request ID. |
| └─ description | string | Subscription description. |
| └─ status | string | 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.; |
| └─ cancelAtPeriodEnd | boolean | Whether the subscription is scheduled to cancel at period end. true means it will be canceled at the end of the current billing cycle. |
| └─ cancelReason | string | 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; |
| └─ currentPeriod | integer | Current subscription period, such as 0 , 1 , 2 , 3 ..., where 0 represents the trial period. |
| └─ startAt | string | Subscription start time as a 13-digit millisecond timestamp string. |
| └─ endAt | string | Subscription end time as a 13-digit millisecond timestamp string. |
| └─ notifyUrl | string | Subscription notification URL. |
| └─ period | object | Subscription billing cycle. |
| └─ └─ count | integer | 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. |
| └─ └─ unit | string | 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.; |
| └─ totalPeriodCount | integer | 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. |
| └─ trial | object | Trial settings. An empty object {} is returned when no trial is configured. |
| └─ └─ startAt | string | Trial start time as a 10-digit second-level timestamp string. |
| └─ └─ endAt | string | Trial end time as a 10-digit second-level timestamp string. |
| └─ └─ periodDays | integer | Trial duration in days. |
| └─ autoRecovery | object | Automatic retry settings. |
| └─ └─ enabled | boolean | Whether automatic retry is enabled. Automatic retry is enabled by default. true : retry enabled; false : retry disabled; |
| └─ goods | object | Goods information for the subscription plan. |
| └─ └─ name | string | Product name. |
| └─ └─ description | string | Product description. |
| └─ └─ sku | string | Product number, product SKU. |
| └─ └─ unitPrice | string | Unit price of the product. Note: the sum of unitPrice × number must equal flatPrice.amount , otherwise 301012 is returned. |
| └─ └─ unitTaxAmount | string | Tax per item, mandatory when the total order amount includes tax. |
| └─ └─ taxRate | string | Tax rate. |
| └─ └─ totalDiscountAmount | string | Total discount amount per item, mandatory when the total order amount involves discounts. |
| └─ └─ number | string | Quantity of the product purchased. |
| └─ └─ imgUrl | string | Main image link of the product. |
| └─ └─ virtualProduct | string | Whether it is a virtual product, virtual goods ( Y / N ). |
| └─ └─ itemType | string | Product type, enumerated values: 1 / 2 / 3 , corresponding meanings are as follows: 1 DIGITAL: Digital products; 2 PHYSICAL: Physical products; 3 SERVICE: Services; |
| └─ paymentRecords | array | 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: /en/notes/subscription/invoice/query/ API with the invoiceId. |
| └─ └─ period | integer | Subscription period number. |
| └─ └─ merchantTransactionId | string | Merchant transaction ID for that period. |
| └─ refundRecords | array | Refund record list. |
| └─ └─ merchantRefundId | string | Merchant refund ID. |
| └─ └─ originalMerchantTransactionId | string | Original merchant transaction ID associated with the refund. |
| └─ resultCode | string | Business result code. |
| └─ resultMessage | string | Business result message. |

### Response Example

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