订阅项目

订阅项目代表客户订阅的特定产品和价格。它们是订阅的组成部分，对于管理循环计费至关重要，特别是对于按使用量计费的计划。

该 API 允许您创建、检索、更新和删除订阅项目。关键的是，它还提供了报告计量计费使用情况的方法。

订阅项目对象#

订阅项目对象包含有关订阅中特定项目的详细信息。

The TSubscriptionItemExpanded Object

interface TSubscriptionItemExpanded {
  id: string; // 订阅项目的唯一标识符
  subscription_id: string; // 此项目所属的订阅 ID
  price_id: string; // 与此项目关联的价格 ID
  quantity: number; // 价格的数量
  billing_thresholds: object | null; // 基于使用量的计费阈值
  metadata: object | null; // 用于附加信息的键值对集合
  created_at: number; // 创建时的时间戳
  updated_at: number; // 最后更新的时间戳
  price: TPrice; // 展开的价格对象
}

创建订阅项目#

向现有订阅添加一个新项目（产品和价格）。

Create Subscription Item

const subscriptionItem = await payment.subscriptionItems.create({
  subscription_id: 'sub_xxxxxxxxxxxxxx',
  price_id: 'price_xxxxxxxxxxxxxx',
  quantity: 1,
});

参数

Name

Type

Description

subscription_id

string

必需。 要将此项目添加到的订阅的 ID。

price_id

string

必需。 客户要订阅的价格的 ID。

quantity

number

价格的数量。默认为 1。

billing_thresholds

object

此项目基于使用量的计费阈值。

metadata

object

您可以附加到对象的一组键值对。这对于以结构化格式存储有关对象的附加信息很有用。

返回

返回新创建的 TSubscriptionItem 对象。

检索订阅项目#

检索现有订阅项目的详细信息。

Retrieve Subscription Item

const subscriptionItem = await payment.subscriptionItems.retrieve(
  'si_xxxxxxxxxxxxxx' // 订阅项目 ID
);

参数

Name

Type

Description

id

string

必需。 要检索的订阅项目的唯一标识符。

返回

如果提供了有效的 ID，则返回一个 TSubscriptionItemExpanded 对象。

更新订阅项目#

更新订阅项目的属性。您可以更新 price_id、quantity 和 metadata。

Update Subscription Item

const subscriptionItem = await payment.subscriptionItems.update(
  'si_xxxxxxxxxxxxxx', // 订阅项目 ID
  {
    quantity: 2,
  }
);

参数

Name

Type

Description

id

string

必需。 要更新的订阅项目的 ID。

updates

object

一个包含要更新字段的对象。

可更新字段

Name

Type

Description

price_id

string

此项目的新价格的 ID。

quantity

number

此项目的新数量。

billing_thresholds

object

此项目基于使用量的计费阈值。

metadata

object

要更新的一组键值对。

返回

返回更新后的 TSubscriptionItem 对象。

列出订阅项目#

返回给定订阅的订阅项目列表。

List Subscription Items

const subscriptionItems = await payment.subscriptionItems.list({
  subscription_id: 'sub_xxxxxxxxxxxxxx',
});

参数

Name

Type

Description

subscription_id

string

必需。 您想要列出其项目的订阅的 ID。

page

number

用于分页的页码。默认为 1。

pageSize

number

每页返回的项目数。默认为 20。

返回

一个分页的 TSubscriptionItemExpanded 对象列表。

删除订阅项目#

从订阅中删除一个项目。这是一个永久性操作。

Delete Subscription Item

const deletedItem = await payment.subscriptionItems.del(
  'si_xxxxxxxxxxxxxx', // 订阅项目 ID
  {
    clear_usage: true, // 可选
  }
);

参数

Name

Type

Description

id

string

必需。 要删除的订阅项目的 ID。

body.clear_usage

boolean

如果为 true，计量价格的所有使用记录都将被清除。默认为 false。

返回

返回已删除的 TSubscriptionItem 对象。

创建使用记录#

对于 metered 价格，您必须报告使用情况以正确地向客户计费。此方法为指定的订阅项目创建一条使用记录。

Create Usage Record

const usageRecord = await payment.subscriptionItems.createUsageRecord({
  subscription_item_id: 'si_xxxxxxxxxxxxxx',
  quantity: 100,
  action: 'increment',
  timestamp: Math.floor(Date.now() / 1000),
});

参数

Name

Type

Description

subscription_item_id

string

必需。 要报告使用情况的订阅项目的 ID。

quantity

number

必需。 要报告的使用数量。必须是正整数。

action

string

确定如何应用报告的 quantity。可以是 increment（增加到现有使用量）或 set（在给定时间戳覆盖使用量）。默认为 increment。

timestamp

number

使用事件的 UNIX 时间戳。必须在当前计费周期内。默认为当前时间。

返回

返回创建的 TUsageRecord 对象。

列出使用记录摘要#

对于给定的订阅项目，返回按计费周期（发票）汇总的使用记录摘要列表。

List Usage Record Summaries

const summaries = await payment.subscriptionItems.listUsageRecordSummaries({
  subscription_item_id: 'si_xxxxxxxxxxxxxx',
});

参数

Name

Type

Description

subscription_item_id

string

必需。 订阅项目的 ID。

page

number

用于分页的页码。默认为 1。

pageSize

number

每页返回的项目数。默认为 20。

返回

一个分页的 TUsageRecordSummary 对象列表。

The TUsageRecordSummary Object

interface TUsageRecordSummary {
  invoice_id: string; // 此期间发票的 ID
  subscription_item_id: string;
  total_usage: number; // 此期间的总使用量
  period: {
    start: number; // 计费周期开始（UNIX 时间戳）
    end: number; // 计费周期结束（UNIX 时间戳）
  };
}

列出使用记录#

检索订阅项目的单个使用记录列表。这提供了所有报告使用情况的详细、非聚合视图。

List Usage Records

const records = await payment.subscriptionItems.listUsageRecords({
  subscription_item_id: 'si_xxxxxxxxxxxxxx',
});

参数

Name

Type

Description

subscription_item_id

string

必需。 订阅项目的 ID。

start

number

一个 UNIX 时间戳，用于筛选此时间之后的使用记录。

end

number

一个 UNIX 时间戳，用于筛选此时间之前或此时的使用记录。

page

number

用于分页的页码。默认为 1。

pageSize

number

每页返回的项目数。默认为 20。

返回

一个分页的 TUsageRecord 对象列表。

The TUsageRecord Object

interface TUsageRecord {
  id: string;
  subscription_item_id: string;
  quantity: number;
  timestamp: number; // 记录的 UNIX 时间戳
  billed: boolean; // 此使用情况是否已计费
}
设置
订阅