跳转到主要内容
POST
/
api
/
v1
/
subscriptions
/
create
{
  "id": "<string>",
  "object": "subscription",
  "customer": "<string>",
  "store_id": "<string>",
  "currency": "<string>",
  "description": "<string>",
  "status": "incomplete",
  "items": [
    {
      "id": "<string>",
      "price_data": {
        "id": "<string>",
        "currency": "<string>",
        "product": "<string>",
        "unit_amount": 123,
        "recurring": {
          "interval": "day",
          "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>",
    "status": "open",
    "payment_status": "pending",
    "billing_reason": "<string>",
    "period_start": 123,
    "period_end": 123,
    "created": 123,
    "frequency": "<string>",
    "recurring_interval": "day",
    "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": "jsmith@example.com",
    "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,
    "status": "active",
    "mandate_id": "<string>",
    "metadata": {},
    "created": 123
  },
  "checkout_url": "<string>",
  "metadata": {},
  "created": 123
}

Documentation Index

Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt

Use this file to discover all available pages before exploring further.

授权

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 为空字符串。

请求头

Idempotency-Key
string
必填

商户生成的幂等键,最长 128 字符。相同键重试会返回首次创建的订阅对象。

Maximum string length: 128
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 为空字符串。

请求体

application/json
items
object[]
必填

订阅项列表,当前仅支持 1 个元素。

Required array length: 1 element
customer
string
必填

外部客户 ID(商户侧客户标识)。

customer_email
string<email>

客户邮箱。

customer_phone
string

客户手机号。

customer_name
string

客户姓名。

Maximum string length: 255
currency
enum<string>

订阅币种。当前仅支持 USD,可省略并由 price_data.currency 决定。

可用选项:
USD,
usd
description
string

订阅描述。

Maximum string length: 500
success_url
string

用户完成首次付款后的跳转 URL,最长 512 字符。

Maximum string length: 512
cancel_url
string

用户取消首次付款后的跳转 URL,最长 512 字符。

Maximum string length: 512
trial_end
integer<int64>

试用期结束时间,Unix 秒。与 billing_cycle_anchor 互斥。

billing_cycle_anchor
integer<int64>

账期锚点时间,Unix 秒。与 trial_end 互斥;非试用场景必须为未来时间或当前/过去时间代表立即扣首期。

cancel_at
integer<int64>

计划取消时间,Unix 秒。必须为未来时间,且与 iterations 互斥。

iterations
integer

运行 N 个周期后自动取消。必须大于 0,且与 cancel_at 互斥。

必填范围: x >= 1
metadata
object

商户自定义元数据。

响应

订阅创建成功;重复使用相同 Idempotency-Key 时返回首次创建的订阅对象。

订阅对象。

id
string

订阅 ID。

object
string
示例:

"subscription"

customer
string

外部客户 ID。

store_id
string

店铺 ID。

currency
string

币种。

description
string

订阅描述。

status
enum<string>

订阅状态。

可用选项:
incomplete,
trialing,
active,
past_due,
canceled,
incomplete_expired
items
object[]

订阅项列表。

payment_method_id
string

默认支付方式 ID。

billing_cycle_anchor
integer<int64>

账期锚点,Unix 秒。

current_period_start
integer<int64>

当前周期开始,Unix 秒。

current_period_end
integer<int64>

当前周期结束,Unix 秒。

canceled_at
integer<int64>

取消完成时间,Unix 秒。

cancel_at
integer<int64>

计划取消时间,Unix 秒。

latest_invoice
string

最近一张发票 ID。

latest_invoice_object
object

expand=latest_invoice 时返回完整发票对象。

customer_object
object

expand=customer 时返回完整客户对象。

payment_method_object
object

expand=payment_method 时返回完整支付方式对象。

checkout_url
string

首次付款收银台 URL,仅创建时返回。

metadata
object

商户自定义元数据。

created
integer<int64>

创建时间,Unix 秒。

Last modified on April 30, 2026