Used to check for browser translation.
用于检测浏览器翻译。
ブラウザの翻訳を検出する
API 参考

订阅项目

订阅项目代表客户在某个较大订阅中订阅的特定产品或服务。它们将价格与订阅关联，并跟踪数量等详细信息。此 API 允许你单独管理这些项目，包括报告计量计费的使用量。

如需管理整个订阅，请参阅 订阅 API 文档。

订阅项目对象#

订阅项目对象包含订阅中产品的详细信息。

属性

类型

描述

id

string

订阅项目的唯一标识符。

livemode

boolean

如果对象存在于生产模式，则为 true；如果存在于测试模式，则为 false。

subscription_id

string

此项目所属订阅的 ID。

price_id

string

与此项目关联的价格的 ID。

quantity

number

订阅的价格数量。

metadata

object

可附加到对象的一组键值对。可用于存储附加信息。

billing_thresholds

object

基于使用量的计费阈值。包含 usage_gte。

created_at

date

对象创建时的时间戳。

updated_at

date

上次更新的时间戳。

检索时，price 对象将被展开。

创建订阅项目#

向现有订阅添加新项目。

参数

名称

类型

描述

subscription_id

string

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

price_id

string

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

quantity

number

价格的数量。默认为 1。

metadata

object

与项目关联的键值数据。

billing_thresholds

object

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

示例

import payment from '@blocklet/payment-js';

async function addSubscriptionItem() {
try {
const subscriptionItem = await payment.subscriptionItems.create({
subscription_id: 'sub_xxxxxxxxxxxxxx',
price_id: 'price_xxxxxxxxxxxxxx',
quantity: 2
});
console.log('已创建订阅项目：', subscriptionItem);
} catch (error) {
console.error('创建订阅项目时出错：', error.message);
}
}

addSubscriptionItem();

示例响应

{
"id": "si_xxxxxxxxxxxxxx",
"livemode": false,
"subscription_id": "sub_xxxxxxxxxxxxxx",
"price_id": "price_xxxxxxxxxxxxxx",
"quantity": 2,
"metadata": {},
"billing_thresholds": null,
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:00:00.000Z"
}

检索订阅项目#

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

参数

名称

类型

描述

id

string

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

示例

import payment from '@blocklet/payment-js';

async function getSubscriptionItem(itemId) {
try {
const subscriptionItem = await payment.subscriptionItems.retrieve(itemId);
console.log('已检索订阅项目：', subscriptionItem);
} catch (error) {
console.error('检索订阅项目时出错：', error.message);
}
}

getSubscriptionItem('si_xxxxxxxxxxxxxx');

示例响应（已展开）

{
"id": "si_xxxxxxxxxxxxxx",
"livemode": false,
"subscription_id": "sub_xxxxxxxxxxxxxx",
"price_id": "price_xxxxxxxxxxxxxx",
"price": {
"id": "price_xxxxxxxxxxxxxx",
"product_id": "prod_xxxxxxxxxxxxxx",
"active": true,
"type": "recurring",
"unit_amount": "1000",
"currency_id": "usd",
"recurring": {
"interval": "month",
"interval_count": 1
}
},
"quantity": 2,
"metadata": {},
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:00:00.000Z"
}

更新订阅项目#

更新订阅项目的参数。

参数

名称

类型

描述

id

string

必需。 要更新的订阅项目的标识符。

quantity

number

项目的新数量。

price_id

string

项目的新价格 ID。

metadata

object

新的一组键值数据。

示例

import payment from '@blocklet/payment-js';

async function updateSubscriptionItem(itemId) {
try {
const updatedItem = await payment.subscriptionItems.update(itemId, {
quantity: 3
});
console.log('已更新订阅项目：', updatedItem);
} catch (error) {
console.error('更新订阅项目时出错：', error.message);
}
}

updateSubscriptionItem('si_xxxxxxxxxxxxxx');

示例响应

{
"id": "si_xxxxxxxxxxxxxx",
"livemode": false,
"subscription_id": "sub_xxxxxxxxxxxxxx",
"price_id": "price_xxxxxxxxxxxxxx",
"quantity": 3,
"metadata": {},
"billing_thresholds": null,
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:05:00.000Z"
}

