查询订阅

接口说明

  • 适用场景：【订阅查询】根据订阅号或商户订单号查询订阅详情
  • 方法：POST
  • 路径：/v1/subscription/query
  • 查询约束：subscription_no 与 out_trade_no 二选一且仅填一项

请求字段

字段 类型 必填 约束 匹配后（key / 中文名） 说明
subscription_no string 条件 与 out_trade_no 二选一 subscription_no / 订阅号 订阅号
out_trade_no string 条件 与 subscription_no 二选一 out_trade_no / 商户订单号 商户订单号

响应字段

字段 类型 必填 匹配后（key / 中文名） 说明
subscription_no string 是 subscription_no / 订阅号 订阅号
out_trade_no string 是 out_trade_no / 商户订单号 商户签约订单号
product_code string 是 product_code / 产品码 产品编码
merchant_user_id string 否 merchant_user_id / 商户用户 ID 用户标识
period_type string 是 period_type / 周期类型 周期类型
period_value integer 是 period_value / 周期值 周期值
fixed_day integer 否 fixed_day / 固定扣款日 固定扣款日
period_amount integer 是 period_amount / 每期扣款金额 每期扣款金额（分）
applied_pricing_type string 否 applied_pricing_type / 营销定价类型 营销定价类型
subscription_status string 是 subscription_status / 订阅状态 订阅状态
sign_time string 是 sign_time / 签约时间 签约时间
cancel_time string 否 cancel_time / 取消时间 取消时间
next_deduction_time string 否 next_deduction_time / 下次扣款时间 下次计划扣款时间
deduct_period integer 是 deduct_period / 扣款周期数 扣款期数
total_period integer 否 total_period / 总期数 总期数

请求示例（按订阅号）：

{
  "subscription_no": "SP01010120260319120000000001"
}

请求示例（按商户订单号）：

{
  "out_trade_no": "MCH202603190001"
}

响应示例（成功）：

{
  "subscription_no": "SP01010120260319120000000001",
  "out_trade_no": "MCH202603190001",
  "product_code": "PC202603260001",
  "merchant_user_id": "U10001",
  "period_type": "MONTH",
  "period_value": 1,
  "fixed_day": null,
  "period_amount": 1990,
  "applied_pricing_type": "FIRST_PERIOD_DISCOUNT",
  "subscription_status": "ACTIVE",
  "sign_time": "2026-05-25T16:00:00+08:00",
  "cancel_time": null,
  "next_deduction_time": "2026-05-25T16:00:00+08:00",
  "deduct_period": 1,
  "total_period": 12
}

响应示例（失败）：

{
  "code": "ORDER_NOT_FOUND",
  "message": "订阅不存在"
}

错误与调用方处理

HTTP code 触发条件 调用方处理
200 — 查询成功 以 subscription_status 为准
非 200 INVALID_PARAMETER 二选一校验不通过/缺 Header 修正参数后重试
非 200 ORDER_NOT_FOUND 订阅不存在 核查单号

##