价格

Price 对象定义了特定产品的收费金额和频率。它将价格金额和货币与 产品 相关联。例如，一个产品可以有多个价格，每个价格使用不同的货币或计费周期。
本文档详细介绍了如何使用 SDK 管理 Price 对象。
Price 对象#Price 对象包含有关产品定价模型的所有详细信息。
Attribute
Type
Description
id
string
价格对象的唯一标识符。
product_id
string
此价格关联的产品 ID。
product
object
展开后的 Product 对象。
active
boolean
该价格是否可用于新购买。
currency_id
string
此价格的默认货币 ID。
currency
object
展开后的 PaymentCurrency 对象。
nickname
string
价格的简要描述，会向客户显示。
type
string
one_time 或 recurring 之一。
unit_amount
string
以最小货币单位表示的价格（例如，美元的美分）。
recurring
object
对于周期性价格，此哈希包含计费周期信息。详见下文。
lookup_key
string
用户定义的用于检索价格的唯一键。
metadata
object
可附加到对象上的一组键值对。
currency_options
array
为多种货币指定不同的定价。
quantity_available
number
此价格的总可用数量。0 表示无限制。
quantity_sold
number
已售出的单位数量。
quantity_limit_per_checkout
number
客户在单次结账中可以购买的最大数量。0 表示无限制。
upsell
object
用于增销至另一价格的配置。
recurring 对象的属性
Attribute
Type
Description
interval
string
订阅的计费频率。day、week、month 或 year 之一。
interval_count
number
订阅计费之间的间隔数。
meter_id
string
用于按使用量计费的计量器 ID。
创建价格#为现有产品创建一个新价格。
创建价格
async function createPrice() {
  try {
    const price = await payment.prices.create({
      product_id: 'prod_xxxxxxxxxxxxxx',
      unit_amount: 1500, // 例如，$15.00
      currency_id: 'usd_xxxxxxxxxxxxxx',
      type: 'recurring',
      recurring: {
        interval: 'month',
        interval_count: 1,
      },
      nickname: 'Monthly Pro Plan',
      lookup_key: 'pro_monthly_usd',
    });
    console.log('价格已创建：', price);
  } catch (error) {
    console.error('创建价格时出错：', error.message);
  }
}

createPrice();
参数#Name
Type
Description
product_id
string
必需。 此价格所属的产品的 ID。
unit_amount
number
必需。 要收取的金额，以最小货币单位表示。
currency_id
string
必需。 此价格的货币 ID。
type
string
定价类型。可以是 one_time 或 recurring。默认为 one_time。
active
boolean
价格是否有效。默认为 true。
nickname
string
价格的内部名称。
lookup_key
string
用于引用价格的唯一字符串。
recurring
object
包含周期性计费信息的对象。如果 type 为 recurring，则此项为必需。
currency_options
array
一个对象数组，用于指定不同货币的价格。
metadata
object
与价格一同存储的键值数据。
quantity_available
number
总可用数量。默认为 0 (无限制)。
quantity_limit_per_checkout
number
每次结账的最大数量。默认为 0 (无限制)。
返回值#返回新创建的 Price 对象。
Response
{
  "id": "price_xxxxxxxxxxxxxx",
  "product_id": "prod_xxxxxxxxxxxxxx",
  "active": true,
  "currency_id": "usd_xxxxxxxxxxxxxx",
  "nickname": "Monthly Pro Plan",
  "type": "recurring",
  "unit_amount": "1500",
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "meter_id": null
  },
  "lookup_key": "pro_monthly_usd",
  "metadata": {},
  "product": {
    "id": "prod_xxxxxxxxxxxxxx",
    "name": "Pro Plan"
  },
  "currency": {
    "id": "usd_xxxxxxxxxxxxxx",
    "name": "United States Dollar"
  }
}
检索价格#检索现有价格的详细信息。
检索价格
async function retrievePrice(priceId) {
  try {
    const price = await payment.prices.retrieve(priceId);
    console.log('已检索到价格：', price);
  } catch (error) {
    console.error('检索价格时出错：', error.message);
  }
}

