API 参考

订阅是 PaymentKit 中定期计费的基石。订阅 API 允许您管理客户订阅的整个生命周期，从创建、更新到暂停、恢复和取消。本参考提供了所有可用订阅相关方法的详细信息。
如需更实用的订阅工作流实施指南，请参阅 订阅指南。
订阅对象#Subscription 对象包含有关客户定期付款计划的所有信息。
属性
类型
描述
id
string
订阅的唯一标识符。
status
string
订阅的状态。可以是 active、past_due、paused、canceled、incomplete、incomplete_expired 或 trialing。
customer_id
string
此订阅所属客户的 ID。
currency_id
string
订阅所用货币的 ID。
current_period_start
number
当前计费周期的开始时间，以 Unix 时间戳表示。
current_period_end
number
当前计费周期的结束时间，以 Unix 时间戳表示。
cancel_at_period_end
boolean
如果为 true，订阅将在当前周期结束时取消。
canceled_at
number
订阅被取消的时间，以 Unix 时间戳表示。
start_date
number
订阅的开始日期，以 Unix 时间戳表示。
ended_at
number
订阅的结束日期，以 Unix 时间戳表示。
trial_start
number
试用期的开始时间，以 Unix 时间戳表示。
trial_end
number
试用期的结束时间，以 Unix 时间戳表示。
collection_method
string
charge_automatically 或 send_invoice。
default_payment_method_id
string
订阅的默认支付方式 ID。
latest_invoice_id
string
为此订阅生成的最新发票的 ID。
metadata
object
可附加到对象的一组键值对。
cancelation_details
object
如果订阅被取消，则提供有关取消的详细信息。包含 comment、feedback 和 reason。
pause_collection
object
如果订阅被暂停，则提供有关暂停状态的详细信息。包含 behavior 和 resumes_at。
检索订阅#通过唯一 ID 检索现有订阅的详细信息。
参数
名称
类型
描述
id
string
要检索的订阅的唯一标识符。
返回
如果找到，则返回 Subscription 对象。检索时，该对象会展开并包含其他详细信息（TSubscriptionExpanded）。
async function retrieveSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.retrieve(subscriptionId);
    console.log('已检索订阅:', subscription);
  } catch (error) {
    console.error('检索订阅时出错:', error.message);
  }
}

retrieveSubscription('sub_xxxxxxxxxxxxxx');响应示例
{
  "id": "sub_xxxxxxxxxxxxxx",
  "livemode": false,
  "currency_id": "usd",
  "customer_id": "cus_xxxxxxxxxxxxxx",
  "current_period_end": 1672531199,
  "current_period_start": 1669852800,
  "status": "active",
  "cancel_at_period_end": false,
  "billing_cycle_anchor": 1669852800,
  "collection_method": "charge_automatically",
  "start_date": 1669852800,
  "metadata": {}
}更新订阅#通过设置或取消设置属性来更新现有订阅。
参数
名称
类型
描述
id
string
要更新的订阅的唯一标识符。
data
object
包含要更新字段的对象。
数据字段
名称
类型
描述
description
string
附加到订阅的任意字符串。
default_payment_method_id
string
订阅的默认支付方式 ID。
metadata
object
与订阅一起存储的一组键值对。
proration_behavior
string
确定计费周期更改时如何处理按比例计费。可以是 always_invoice、create_prorations 或 none。
async function updateSubscription(subscriptionId) {
  try {
    const updatedSubscription = await payment.subscriptions.update(subscriptionId, {
      metadata: { order_id: '6735' }
    });
    console.log('已更新订阅:', updatedSubscription);
  } catch (error) {
    console.error('更新订阅时出错:', error.message);
  }
}

