> ## 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. # 取消订阅 > 立即取消订阅，或设置为周期结束时取消。 ## OpenAPI ````yaml /zh/api/subscription-openapi.json post /api/v1/subscriptions/{subscription_id}/cancel openapi: 3.1.0 info: title: StablePay 订阅 API version: '2026-04-20' summary: StablePay 订阅相关接口：订阅管理、支付、支付方式、订阅退款与 Webhook 事件。 description: >- StablePay 订阅服务 OpenAPI 规范。 ## 基础信息 - Base URL: `https://api.stablepay.co` - 前缀: `/api/v1` - 协议: HTTPS - 数据格式: JSON (UTF-8) ## 认证 所有接口使用 `Authorization: Bearer {api_key}` 进行鉴权，并同时携带防重放签名头：`X-StablePay-Timestamp`、`X-StablePay-Nonce`、`X-StablePay-Signature`。无请求体的方法按空字符串参与签名。创建订阅时还必须额外携带 `Idempotency-Key` 请求头。 ## 金额精度 金额字段均使用币种的最小单位（如 USD 以分为单位，`1999` 代表 $19.99；USDT/USDC 使用 6 位精度）。 servers: - url: https://api.stablepay.co description: 生产环境 security: - bearerAuth: [] stablepayTimestamp: [] stablepayNonce: [] stablepaySignature: [] tags: - name: 订阅 description: 创建、查询、列出和取消订阅。 paths: /api/v1/subscriptions/{subscription_id}/cancel: post: tags: - 订阅 summary: 取消订阅 description: 立即取消订阅，或设置为周期结束时取消。 operationId: cancelSubscription parameters: - $ref: '#/components/parameters/SubscriptionId' - $ref: '#/components/parameters/XStablePayTimestamp' - $ref: '#/components/parameters/XStablePayNonce' - $ref: '#/components/parameters/XStablePaySignature' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CancelSubscriptionRequest' responses: '200': description: 取消成功。 content: application/json: schema: $ref: '#/components/schemas/Subscription' '400': description: 请求参数错误。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: 认证失败。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: 订阅不存在或无权限访问。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 服务器错误。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: SubscriptionId: name: subscription_id in: path required: true description: 订阅 ID。 schema: type: string XStablePayTimestamp: name: X-StablePay-Timestamp in: header required: true description: Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。 schema: type: string example: '1735689600' XStablePayNonce: name: X-StablePay-Nonce in: header required: true description: 防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。 schema: type: string minLength: 16 maxLength: 64 example: 550e8400-e29b-41d4-a716-446655440000 XStablePaySignature: name: X-StablePay-Signature in: header required: true description: >- 使用商户 API Secret 对 `{timestamp}.{nonce}.{requestBody}` 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 `requestBody` 为空字符串。 schema: type: string example: a1b2c3d4e5f6... schemas: CancelSubscriptionRequest: type: object properties: cancel_at_period_end: type: boolean default: false description: 是否在当前账期结束时取消。默认 false，表示立即取消。 cancellation_reason: type: string description: 取消原因。 cancellation_comment: type: string description: 取消备注。 Subscription: type: object description: 订阅对象。 properties: id: type: string description: 订阅 ID。 object: type: string example: subscription customer: type: string description: 外部客户 ID。 store_id: type: string description: 店铺 ID。 currency: type: string description: 币种。 description: type: string description: 订阅描述。 status: $ref: '#/components/schemas/SubscriptionStatus' items: type: array items: $ref: '#/components/schemas/SubscriptionItem' description: 订阅项列表。 payment_method_id: type: string description: 默认支付方式 ID。 billing_cycle_anchor: type: integer format: int64 description: 账期锚点，Unix 秒。 current_period_start: type: integer format: int64 description: 当前周期开始，Unix 秒。 current_period_end: type: integer format: int64 description: 当前周期结束，Unix 秒。 canceled_at: type: integer format: int64 description: 取消完成时间，Unix 秒。 cancel_at: type: integer format: int64 description: 计划取消时间，Unix 秒。 latest_invoice: type: string description: 最近一张发票 ID。 latest_invoice_object: allOf: - $ref: '#/components/schemas/Invoice' description: '`expand=latest_invoice` 时返回完整发票对象。' customer_object: allOf: - $ref: '#/components/schemas/Customer' description: '`expand=customer` 时返回完整客户对象。' payment_method_object: allOf: - $ref: '#/components/schemas/PaymentMethod' description: '`expand=payment_method` 时返回完整支付方式对象。' checkout_url: type: string description: 首次付款收银台 URL，仅创建时返回。 metadata: type: object additionalProperties: true description: 商户自定义元数据。 created: type: integer format: int64 description: 创建时间，Unix 秒。 ErrorResponse: type: object description: 错误响应。 properties: error: type: object properties: type: type: string description: 错误类型。 code: type: string description: 错误代码。 message: type: string description: 错误信息。 param: type: string description: 相关参数。 doc_url: type: string description: 错误文档链接。 decline_code: type: string description: 拒绝代码。 request_log_url: type: string description: 请求日志链接。 charge: type: string description: 相关支付 ID。 request_id: type: string description: 请求 ID。 timestamp: type: integer format: int64 description: 错误发生时间，Unix 秒。 SubscriptionStatus: type: string enum: - incomplete - trialing - active - past_due - canceled - incomplete_expired description: 订阅状态。 SubscriptionItem: type: object properties: id: type: string description: 订阅项 ID。 price_data: $ref: '#/components/schemas/PriceData' quantity: type: integer minimum: 1 description: 数量。 metadata: type: object additionalProperties: true description: 订阅项元数据。 Invoice: type: object required: - id - object - subscription_id - customer - amount_due - amount_paid - amount_remaining - currency - status - payment_status - billing_reason - period_start - period_end - created properties: id: type: string description: 发票 ID。 object: type: string example: invoice subscription_id: type: string description: 关联订阅 ID。 customer: type: string description: 客户 ID。 amount_due: type: integer format: int64 description: 应付金额，使用最小单位。 amount_paid: type: integer format: int64 description: 已支付金额，使用最小单位。 amount_remaining: type: integer format: int64 description: 未支付金额，使用最小单位。 currency: type: string description: 币种。 status: $ref: '#/components/schemas/InvoiceStatus' payment_status: type: string enum: - pending - processing - completed - failed - canceled - expired description: 发票支付状态。 billing_reason: type: string description: 开票原因，例如 `subscription_create`、`subscription_cycle`。 frequency: type: string description: 计费频率展示文本，例如 `Monthly`。 recurring_interval: type: string enum: - day - week - month - year description: 重复计费周期。 recurring_interval_count: type: integer format: int32 description: 重复计费周期数量。 period_start: type: integer format: int64 description: 计费周期开始，Unix 秒。 period_end: type: integer format: int64 description: 计费周期结束，Unix 秒。 payment_id: type: string description: 关联支付会话 ID。优先返回 payment_session_id，其次返回 trade_order_id。 paid_at: type: integer format: int64 description: 支付完成时间，Unix 秒。 due_date: type: integer format: int64 description: 到期时间，Unix 秒。 created: type: integer format: int64 description: 创建时间，Unix 秒。 Customer: type: object properties: id: type: string description: 客户 ID。 object: type: string example: customer merchant_id: type: string description: 商户 ID。 external_customer_id: type: string description: 外部客户 ID。 email: type: string format: email description: 客户邮箱。 name: type: string description: 客户姓名。 phone: type: string description: 客户手机号。 default_payment_method: type: string description: 默认支付方式 ID。 description: type: string description: 客户描述。 created: type: integer format: int64 description: 创建时间，Unix 秒。 PaymentMethod: type: object properties: id: type: string description: 支付方式 ID。 object: type: string example: payment_method customer: type: string description: 客户 ID。 merchant_id: type: string description: 商户 ID。 type: type: string description: 支付方式类型。 currency: type: string description: 币种。 chain_type: type: integer format: int32 description: 链类型。 status: type: string enum: - active - inactive - revoked - unknown description: 支付方式状态。 mandate_id: type: string description: 授权 ID。 metadata: type: object additionalProperties: true description: 元数据。 created: type: integer format: int64 description: 创建时间，Unix 秒。 PriceData: type: object properties: id: type: string description: 价格 ID。当前 HTTP 响应通常不返回该字段。 currency: type: string description: 币种。 product: type: string description: 产品 ID 或产品名称。 unit_amount: type: integer format: int64 description: 单价，使用最小单位。 recurring: $ref: '#/components/schemas/RecurringConfig' InvoiceStatus: type: string enum: - open - paid - void description: 发票状态。 RecurringConfig: type: object properties: interval: type: string enum: - day - week - month - year description: 计费周期。 interval_count: type: integer description: 计费间隔数。当前服务端固定为 1。 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: Bearer API Key，例如 `Bearer sk_live_xxx`。 stablepayTimestamp: type: apiKey in: header name: X-StablePay-Timestamp description: Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。 stablepayNonce: type: apiKey in: header name: X-StablePay-Nonce description: 防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。 stablepaySignature: type: apiKey in: header name: X-StablePay-Signature description: >- 使用商户 API Secret 对 `{timestamp}.{nonce}.{requestBody}` 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 `requestBody` 为空字符串。 ````