retrievePrice('price_xxxxxxxxxxxxxx');
参数#Name
Type
Description
id
string
必需。 要检索的价格的唯一标识符。也可以是 lookup_key。
返回值#返回请求的 Price 对象。
更新价格#通过设置传入参数的值来更新现有价格。
更新价格
async function updatePrice(priceId) {
  try {
    const price = await payment.prices.update(priceId, {
      nickname: 'Updated Pro Plan Nickname',
      metadata: { order_id: '6735' },
    });
    console.log('价格已更新：', price);
  } catch (error) {
    console.error('更新价格时出错：', error.message);
  }
}

updatePrice('price_xxxxxxxxxxxxxx');
参数#Name
Type
Description
id
string
必需。 要更新的价格的 ID。也可以是 lookup_key。
updates
object
包含要更新字段的对象。可更新字段列表请参见创建方法。注意：如果价格已被使用（locked），则无法更改 unit_amount 和 recurring 等核心属性。
返回值#返回更新后的 Price 对象。
列出所有价格#返回您的价格列表。价格按创建日期排序返回，最新创建的价格排在最前面。
列出价格
async function listPrices() {
  try {
    const prices = await payment.prices.list({
      product_id: 'prod_xxxxxxxxxxxxxx',
      active: true,
      limit: 5,
    });
    console.log('已检索到的价格：', prices.list);
  } catch (error) {
    console.error('列出价格时出错：', error.message);
  }
}

listPrices();
参数#Name
Type
Description
active
boolean
仅返回具有此活动状态的价格。
type
string
仅返回此类型的价格，例如 recurring。
currency_id
string
仅返回此货币 ID 的价格。
product_id
string
仅返回此产品 ID 的价格。
lookup_key
string
仅返回具有此查找键的价格。
page
number
用于分页的页码。默认为 1。
pageSize
number
每页的项目数。默认为 20。
返回值#返回一个分页对象，其中包含 Price 对象 list、总 count 和 paging 信息。
搜索价格#搜索与查询字符串匹配的价格。
搜索价格
async function searchPrices() {
  try {
    const prices = await payment.prices.search({ query: 'Pro Plan' });
    console.log('搜索结果：', prices.list);
  } catch (error) {
    console.error('搜索价格时出错：', error.message);
  }
}

searchPrices();
参数#Name
Type
Description
query
string
搜索查询字符串。
page
number
用于分页的页码。默认为 1。
pageSize
number
每页的项目数。默认为 20。
返回值#返回一个分页对象，其中包含匹配的 Price 对象 list。
归档价格#归档一个价格，以防止其在新的结账中使用。如果一个价格已被使用，通常归档它比删除它更好。
归档价格
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');
参数#Name
Type
Description
id
string
必需。 要归档的价格的 ID。也可以是 lookup_key。
返回值#返回已归档的 Price 对象，其 active 设置为 false。
删除价格#永久删除一个价格。此操作无法撤销。如果价格已在交易中使用或因其他原因被锁定，则无法删除。
删除价格
async function deletePrice(priceId) {
  try {
    const deletedPrice = await payment.prices.del(priceId);
    console.log('价格已删除：', deletedPrice.id);
  } catch (error) {
    console.error('删除价格时出错：', error.message);
  }
}

deletePrice('price_xxxxxxxxxxxxxx');
参数#Name
Type
Description
id
string
必需。 要删除的价格的 ID。也可以是 lookup_key。
返回值#返回已删除的 Price 对象。
更新库存#手动调整价格的 quantity_sold。这对于在标准结账流程之外跟踪库存很有用。
更新库存
async function updateInventory(priceId) {
  try {
    // 将已售数量增加 2
    const price = await payment.prices.inventory(priceId, {
      quantity: 2,
      action: 'increment',
    });
    console.log('库存已更新。新的已售数量：', price.quantity_sold);
  } catch (error) {
    console.error('更新库存时出错：', error.message);
  }
}

updateInventory('price_xxxxxxxxxxxxxx');
参数#Name
Type
Description
id
string
必需。 价格的 ID。
params
object
包含库存调整详细信息的对象。
params 对象的属性
Name
Type
Description
quantity
number
必需。 调整已售数量的金额。
action
string
必需。 调整操作。必须是 increment 或 decrement。
返回值#返回更新后的 Price 对象，其中包含新的 quantity_sold 值。

