# 查询订阅信息

> 按订阅合约号查询订阅的计费、状态和 token 信息。

```yaml
openapi: 3.1.0
info:
  title: 查询订阅信息
  version: 1.0.0
  description: 按订阅合约号查询订阅的计费、状态和 token 信息。
paths:
  /v1/txn/sub/detail:
    post:
      summary: 查询订阅信息
      description: 按订阅合约号查询订阅的计费、状态和 token 信息。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantNo:
                  type: string
                  description: Onerway 分配的商户号；获取方式参见[接入准备](/zh/payments/get-started/setup#获取凭证)。
                contractId:
                  type: string
                  description: 订阅合约号，用于查询指定订阅详情；本端点只支持按 `contractId` 查询详情，不返回订阅列表或汇总数据。
                sign:
                  type: string
                  description: 请求签名字符串；生成方式详见[请求签名](/zh/payments/get-started/request-signing)。
              required:
                - merchantNo
                - contractId
                - sign
            examples:
              query-subscription-details:
                summary: 查询订阅信息
                value:
                  contractId: sub_contract_demo_202606210001
                  merchantNo: replace_with_merchant_no
                  sign: "{{SIGN}}"
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                    description: 响应码；`20000`
                      表示查询请求处理成功，其余为错误码。完整码表见[响应码](/zh/payments/api-reference/response-codes)。
                  respMsg:
                    type: string
                    description: 响应码对应的可读说明。
                  data:
                    type: object
                    properties:
                      contractId:
                        type: string
                        description: 订阅合约号，标识一份订阅合约。
                      merchantNo:
                        type: string
                        description: Onerway 分配的商户号。
                      merchantCustomerId:
                        type: string
                        description: 商户侧客户标识，用于在商户系统中关联该订阅所属客户。
                      products:
                        type: string
                        description: 订阅商品信息列表；接口返回值为 JSON 字符串，解析后为商品对象数组。
                        contentMediaType: application/json
                        contentSchema:
                          type: array
                          items:
                            type: object
                            properties:
                              currency:
                                type: string
                                description: 商品币种，[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 三位字母货币代码。
                              name:
                                type: string
                                description: 商品名称。
                              num:
                                type: string
                                description: 商品数量，使用字符串格式。
                              price:
                                type: string
                                description: 商品单价，使用字符串格式。
                              type:
                                type: string
                                description: 商品类型。
                                x-onerway-value:
                                  empty: true
                                  when:
                                    en: Can be an empty string when no product type is configured.
                                    zh: 未配置商品类型时可为空字符串。
                        x-onerway-format: json_string
                      orderAmount:
                        type: string
                        description: 单个计费周期的扣款金额。
                      orderCurrency:
                        type: string
                        description: 单个计费周期的扣款币种，[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
                          三位字母货币代码。
                      expireDate:
                        type: string
                        description: 订阅合约的到期日期，格式 `yyyy-MM-dd`。
                      frequencyType:
                        type: string
                        description: 订阅计费周期单位。
                        enum:
                          - D
                          - M
                          - Y
                        x-enum-descriptions:
                          D: 按天计费。
                          M: 按月计费。
                          Y: 按年计费。
                      frequencyPoint:
                        type: number
                        description: 计费周期长度，单位由 `frequencyType`
                          指定。自主管理订阅的计费周期按天表示，返回值即初始订阅请求中提交的天数；Onerway 不据此发起扣款。
                      cycleCount:
                        type:
                          - number
                          - "null"
                        description: 订阅计划的计费周期总数。
                        x-onerway-constraints:
                          - kind: range
                            min: 1
                            max: 99
                            text: 非空时取值范围为 `1-99`。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returns a concrete cycle count when the subscription ends after a fixed
                              number of billing cycles; returns `null` when the
                              subscription was created without `cycleCount` and
                              ends by `expireDate`.
                            zh: 订阅按固定计费周期数结束时返回具体周期数；创建订阅时未传 `cycleCount` 且按 `expireDate` 结束时返回 `null`。
                      notificationEmail:
                        type:
                          - string
                          - "null"
                        description: 订阅通知邮箱，用于接收订阅相关邮件通知。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Has a value only when a subscription notification email is configured.
                            zh: 订阅配置了通知邮箱时才有值；未配置时可为 `null`。
                      billingCycleAnchor:
                        type:
                          - string
                          - "null"
                        description: 下一期扣款时间节点，格式 `yyyy-MM-dd HH:mm:ss`。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Active subscriptions normally return the next charge time. It can be `null`
                              when the next charge time is not determined.
                            zh: "`active` 订阅正常返回下一期扣款时间；下一期扣款时间未确定时可为 `null`。"
                      dataStatus:
                        type: string
                        description: 订阅合约启用状态。
                        enum:
                          - "0"
                          - "1"
                          - "2"
                          - "3"
                        x-enum-descriptions:
                          "0": 待启用。
                          "1": 启用。
                          "2": 停用。
                          "3": 已取消。
                      subscriptionStatus:
                        type: string
                        description: 订阅当前生命周期状态。
                        enum:
                          - trialing
                          - paymentdue
                          - active
                          - pastdue
                          - paused
                          - canceled
                          - ended
                        x-enum-descriptions:
                          trialing: 试用期内；付费订阅开始前的试用期，是否计费由 `trialFromPlan` 控制。
                          paymentdue: 待付款；用户待付款或付款处理中，订阅合同尚未生效。
                          active: 订阅生效中；订阅状态正常，所有款项已支付。
                          pastdue: 付款逾期；当前周期已结束但续扣失败，订阅合同仍然有效。
                          paused: 临时暂停；某期扣款尝试全部失败后订阅暂停，合约仍处于启用状态。
                          canceled: 已取消；用户或商户在计划结束前终止订阅。
                          ended: 已结束；达到自然结束日期或完成所有计费周期。
                      metaData:
                        type:
                          - string
                          - "null"
                        description: 商户自定义数据；接口返回值为 JSON 字符串。
                        contentMediaType: application/json
                        contentSchema:
                          type: object
                          properties:
                            {}
                        x-onerway-value:
                          nullable: true
                          empty: true
                          when:
                            en: Has a value when custom metadata was provided during subscription creation
                              or update; it can be empty when no metadata is
                              configured.
                            zh: 订阅创建或更新时传入自定义数据时返回；未配置时可能为空。
                        x-onerway-format: json_string
                      createTime:
                        type: string
                        description: 首次订阅创建时间，格式 `yyyy-MM-dd HH:mm:ss`。
                      tokenId:
                        type: string
                        description: 订阅 token，用于后续扣款。
                    description: 订阅查询结果对象，包含订阅合约、客户、商品、计费周期、状态与 token 信息。
```