使用指南

订阅是 PaymentKit 中循环计费的核心。它们允许你为你的产品和服务按重复的计划向客户收费。本指南介绍了如何管理整个订阅生命周期，从创建、列出到更新、取消和报告计量使用情况。
在管理订阅之前，你应该熟悉如何设置你的产品。更多详情，请参阅 产品与价格 指南。
订阅生命周期流程#订阅从创建到最终完成或取消，会经历几个状态。理解这个流程是管理你循环收入的关键。
活跃周期
完成
支付失败
支付成功
续订
暂停
恢复
支付成功
支付失败且已过期
用户或 API 取消
宽限期结束
结账会话
订阅已创建：试用中或未完成
状态：活跃
状态：逾期
状态：已暂停
状态：未完成且已过期
状态：已取消

列出订阅#检索所有订阅的分页列表。你可以根据各种标准（如客户 ID 或状态）筛选列表。
参数
Name
Type
Description
status
string
按状态筛选订阅。选项包括 active、past_due、paused、canceled、incomplete、incomplete_expired、trialing。
customer_id
string
按客户的唯一 ID 筛选订阅。
customer_did
string
按客户的 DID 筛选订阅。
metadata.{key}
string
按自定义元数据字段筛选。
order
string
结果的排序顺序，例如 'updated_at:ASC' 或 'created_at:DESC'。
activeFirst
boolean
如果为 true，则活跃订阅会优先列出。
page
number
分页的页码。默认为 1。
pageSize
number
每页的项目数。默认为 20。
返回
返回一个包含订阅对象列表的分页对象。
Name
Type
Description
count
number
与查询匹配的订阅总数。
list
object[]
一个订阅对象数组。
示例
import payment from '@blocklet/payment-js';

async function listActiveSubscriptions() {
  try {
    const subscriptions = await payment.subscriptions.list({
      order: 'updated_at:ASC', // 按更新时间排序
      activeFirst: true,       // 优先显示活跃订阅
      pageSize: 10,
    });
    console.log(`找到 ${subscriptions.count} 个订阅。`);
    subscriptions.list.forEach(sub => {
      console.log(`- ID: ${sub.id}，状态: ${sub.status}`);
    });
  } catch (error) {
    console.error('列出订阅时出错：', error.message);
  }
}

listActiveSubscriptions();响应示例
{
  "count": 1,
  "list": [
    {
      "id": "sub_xxx",
      "livemode": false,
      "currency_id": "pc_xxx",
      "customer_id": "cus_xxx",
      "current_period_end": 1731888000,
      "current_period_start": 1729209600,
      "status": "active",
      "billing_cycle_anchor": 1729209600,
      "collection_method": "charge_automatically",
      "start_date": 1729209600,
      "metadata": {}
    }
  ]
}检索订阅#使用其唯一 ID 获取特定订阅的详细信息。
参数
Name
Type
Description
id
string
要检索的订阅的唯一标识符。
返回
如果找到，则返回一个完整的订阅对象。
示例
import payment from '@blocklet/payment-js';

async function getSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.retrieve(subscriptionId);
    console.log('已检索到订阅：', subscription);
  } catch (error) {
    console.error('发生错误：', error.message);
  }
}

getSubscription('sub_xxx');响应示例
{
  "id": "sub_xxx",
  "livemode": false,
  "currency_id": "pc_xxx",
  "customer_id": "cus_xxx",
  "current_period_end": 1731888000,
  "current_period_start": 1729209600,
  "status": "active",
  "cancel_at_period_end": false,
  "billing_cycle_anchor": 1729209600,
  "collection_method": "charge_automatically",
  "start_date": 1729209600,
  "items": [
    {
      "id": "si_xxx",
      "price_id": "price_xxx",
      "quantity": 1
    }
  ]
}取消订阅#你可以立即取消订阅，也可以在当前计费周期结束时取消。
参数
Name
Type
Description
id
string
要取消的订阅的 ID。
body
object
包含取消选项的对象。详见下文。
取消选项 (body)
Name
Type
Description
at
string
何时执行取消操作。可以是 'now'（立即）、'current_period_end'（当前周期结束时）或 'custom'（自定义）。
time
number
如果 at 是 'custom'，则此项为必需。用于自定义取消时间的 Unix 时间戳。
reason
string
取消原因（例如 'cancellation_requested'）。
feedback
string
客户反馈（例如 'too_expensive'、'unused'）。
示例
import payment from '@blocklet/payment-js';