Name	Type	Description
`product_id`	string	必需。此价格所属的产品的 ID。
`unit_amount`	number	必需。要收取的金额，以最小货币单位表示。
`currency_id`	string	必需。此价格的货币 ID。
`type`	string	定价类型。可以是 `one_time` 或 `recurring`。默认为 `one_time`。
`active`	boolean	价格是否有效。默认为 `true`。
`nickname`	string	价格的内部名称。
`lookup_key`	string	用于引用价格的唯一字符串。
`recurring`	object	包含周期性计费信息的对象。如果 `type` 为 `recurring`，则此项为必需。
`currency_options`	array	一个对象数组，用于指定不同货币的价格。
`metadata`	object	与价格一同存储的键值数据。
`quantity_available`	number	总可用数量。默认为 `0` (无限制)。
`quantity_limit_per_checkout`	number	每次结账的最大数量。默认为 `0` (无限制)。

概述

快速入门

SDK 结构

环境

核心概念

API 参考

价格

Price 对象#

创建价格#

参数#

返回值#

检索价格#

参数#

返回值#

更新价格#

参数#

返回值#

列出所有价格#

参数#

返回值#

搜索价格#

参数#

返回值#

归档价格#

参数#

返回值#

删除价格#

参数#

返回值#

更新库存#

参数#

返回值#

支付方式

产品

Attribute	Type	Description
`id`	string	价格对象的唯一标识符。
`product_id`	string	此价格关联的产品 ID。
`product`	object	展开后的 Product 对象。
`active`	boolean	该价格是否可用于新购买。
`currency_id`	string	此价格的默认货币 ID。
`currency`	object	展开后的 PaymentCurrency 对象。
`nickname`	string	价格的简要描述，会向客户显示。
`type`	string	`one_time` 或 `recurring` 之一。
`unit_amount`	string	以最小货币单位表示的价格（例如，美元的美分）。
`recurring`	object	对于周期性价格，此哈希包含计费周期信息。详见下文。
`lookup_key`	string	用户定义的用于检索价格的唯一键。
`metadata`	object	可附加到对象上的一组键值对。
`currency_options`	array	为多种货币指定不同的定价。
`quantity_available`	number	此价格的总可用数量。`0` 表示无限制。
`quantity_sold`	number	已售出的单位数量。
`quantity_limit_per_checkout`	number	客户在单次结账中可以购买的最大数量。`0` 表示无限制。
`upsell`	object	用于增销至另一价格的配置。

Attribute	Type	Description
`interval`	string	订阅的计费频率。`day`、`week`、`month` 或 `year` 之一。
`interval_count`	number	订阅计费之间的间隔数。
`meter_id`	string	用于按使用量计费的计量器 ID。

Name	Type	Description
`id`	string	必需。要更新的价格的 ID。也可以是 `lookup_key`。
`updates`	object	包含要更新字段的对象。可更新字段列表请参见创建方法。注意：如果价格已被使用（`locked`），则无法更改 `unit_amount` 和 `recurring` 等核心属性。

Name	Type	Description
`active`	boolean	仅返回具有此活动状态的价格。
`type`	string	仅返回此类型的价格，例如 `recurring`。
`currency_id`	string	仅返回此货币 ID 的价格。
`product_id`	string	仅返回此产品 ID 的价格。
`lookup_key`	string	仅返回具有此查找键的价格。
`page`	number	用于分页的页码。默认为 `1`。
`pageSize`	number	每页的项目数。默认为 `20`。

Name	Type	Description
`query`	string	搜索查询字符串。
`page`	number	用于分页的页码。默认为 `1`。
`pageSize`	number	每页的项目数。默认为 `20`。

Name	Type	Description
`id`	string	必需。价格的 ID。
`params`	object	包含库存调整详细信息的对象。

Name	Type	Description
`quantity`	number	必需。调整已售数量的金额。
`action`	string	必需。调整操作。必须是 `increment` 或 `decrement`。