查询订阅详情

约 165 字小于 1 分钟

View as Markdown

2026-06-16

POST

📍如何选择站点？请参阅 API 端点地址

OpenAPI 总览

Request Body Parameters

application/json

公共请求参数

bizContent

merchantSubscriptionIdString(64)按条件选
商户定义的订阅计划的唯一ID，和 subscriptionId 至少上传一个。
subscriptionIdString(64)按条件选
PingPong 订阅单号，和 merchantSubscriptionId 至少上传一个。
requestIdString(64)必填
商户请求唯一编号。

请求报文示例

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

公共返回参数

bizContent

flatPriceObject必填
当前订阅计划每个正式计费周期的扣款金额和币种。注意：通过 NEXT_CYCLE 预约的变更在生效前不会反映在该字段中（仍显示当前价格），生效后才会更新。
- amountString(12)必填
  订阅计划每个正式计费周期的实际扣款金额。
- currencyString(3)必填
  订阅计划正式计费周期的扣款币种，使用三位字母的 ISO 4217 币种代码。
discountObject可选
当前生效的订阅折扣配置；未配置折扣时不返回。
- typeString(32)必填
  折扣类型。有效值：
  fixedAmount：固定金额折扣。
  percentage：百分比折扣。
- amountOffString(12)按条件选
  固定金额减免。仅当 type 为 fixedAmount 时传入；与 percentOff 互斥。
- percentOffString(12)按条件选
  百分比减免值。仅当 type 为 percentage 时传入；与 amountOff 互斥。
- durationCountString(12)必填
  折扣持续的正式计费周期数，不包含试用期。
periodObject必填
订阅周期信息。
- countInteger必填
  单个正式计费周期包含的单位数量，必须大于等于 1。例如，unit 为 MONTH、count 为 1 表示每月计费一次；此字段不是订阅总期数。
- unitString必填
  订阅周期单位类型，有效值包括：
  YEAR：表示订阅周期以年为单位。
  MONTH：表示订阅周期以月为单位。
  WEEK：表示订阅周期以周为单位。
  DAY：表示订阅周期以天为单位。
trialObject可选
试用期信息；未配置试用期时返回空对象 {}。
- startAtString(10)可选
  试用期开始时间，10 位秒级时间戳字符串。
- endAtString(10)按条件选
  试用期结束时间，10 位秒级时间戳字符串。
- periodDaysInteger按条件选
  试用期持续天数。
autoRecoveryObject可选
自动重试配置。
- enabledBoolean可选
  是否开启自动重试，默认自动开启。
  true 开启重试
  false 关闭重试
goodsObject必填
订阅计划的商品信息。
- nameString(128)必填
  商品名称。
- descriptionString(255)可选
  商品描述。
- skuString(255)可选
  商品编号，产品SKU。
- unitPriceString(12)必填
  商品单价。注意：单个商品的 unitPrice × number 之和须与 flatPrice.amount 一致，否则返回 301012。
- unitTaxAmountString(12)按条件选
  单个商品税费，订单总金额包含税费时必填。
- taxRateString可选
  税率。
- totalDiscountAmountString按条件选
  单个商品总优惠金额，订单总金额涉及优惠时必填。
- numberString(12)必填
  商品购买数量。
- imgUrlString(255)必填
  商品主图链接。
- virtualProductString(1)可选
  是否是虚拟产品，虚拟商品（Y/N）。
- itemTypeString(1)可选
  商品类型，枚举值：1/2/3，对应含义如下：
  1 DIGITAL：数字商品
  2 PHYSICAL：实物商品
  3 SERVICE：服务
paymentRecordsArray可选
简版支付记录列表。仅包含周期扣款记录；Update 变更产生的补扣/退款不在此列表，请通过票据详情接口按 invoiceId 查询。
- periodInteger必填
  所属订阅期次。
- merchantTransactionIdString(64)必填
  该期对应的商户交易单号。
refundRecordsArray可选
退款记录列表。
- merchantRefundIdString(64)必填
  退款订单号。
- originalMerchantTransactionIdString(64)必填
  退款单对应的原支付商户交易单号。
merchantSubscriptionIdString(64)必填
商户定义的订阅计划的唯一ID。
subscriptionIdString(64)必填
PingPong 订阅单号。
requestIdString(64)必填
商户请求唯一编号。
descriptionString(255)可选
订阅计划描述。
statusString(32)必填
订阅计划状态。有效值包括：
- PENDING 订阅已创建，但尚未进入正式生效阶段。
- IN_TRIAL 订阅处于试用期内，当前服务可用，但尚未完成首次正式收费。
- ACTIVE 订阅当前正常生效中，用户有权使用服务。
- PAST_DUE 订阅已到应扣款时间，但本次扣款失败，进入欠费/补扣阶段。
- CANCELLED 订阅已终止，不再继续自动续费。
cancelAtPeriodEndBoolean可选
是否已预约在周期末取消；true 表示当前订阅将于本计费周期结束时取消。
cancelReasonString(64)可选
订阅状态为 CANCELLED 时返回，表示订阅取消原因。
- user_requested 用户取消
- merchant_requested 商户取消
- payment_retry_exhausted 自动重试结束
- plan_ended 订阅到期结束
currentPeriodInteger必填
当前所在周期，0、1、2、3...，其中 0 代表试用期。
startAtString(13)可选
订阅开始时间，13 位毫秒级时间戳字符串。
endAtString(13)可选
订阅结束时间，13 位毫秒级时间戳字符串。
notifyUrlString(255)必填
订阅通知地址。
totalPeriodCountInteger可选
订阅计划包含的正式扣款周期总数，必须大于等于 1，不包含试用期。不传时不限制正式扣款期数。
resultCodeString必填
业务处理结果码。
resultMessageString必填
业务处理结果描述。

响应报文示例

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

买家接口

票据接口

查询订阅详情

Request Body Parameters

请求报文示例

Responses Body Parameters

响应报文示例