价格 | ArcBlock

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,
        usage_type: 'licensed'
      },
      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 值。