API 参考

价格

价格代表了产品的成本及其计费方式。一个产品可以有多个价格，以支持不同的货币、计费周期（一次性与周期性）和定价模型（按单位与分级）。此 API 允许你创建和管理这些定价模型。
在创建价格之前，你必须先有一个与之关联的产品。
有一个或多个
可以是
可以是
用于
定义
产品
价格
一次性
周期性
结账会话
计费周期

价格对象#Price 对象包含有关产品特定定价配置的所有详细信息。扩展版本 TPriceExpanded 还包含完整的产品和货币对象。
属性
类型
描述
id
string
价格的唯一标识符。
product_id
string
此价格所属产品的 ID。
nickname
string
价格的内部名称。
active
boolean
该价格是否可用于新的结账。
type
`'one_time'
'recurring'`
billing_scheme
`'per_unit'
'tiered'`
unit_amount
string
以最小货币单位表示的单位金额（例如，美元的美分）。
recurring
object
周期性价格的详细信息。请参阅下方的 PriceRecurring 类型。
tiers
array
对于分级计费，指其分级结构。
currency_id
string
三字母 ISO 货币代码。
quantity_available
number
此价格的可用数量。如果无限，则为 Null。
product
object
（扩展）完整的产品对象。
currency
object
（扩展）完整的支付货币对象。
PriceRecurring 对象#属性
类型
描述
interval
`'hour'
'day'
interval_count
number
订阅计费之间的间隔数。
usage_type
`'licensed'
'metered'`
创建价格#创建一个新价格并将其与一个产品关联。
参数
参数
类型
描述
product_id
string
必填。 此价格所属产品的 ID。
unit_amount
string
必填。 一个以最小货币单位表示的正整数，代表收费金额。
currency_id
string
必填。 此价格所用货币的 ID。
type
`'one_time'
'recurring'`
nickname
string
价格的简要描述，对客户不可见。
active
boolean
价格是否对新购买激活。默认为 true。
recurring
object
如果 type 是 recurring，则此项为必填。一个包含 interval 和 interval_count 的对象。
billing_scheme
`'per_unit'
'tiered'`
lookup_key
string
一个用户定义的唯一键，可用于检索价格。
quantity_available
number
此价格的初始可用数量。
示例
import payment from '@blocklet/payment-js';

async function createRecurringPrice() {
  try {
    const price = await payment.prices.create({
      product_id: 'prod_xxxxxxxxxxxxxx',
      nickname: 'Standard Monthly Plan',
      unit_amount: '2000', // 例如，$20.00
      currency_id: 'cur_xxxxxxxxxxxxxx', // 对应美元
      type: 'recurring',
      recurring: {
        interval: 'month',
        interval_count: 1,
      },
    });
    console.log('价格已创建：', price);
  } catch (error) {
    console.error('创建价格时出错：', error.message);
  }
}

createRecurringPrice();示例响应
{
  "id": "price_xxxxxxxxxxxxxx",
  "object": "price",
  "product_id": "prod_xxxxxxxxxxxxxx",
  "nickname": "Standard Monthly Plan",
  "active": true,
  "livemode": false,
  "type": "recurring",
  "billing_scheme": "per_unit",
  "unit_amount": "2000",
  "recurring": {
    "interval": "month",
    "interval_count": 1
  },
  "currency_id": "cur_xxxxxxxxxxxxxx",
  "product": {
    "id": "prod_xxxxxxxxxxxxxx",
    "name": "My SaaS Product"
  },
  "currency": {
    "id": "cur_xxxxxxxxxxxxxx",
    "name": "US Dollar"
  }
}检索价格#检索现有价格的详细信息。
参数
参数
类型
描述
id
string
必填。 要检索的价格的唯一标识符。
示例
import payment from '@blocklet/payment-js';

async function getPrice(priceId) {
  try {
    const price = await payment.prices.retrieve(priceId);
    console.log('检索到的价格：', price.nickname);
  } catch (error) {
    console.error('检索价格时出错：', error.message);
  }
}

getPrice('price_xxxxxxxxxxxxxx');示例响应
{
  "id": "price_xxxxxxxxxxxxxx",
  "object": "price",
  "product_id": "prod_xxxxxxxxxxxxxx",
  "nickname": "Standard Monthly Plan",
  "active": true,
  "type": "recurring",
  "unit_amount": "2000",
  "currency_id": "cur_xxxxxxxxxxxxxx"
}更新价格#通过设置传入参数的值来更新指定的价格。
参数
参数
类型
描述
id
string
必填。 要更新的价格的 ID。
nickname
string
价格的简要描述。
active
boolean
价格是否激活。
lookup_key
string
一个用户定义的唯一键。
metadata
object
一组与对象一同存储的键值对。
示例
import payment from '@blocklet/payment-js';

async function updatePrice(priceId) {
  try {
    const price = await payment.prices.update(priceId, {
      nickname: 'Updated Standard Plan Name',
    });
    console.log('价格更新成功：', price.id);
  } catch (error) {
    console.error('更新价格时出错：', error.message);
  }
}

updatePrice('price_xxxxxxxxxxxxxx');列出所有价格#返回你的价格列表。价格按创建日期排序返回，最新创建的价格排在最前面。
参数
参数
类型
描述
active
boolean
仅返回激活的价格。
type
`'one_time'
'recurring'`
currency_id
string
仅返回指定货币的价格。
product_id
string
仅返回指定产品的价格。
lookup_key
string
仅返回具有此查找键的价格。
page
number
用于分页的页码。
pageSize
number
每页的项目数。默认为 20。
order
array
结果的排序顺序。
示例
import payment from '@blocklet/payment-js';

async function listPrices() {
  try {
    const priceList = await payment.prices.list({
      product_id: 'prod_xxxxxxxxxxxxxx',
      active: true,
      pageSize: 5,
    });
    console.log('检索到的价格：', priceList.list);
  } catch (error) {
    console.error('列出价格时出错：', error.message);
  }
}

listPrices();示例响应
{
  "count": 1,
  "list": [
    {
      "id": "price_xxxxxxxxxxxxxx",
      "object": "price",
      "product_id": "prod_xxxxxxxxxxxxxx",
      "nickname": "Standard Monthly Plan",
      "active": true,
      "type": "recurring",
      "unit_amount": "2000"
    }
  ]
}更新库存#增加或减少某个价格的 quantity_available。这对于管理库存水平很有用。
参数
参数
类型
描述
id
string
必填。 要更新库存的价格的 ID。
quantity
number
必填。 调整库存的数量。可为正数或负数。
action
`'increment'
'decrement'`
示例
import payment from '@blocklet/payment-js';

async function decrementInventory(priceId) {
  try {
    const price = await payment.prices.inventory(priceId, {
      quantity: 1,
      action: 'decrement',
    });
    console.log('库存已更新。新的可用数量：', price.quantity_available);
  } catch (error) {
    console.error('更新库存时出错：', error.message);
  }
}

decrementInventory('price_xxxxxxxxxxxxxx');归档价格#停用一个价格，以防止其在新的结账中使用。使用此价格的现有订阅不受影响。
参数
参数
类型
描述
id
string
必填。 要归档的价格的 ID。
示例
import payment from '@blocklet/payment-js';

async function archivePrice(priceId) {
  try {
    const price = await payment.prices.archive(priceId);
    console.log(`价格 ${price.id} 已归档。激活状态：${price.active}`);
  } catch (error) {
    console.error('归档价格时出错：', error.message);
  }
}

archivePrice('price_xxxxxxxxxxxxxx');删除价格#永久删除一个价格。此操作无法撤销。
参数
参数
类型
描述
id
string
必填。 要删除的价格的 ID。
示例
import payment from '@blocklet/payment-js';

async function deletePrice(priceId) {
  try {
    const result = await payment.prices.del(priceId);
    console.log(`价格 ${result.id} 已成功删除。`);
  } catch (error) {
    console.error('删除价格时出错：', error.message);
  }
}

deletePrice('price_xxxxxxxxxxxxxx');
在配置好产品和价格后，你现在可以创建交易了。在结账会话指南中了解更多关于如何创建面向客户的支付页面的信息。

属性	类型	描述
`id`	`string`	价格的唯一标识符。
`product_id`	`string`	此价格所属产品的 ID。
`nickname`	`string`	价格的内部名称。
`active`	`boolean`	该价格是否可用于新的结账。
`type`	`'one_time'	'recurring'`
`billing_scheme`	`'per_unit'	'tiered'`
`unit_amount`	`string`	以最小货币单位表示的单位金额（例如，美元的美分）。
`recurring`	`object`	周期性价格的详细信息。请参阅下方的 `PriceRecurring` 类型。
`tiers`	`array`	对于分级计费，指其分级结构。
`currency_id`	`string`	三字母 ISO 货币代码。
`quantity_available`	`number`	此价格的可用数量。如果无限，则为 Null。
`product`	`object`	（扩展）完整的产品对象。
`currency`	`object`	（扩展）完整的支付货币对象。

参数	类型	描述
`product_id`	`string`	必填。此价格所属产品的 ID。
`unit_amount`	`string`	必填。一个以最小货币单位表示的正整数，代表收费金额。
`currency_id`	`string`	必填。此价格所用货币的 ID。
`type`	`'one_time'	'recurring'`
`nickname`	`string`	价格的简要描述，对客户不可见。
`active`	`boolean`	价格是否对新购买激活。默认为 `true`。
`recurring`	`object`	如果 `type` 是 `recurring`，则此项为必填。一个包含 `interval` 和 `interval_count` 的对象。
`billing_scheme`	`'per_unit'	'tiered'`
`lookup_key`	`string`	一个用户定义的唯一键，可用于检索价格。
`quantity_available`	`number`	此价格的初始可用数量。

参数	类型	描述
`id`	`string`	必填。要更新的价格的 ID。
`nickname`	`string`	价格的简要描述。
`active`	`boolean`	价格是否激活。
`lookup_key`	`string`	一个用户定义的唯一键。
`metadata`	`object`	一组与对象一同存储的键值对。

参数	类型	描述
`active`	`boolean`	仅返回激活的价格。
`type`	`'one_time'	'recurring'`
`currency_id`	`string`	仅返回指定货币的价格。
`product_id`	`string`	仅返回指定产品的价格。
`lookup_key`	`string`	仅返回具有此查找键的价格。
`page`	`number`	用于分页的页码。
`pageSize`	`number`	每页的项目数。默认为 20。
`order`	`array`	结果的排序顺序。

参数	类型	描述
`id`	`string`	必填。要更新库存的价格的 ID。
`quantity`	`number`	必填。调整库存的数量。可为正数或负数。
`action`	`'increment'	'decrement'`

概述

快速入门

核心概念

使用指南

API 参考

TypeScript 支持

价格

价格对象#

`PriceRecurring` 对象#

创建价格#

检索价格#

更新价格#

列出所有价格#

更新库存#

归档价格#

删除价格#

产品

支付意图

属性	类型	描述
`interval`	`'hour'	'day'
`interval_count`	`number`	订阅计费之间的间隔数。
`usage_type`	`'licensed'	'metered'`