updateSubscription('sub_xxxxxxxxxxxxxx');响应示例
{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "active",
  "metadata": {
    "order_id": "6735"
  }
}列出订阅#返回您的订阅列表。订阅按创建日期排序返回，最新的订阅排在最前面。
参数
名称
类型
描述
status
string
按状态筛选订阅（例如 active、trialing、canceled）。
customer_id
string
按特定客户 ID 筛选。
customer_did
string
按特定客户 DID 筛选。
activeFirst
boolean
如果为 true，则活跃订阅排在最前面。
order
string or array
排序顺序（例如 'created_at:DESC'）。
page
number
用于分页的页码。
pageSize
number
每页的项目数。默认为 20。
async function listSubscriptions() {
  try {
    const subscriptions = await payment.subscriptions.list({ 
      status: 'active',
      limit: 5
    });
    console.log('活跃订阅:', subscriptions.list);
  } catch (error) {
    console.error('列出订阅时出错:', error.message);
  }
}

listSubscriptions();响应示例
{
  "count": 50,
  "list": [
    {
      "id": "sub_xxxxxxxxxxxxxx",
      "customer_id": "cus_xxxxxxxxxxxxxx",
      "status": "active",
      "current_period_end": 1672531199
    }
  ]
}取消订阅#取消客户的订阅。订阅状态将设置为 canceled。
参数
名称
类型
描述
id
string
要取消的订阅的唯一标识符。
body
object
包含取消参数的对象。
正文字段
名称
类型
描述
at
string
何时取消。可以是 now、current_period_end 或 custom。
time
number or string
如果 at 是 custom，则为必需字段。取消应生效的 Unix 时间戳。
refund
string
指定退款行为。可以是 none、proration 或 last。
reason
string
取消原因（例如 cancellation_requested、payment_failed）。
feedback
string
客户对取消的反馈。
comment
string
关于取消的内部评论。
async function cancelSubscription(subscriptionId) {
  try {
    const canceledSubscription = await payment.subscriptions.cancel(subscriptionId, {
      at: 'current_period_end',
      reason: 'cancellation_requested',
      feedback: 'switched_service'
    });
    console.log('已计划取消的订阅:', canceledSubscription);
  } catch (error) {
    console.error('取消订阅时出错:', error.message);
  }
}

cancelSubscription('sub_xxxxxxxxxxxxxx');响应示例
{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "active",
  "cancel_at_period_end": true,
  "canceled_at": null,
  "cancelation_details": {
    "reason": "cancellation_requested",
    "feedback": "switched_service"
  }
}暂停订阅#暂停订阅的收款。订阅状态将设置为 paused。
参数
名称
类型
描述
id
string
要暂停的订阅的唯一标识符。
async function pauseSubscription(subscriptionId) {
  try {
    const pausedSubscription = await payment.subscriptions.pause(subscriptionId);
    console.log('已暂停的订阅:', pausedSubscription);
  } catch (error) {
    console.error('暂停订阅时出错:', error.message);
  }
}

pauseSubscription('sub_xxxxxxxxxxxxxx');响应示例
{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "paused",
  "pause_collection": {
    "behavior": "keep_as_draft",
    "resumes_at": 1672531199
  }
}恢复订阅#恢复已暂停的订阅。订阅状态将恢复为 active。
参数
名称
类型
描述
id
string
要恢复的订阅的唯一标识符。
async function resumeSubscription(subscriptionId) {
  try {
    const resumedSubscription = await payment.subscriptions.resume(subscriptionId);
    console.log('已恢复的订阅:', resumedSubscription);
  } catch (error) {
    console.error('恢复订阅时出错:', error.message);
  }
}

resumeSubscription('sub_xxxxxxxxxxxxxx');响应示例
{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "active",
  "pause_collection": null
}找回订阅#找回已取消的订阅。如果客户在取消后改变主意，此功能非常有用。
参数
名称
类型
描述
id
string
要找回的订阅的唯一标识符。
async function recoverSubscription(subscriptionId) {
  try {
    const recoveredSubscription = await payment.subscriptions.recover(subscriptionId);
    console.log('已找回的订阅:', recoveredSubscription);
  } catch (error) {
    console.error('找回订阅时出错:', error.message);
  }
}

