> ## Documentation Index > Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt > Use this file to discover all available pages before exploring further. # 获取订阅列表 > 查询订阅合同列表 查询订阅合同列表 ## OpenAPI ````yaml openapi/v1-zh.yaml GET /api/v1/subscription openapi: 3.0.3 info: title: Subotiz API description: Subotiz OpenAPI version: 1.0.0 servers: - url: https://{api}.subotiz.com variables: api: default: api security: - sec0: [] tags: - name: 折扣 description: 折扣 - name: 发票 description: 发票 - name: 退款 description: 退款 - name: 商品管理 description: 商品管理 - name: 订阅 description: 订阅 - name: 商品定价 description: 商品定价方案 - name: 交易单 description: 交易单 - name: 支付流水 description: 支付流水 - name: 结账会话 description: 结账会话 - name: 顾客 description: 顾客 - name: 顾客门户 description: 顾客门户 - name: Webhook description: Webhook - name: 争议 description: 争议订单 paths: /api/v1/subscription: get: tags: - 订阅 summary: 获取订阅列表 description: 查询订阅合同列表 operationId: v1-subscription-list-subscription parameters: - name: ids in: query description: 订阅的 id 数组，筛选 id 属于这个数组的订阅记录 schema: type: array items: type: string - name: status in: query description: |- 订阅业务状态： - init - 待生效 - trial - 试用期 - active - 生效中 - paused - 暂停 - past_due - 逾期 - unpaid - 未支付 - canceled - 已终止 schema: type: string - name: starting_after in: query description: >- 用于分页的游标。`starting_after` 是定义您在列表中位置的对象 ID。例如，如果想获取下一页，可以在第一次获取对象列表之后，使用最后一个对象的 id 作为参数值。不能和 `ending_before 同时使用 schema: type: string - name: ending_before in: query description: >- 用于分页的游标 `ending_before` 是定义您在列表中位置的对象 ID。例如，如果想获取上一页，可以在第一次获取对象列表之后，使用第一个对象的 id 作为参数值。不能和 `starting_after` 同时使用 schema: type: string - name: limit in: query description: 分页参数，每页数量，默认：10，接口默认按创建时间倒序排序。限制：[1, 100] schema: type: integer format: int32 - name: merchant_id in: query description: 商户唯一标识 schema: type: string - name: order_ids in: query description: 您平台的订单 ID 数组，筛选出 `order_id` 属于此数组的订阅记录。 schema: type: array items: type: string - name: source_trade_ids in: query description: 来源交易订单 ID 数组，筛选出 `source_trade_id` 属于此数组的订阅记录 schema: type: array items: type: string - name: billing_cycle_unit in: query description: |- 根据订阅周期筛选，支持的枚举值: - week - 周 - month - 月 - quarter - 季 - year - 年 - customer-initiated - 客户发起 - over_threshold - 按量计费 schema: type: array items: type: string - name: search_type in: query description: >- 搜索类型，取值为以下字段之一：subscription_id、trade_id、refund_id、invoice_id、customer_id schema: type: string - name: search_value in: query description: 与 search_type 对应的搜索值 schema: type: string - name: created_at.gt in: query description: 用于过滤的最小值（不包含，RFC3339格式的UTC时间，例如'2025-01-01T00:00:00Z') schema: type: string - name: created_at.gte in: query description: 用于过滤的最小值（包含，RFC3339格式的UTC时间，例如'2025-01-01T00:00:00Z') schema: type: string - name: created_at.lt in: query description: 用于过滤的最大值（不包含，RFC3339格式的UTC时间，例如'2025-01-01T00:00:00Z') schema: type: string - name: created_at.lte in: query description: 用于过滤的最大值（包含，RFC3339格式的UTC时间，例如'2025-01-01T00:00:00Z') schema: type: string - $ref: '#/components/parameters/HeaderRequestID' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListSubscriptionsResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/BaseResponse' example: code: system_error message: Internal server error. components: parameters: HeaderRequestID: name: Request-Id in: header description: 请求的唯一标识符 required: true schema: type: string default: 008e3967-a1b5-48bb-be14-d5bff5092e61 schemas: ListSubscriptionsResponse: type: object properties: code: type: string description: error code message: type: string description: error message data: $ref: '#/components/schemas/ListSubscriptionsResponse_Data' BaseResponse: type: object properties: code: type: string description: 错误码 message: type: string description: 错误详细信息 ListSubscriptionsResponse_Data: type: object properties: has_more: type: boolean description: 是否还有更多数据 list: type: array items: $ref: '#/components/schemas/Subscription' description: 订阅记录列表 Subscription: type: object properties: id: type: string description: 订阅唯一标识 customer_id: type: string description: Subotiz 顾客唯一标识 email: type: string description: 顾客邮箱 cycle_index: type: integer description: 订阅当前所处周期 format: int32 metadata: type: object additionalProperties: type: string description: 元数据 cancel_reason: type: string description: 终止订阅的原因 sub_merchant_id: type: string description: 商户唯一标识 status: type: string description: |- 订阅业务状态： - init - 待生效 - trial - 试用期 - active - 生效中 - paused - 暂停 - past_due - 逾期 - unpaid - 未支付 - canceled - 已终止 price_id: type: string description: 商品定价方案唯一标识 total_cycles: type: integer description: 总周期数（0表示无限期） format: int32 current_period_start: type: string description: 当前计费周期开始时间 current_period_end: type: string description: 当前计费周期结束时间 next_invoice_date: type: string description: 下一次续订时间 created_at: type: string description: 创建时间 updated_at: type: string description: 更新时间 cancel_at: type: string description: 终止订阅时间（可选） order_id: type: string description: 接入方订单 id，创建 checkout session 时传入的 order_id 一致。 source_trade_id: type: string description: 来源交易订单 ID price_type: type: string description: 定价模型 price_version_id: type: string description: 商品定价方案版本唯一标识 first_source_channel: type: string description: 该结账会话的首次创建来源 last_source_channel: type: string description: 该结账会话的最后访问来源 securitySchemes: sec0: type: http description: 'Bearer API Key 鉴权。格式：Authorization: Bearer {your_api_key}' scheme: bearer ````