订阅列表

查询订阅列表，支持按客户与状态筛选。当前接口不支持游标分页参数。

GET /api/v1/subscriptions

200

{
  "object": "list",
  "data": [
    {
      "id": "<string>",
      "object": "subscription",
      "customer": "<string>",
      "store_id": "<string>",
      "currency": "<string>",
      "description": "<string>",
      "items": [
        {
          "id": "<string>",
          "price_data": {
            "id": "<string>",
            "currency": "<string>",
            "product": "<string>",
            "unit_amount": 123,
            "recurring": {
              "interval_count": 123
            }
          },
          "quantity": 2,
          "metadata": {}
        }
      ],
      "payment_method_id": "<string>",
      "billing_cycle_anchor": 123,
      "current_period_start": 123,
      "current_period_end": 123,
      "canceled_at": 123,
      "cancel_at": 123,
      "latest_invoice": "<string>",
      "latest_invoice_object": {
        "id": "<string>",
        "object": "invoice",
        "subscription_id": "<string>",
        "customer": "<string>",
        "amount_due": 123,
        "amount_paid": 123,
        "amount_remaining": 123,
        "currency": "<string>",
        "billing_reason": "<string>",
        "period_start": 123,
        "period_end": 123,
        "created": 123,
        "frequency": "<string>",
        "recurring_interval_count": 123,
        "payment_id": "<string>",
        "paid_at": 123,
        "due_date": 123
      },
      "customer_object": {
        "id": "<string>",
        "object": "customer",
        "merchant_id": "<string>",
        "external_customer_id": "<string>",
        "email": "[e-mail]",
        "name": "<string>",
        "phone": "<string>",
        "default_payment_method": "<string>",
        "description": "<string>",
        "created": 123
      },
      "payment_method_object": {
        "id": "<string>",
        "object": "payment_method",
        "customer": "<string>",
        "merchant_id": "<string>",
        "type": "<string>",
        "currency": "<string>",
        "chain_type": 123,
        "mandate_id": "<string>",
        "metadata": {},
        "created": 123
      },
      "checkout_url": "<string>",
      "metadata": {},
      "created": 123
    }
  ],
  "has_more": true,
  "url": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

授权

Authorization · string · header · 必填

Bearer API Key，例如 Bearer sk_live_xxx。

X-StablePay-Timestamp · string · header · 必填

Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。

X-StablePay-Nonce · string · header · 必填

防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。

X-StablePay-Signature · string · header · 必填

使用商户 API Secret 对 {timestamp}.{nonce}.{requestBody} 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 requestBody 为空字符串。

请求头

X-StablePay-Timestamp · string · 必填

Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。

X-StablePay-Nonce · string · 必填

防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。

Required string length: 16 - 64

X-StablePay-Signature · string · 必填

使用商户 API Secret 对 {timestamp}.{nonce}.{requestBody} 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 requestBody 为空字符串。

查询参数

customer · string

按外部客户 ID 筛选。

status · enum<string>

按订阅状态筛选。 订阅状态。

可用选项: incomplete, trialing, active, past_due, canceled, incomplete_expired

limit · integer · 默认值: 10

返回数量，默认 10，最大 100。当前实现不使用游标分页。

必填范围: 1 <= x <= 100

响应

200

application/json

查询成功。

object · string

示例:

"list"

data · object[]

Show child attributes

has_more · boolean

是否还有更多数据。当前实现按返回数量是否等于 limit 判断。

url · string

当前查询 URL。