recoverSubscription('sub_xxxxxxxxxxxxxx');响应示例
{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "active",
  "recovered_from": "sub_originalxxxxxx"
}
现在您已详细了解如何管理订阅。要管理订阅中的单个产品或服务，请继续阅读 订阅项目 API 参考。

属性	类型	描述
`id`	`string`	订阅的唯一标识符。
`status`	`string`	订阅的状态。可以是 `active`、`past_due`、`paused`、`canceled`、`incomplete`、`incomplete_expired` 或 `trialing`。
`customer_id`	`string`	此订阅所属客户的 ID。
`currency_id`	`string`	订阅所用货币的 ID。
`current_period_start`	`number`	当前计费周期的开始时间，以 Unix 时间戳表示。
`current_period_end`	`number`	当前计费周期的结束时间，以 Unix 时间戳表示。
`cancel_at_period_end`	`boolean`	如果为 true，订阅将在当前周期结束时取消。
`canceled_at`	`number`	订阅被取消的时间，以 Unix 时间戳表示。
`start_date`	`number`	订阅的开始日期，以 Unix 时间戳表示。
`ended_at`	`number`	订阅的结束日期，以 Unix 时间戳表示。
`trial_start`	`number`	试用期的开始时间，以 Unix 时间戳表示。
`trial_end`	`number`	试用期的结束时间，以 Unix 时间戳表示。
`collection_method`	`string`	`charge_automatically` 或 `send_invoice`。
`default_payment_method_id`	`string`	订阅的默认支付方式 ID。
`latest_invoice_id`	`string`	为此订阅生成的最新发票的 ID。
`metadata`	`object`	可附加到对象的一组键值对。
`cancelation_details`	`object`	如果订阅被取消，则提供有关取消的详细信息。包含 `comment`、`feedback` 和 `reason`。
`pause_collection`	`object`	如果订阅被暂停，则提供有关暂停状态的详细信息。包含 `behavior` 和 `resumes_at`。

名称	类型	描述
`description`	`string`	附加到订阅的任意字符串。
`default_payment_method_id`	`string`	订阅的默认支付方式 ID。
`metadata`	`object`	与订阅一起存储的一组键值对。
`proration_behavior`	`string`	确定计费周期更改时如何处理按比例计费。可以是 `always_invoice`、`create_prorations` 或 `none`。

名称	类型	描述
`status`	`string`	按状态筛选订阅（例如 `active`、`trialing`、`canceled`）。
`customer_id`	`string`	按特定客户 ID 筛选。
`customer_did`	`string`	按特定客户 DID 筛选。
`activeFirst`	`boolean`	如果为 `true`，则活跃订阅排在最前面。
`order`	`string` or `array`	排序顺序（例如 `'created_at:DESC'`）。
`page`	`number`	用于分页的页码。
`pageSize`	`number`	每页的项目数。默认为 `20`。

名称	类型	描述
`at`	`string`	何时取消。可以是 `now`、`current_period_end` 或 `custom`。
`time`	`number` or `string`	如果 `at` 是 `custom`，则为必需字段。取消应生效的 Unix 时间戳。
`refund`	`string`	指定退款行为。可以是 `none`、`proration` 或 `last`。
`reason`	`string`	取消原因（例如 `cancellation_requested`、`payment_failed`）。
`feedback`	`string`	客户对取消的反馈。
`comment`	`string`	关于取消的内部评论。

概述

快速入门

核心概念

使用指南

API 参考

TypeScript 支持

订阅

订阅对象#

检索订阅#

更新订阅#

列出订阅#

取消订阅#

暂停订阅#

恢复订阅#

找回订阅#

结账会话

订阅项目

名称	类型	描述
`id`	`string`	要更新的订阅的唯一标识符。
`data`	`object`	包含要更新字段的对象。

名称	类型	描述
`id`	`string`	要取消的订阅的唯一标识符。
`body`	`object`	包含取消参数的对象。