列出订阅项目#

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

参数

名称

类型

描述

subscription_id

string

必需。 要检索其项目的订阅的 ID。

page

number

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

pageSize

number

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

order

string

表示结果顺序的字符串（例如：'created_at:ASC'）。

示例

import payment from '@blocklet/payment-js';

async function listSubscriptionItems(subscriptionId) {
try {
const items = await payment.subscriptionItems.list({
subscription_id: subscriptionId,
pageSize: 5
});
console.log(`找到 ${items.count} 个项目：`, items.list);
} catch (error) {
console.error('列出订阅项目时出错：', error.message);
}
}

listSubscriptionItems('sub_xxxxxxxxxxxxxx');

示例响应

{
"count": 1,
"list": [
{
"id": "si_xxxxxxxxxxxxxx",
"livemode": false,
"subscription_id": "sub_xxxxxxxxxxxxxx",
"price_id": "price_xxxxxxxxxxxxxx",
"quantity": 3,
"metadata": {},
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:05:00.000Z"
}
]
}

删除订阅项目#

从订阅中删除一个项目。此操作通常不可逆。

参数

名称

类型

描述

id

string

要删除的订阅项目的标识符。

示例

import payment from '@blocklet/payment-js';

async function deleteSubscriptionItem(itemId) {
try {
const deletedItem = await payment.subscriptionItems.del(itemId);
console.log('已删除订阅项目：', deletedItem);
} catch (error) {
console.error('删除订阅项目时出错：', error.message);
}
}

deleteSubscriptionItem('si_xxxxxxxxxxxxxx');

示例响应

{
"id": "si_xxxxxxxxxxxxxx",
"livemode": false,
"subscription_id": "sub_xxxxxxxxxxxxxx",
"price_id": "price_xxxxxxxxxxxxxx",
"quantity": 3,
"metadata": {},
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:05:00.000Z"
}

创建使用量记录#

为计量计费的订阅项目创建使用量记录。这用于报告将在周期结束时计费的使用量。

参数

名称

类型

描述

subscription_item_id

string

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

quantity

number

必需。 要报告的使用量。

action

string

可以是 'increment' 以增加到现有使用量，或 'set' 以覆盖它。默认为 'increment'。

timestamp

number

使用量事件的时间戳。默认为当前时间。

示例

import payment from '@blocklet/payment-js';

async function reportUsage(itemId) {
try {
const usageRecord = await payment.subscriptionItems.createUsageRecord({
subscription_item_id: itemId,
quantity: 100,
action: 'increment'
});
console.log('已创建使用量记录：', usageRecord);
} catch (error) {
console.error('创建使用量记录时出错：', error.message);
}
}

reportUsage('si_metered_xxxxxxxx');

示例响应

{
"id": "ur_xxxxxxxxxxxxxx",
"livemode": false,
"quantity": 100,
"subscription_item_id": "si_metered_xxxxxxxx",
"timestamp": 1672531200
}

列出使用量记录摘要#

对于给定的订阅项目，返回摘要对象列表。列表中的每个对象都包含特定时期内报告的总使用量。

参数

名称

类型

描述

subscription_item_id

string

必需。 订阅项目的 ID。

page

number

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

pageSize

number

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

order

string

表示结果顺序的字符串。

示例

import payment from '@blocklet/payment-js';

async function getUsageSummaries(itemId) {
try {
const summaries = await payment.subscriptionItems.listUsageRecordSummaries({
subscription_item_id: itemId
});
console.log('使用量摘要：', summaries);
} catch (error) {
console.error('列出使用量摘要时出错：', error.message);
}
}

getUsageSummaries('si_metered_xxxxxxxx');

示例响应

{
"count": 1,
"list": [
{
"id": "si_metered_xxxxxxxx",
"total_usage": 5000
}
]
}


现在你已掌握了管理订阅中单个项目的工具。要处理与支付相关的事件，请继续阅读 Webhooks 文档。

previous
订阅
next
Webhooks