async function cancelSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.cancel(subscriptionId, {
      at: 'current_period_end', // 订阅将保持活跃状态，直到计费周期结束
      reason: 'cancellation_requested'
    });
    console.log('订阅已安排取消：', subscription.id);
    console.log('在周期结束时取消：', subscription.cancel_at_period_end);
  } catch (error) {
    console.error('取消订阅时出错：', error.message);
  }
}

cancelSubscription('sub_xxx');报告计量计费的使用情况#对于采用计量价格的订阅，你必须报告使用情况以便正确地向客户计费。使用情况是针对特定的 subscription_item_id 进行报告的。
使用情况报告流程#
PaymentKit APISDKPaymentKit APISDK你的应用payment.subscriptionItems.createUsageRecord(data)POST /api/usage-records 附带使用数据返回 UsageRecord 对象解析并返回 UsageRecord 对象汇总下次账单的使用情况你的应用

参数
Name
Type
Description
subscription_item_id
string
必需。 要报告使用情况的订阅项目的 ID。
quantity
number
必需。 要报告的使用量。
action
string
报告操作。使用 'increment' 将使用量添加到本周期的现有用量上，或使用 'set' 覆盖它。默认为 'increment'。
timestamp
number
使用情况发生时的 Unix 时间戳。默认为当前时间。
示例
import payment from '@blocklet/payment-js';

async function reportUsage(subscriptionItemId) {
  try {
    const usageRecord = await payment.subscriptionItems.createUsageRecord({
      subscription_item_id: subscriptionItemId,
      quantity: 100, // 报告 100 个单位的使用量（例如，API 调用）
      action: 'increment',
      timestamp: Math.floor(Date.now() / 1000)
    });
    console.log('使用情况报告成功：', usageRecord);
  } catch (error) {
    console.error('报告使用情况时出错：', error.message);
  }
}

// 将 'si_xxx' 替换为真实的订阅项目 ID
reportUsage('si_xxx');响应示例
{
  "id": "ur_xxx",
  "livemode": false,
  "quantity": 100,
  "subscription_item_id": "si_xxx",
  "timestamp": 1729243800
}
本指南概述了如何管理订阅。借助这些工具，你可以有效地处理循环支付和计量计费。
要获取所有与订阅相关的方法及其参数的完整列表，请参阅 订阅 API 参考 和 订阅项目 API 参考。
接下来，你可能希望通过阅读 信用计费 指南来学习如何实现基于信用的系统。

Name	Type	Description
`status`	`string`	按状态筛选订阅。选项包括 `active`、`past_due`、`paused`、`canceled`、`incomplete`、`incomplete_expired`、`trialing`。
`customer_id`	`string`	按客户的唯一 ID 筛选订阅。
`customer_did`	`string`	按客户的 DID 筛选订阅。
`metadata.{key}`	`string`	按自定义元数据字段筛选。
`order`	`string`	结果的排序顺序，例如 `'updated_at:ASC'` 或 `'created_at:DESC'`。
`activeFirst`	`boolean`	如果为 `true`，则活跃订阅会优先列出。
`page`	`number`	分页的页码。默认为 `1`。
`pageSize`	`number`	每页的项目数。默认为 `20`。

Name	Type	Description
`at`	`string`	何时执行取消操作。可以是 `'now'`（立即）、`'current_period_end'`（当前周期结束时）或 `'custom'`（自定义）。
`time`	`number`	如果 `at` 是 `'custom'`，则此项为必需。用于自定义取消时间的 Unix 时间戳。
`reason`	`string`	取消原因（例如 `'cancellation_requested'`）。
`feedback`	`string`	客户反馈（例如 `'too_expensive'`、`'unused'`）。

Name	Type	Description
`subscription_item_id`	`string`	必需。要报告使用情况的订阅项目的 ID。
`quantity`	`number`	必需。要报告的使用量。
`action`	`string`	报告操作。使用 `'increment'` 将使用量添加到本周期的现有用量上，或使用 `'set'` 覆盖它。默认为 `'increment'`。
`timestamp`	`number`	使用情况发生时的 Unix 时间戳。默认为当前时间。

概述

快速入门

核心概念

使用指南

API 参考

TypeScript 支持

订阅

订阅生命周期流程#

列出订阅#

检索订阅#

取消订阅#

报告计量计费的使用情况#

使用情况报告流程#

产品和价格

点数计费

Name	Type	Description
`count`	`number`	与查询匹配的订阅总数。
`list`	`object[]`	一个订阅对象数组。

Name	Type	Description
`id`	`string`	要取消的订阅的 ID。
`body`	`object`	包含取消选项的对象。详见下文。