产品 | ArcBlock

产品对象代表您向客户提供的商品、服务或数字信用。您可以将它们视为目录中的项目。每个产品可以有一个或多个相关联的价格。

此 API 允许您以编程方式创建和管理您的产品目录。

有关管理这些产品的成本和计费方案的详细信息，请参阅价格 API 参考。

产品对象

产品对象包含有关您销售的单个项目的详细信息。

属性	类型	描述
`id`	`string`	产品对象的唯一标识符。
`name`	`string`	产品的名称，旨在向客户显示。
`type`	`string`	产品的类型。可以是 `service`、`good` 或 `credit`。默认为 `service`。
`active`	`boolean`	产品当前是否可供购买。
`description`	`string`	您可用于描述产品的任意字符串。
`images`	`string[]`	产品图片的 URL 字符串列表。
`metadata`	`object`	可以附加到对象的键值对集合。用于存储附加信息。
`statement_descriptor`	`string`	一个可选的描述符，会显示在客户的信用卡账单上。
`unit_label`	`string`	表示此产品单个单位的标签（例如，“用户”、“许可证”）。
`nft_factory`	`string`	如果产品链接到 NFT，则为 NFT 工厂的地址。
`features`	`object[]`	与产品关联的功能列表。每个功能对象都有一个 `name` 属性。
`prices`	`Price[]`	与此产品关联的价格对象列表。仅在检索单个产品或在展开列表中时包含。
`default_price_id`	`string`	此产品的默认价格 ID。
`created_at`	`string`	对象创建时的时间戳。
`updated_at`	`string`	最后更新的时间戳。

创建产品

创建一个新的产品对象。您也可以同时为该产品创建一个或多个价格。

Create Product

const product = await payment.products.create({
  name: 'Premium Subscription',
  description: 'Monthly access to premium features.',
  type: 'service',
  prices: [
    {
      unit_amount: 1500, // e.g., 15.00 USD
      currency_id: 'usd_xxxx',
      type: 'recurring',
      recurring: {
        interval: 'month',
        interval_count: 1,
        usage_type: 'licensed'
      },
    },
  ],
});

参数

Name	Type	Description
`name`	`string`	必需。产品的名称。
`type`	`string`	产品类型。`service`、`good` 或 `credit` 之一。默认为 `service`。
`description`	`string`	一个可选的、面向用户的产品描述。
`images`	`string[]`	产品图片的 URL 列表。
`metadata`	`object`	与产品一起存储的键值数据。
`statement_descriptor`	`string`	信用卡账单的简短描述符。必须至少包含一个字母，且不能包含 `<`、`>`、`"`、`’` 或 `\`。最多 22 个字符。
`unit_label`	`string`	产品单个单位的标签（例如，“seat”、“GB”）。最多 12 个字符。
`nft_factory`	`string`	关联的 NFT 工厂合约的地址。
`features`	`object[]`	功能对象列表，其中每个对象都有一个 `name` 属性。
`prices`	`object[]`	要创建并附加到此产品的价格对象数组。请参阅下方的价格对象属性表。

价格对象属性

创建产品时，您可以包含一个价格数组。prices 数组中的每个对象可以具有以下属性：

Name	Type	Description
`unit_amount`	`number`	必需。以最小货币单位表示的价格（例如，美元的美分）。必须大于 0。
`currency_id`	`string`	必需。此价格的货币 ID。
`nickname`	`string`	价格的内部名称。
`type`	`string`	`one_time` 或 `recurring`。默认为 `one_time`。
`recurring`	`object`	如果 `type` 是 `recurring`，则为必需。一个包含 `interval`（`day`、`week`、`month` 或 `year`）和可选 `interval_count` 的对象。
`custom_unit_amount`	`object`	定义一个客户可以选择金额的价格。有关详细信息，请参阅价格 API。

返回新创建的 Product 对象，包括任何已创建价格的列表。

Response Example

{
  "id": "prod_12345",
  "name": "Premium Subscription",
  "type": "service",
  "active": true,
  "description": "Monthly access to premium features.",
  "images": [],
  "metadata": {},
  "statement_descriptor": null,
  "unit_label": null,
  "nft_factory": null,
  "features": [],
  "default_price_id": "price_67890",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "prices": [
    {
      "id": "price_67890",
      "product_id": "prod_12345",
      "active": true,
      "type": "recurring",
      "unit_amount": "1500",
      "currency_id": "usd_xxxx",
      "recurring": {
        "interval": "month",
        "interval_count": 1
      }
    }
  ]
}

检索产品

检索现有产品的详细信息。

Retrieve Product

const product = await payment.products.retrieve('prod_12345');

参数

Name	Type	Description
`id`	`string`	必需。要检索的产品的唯一标识符。

如果提供了有效的 ID，则返回一个 Product 对象。否则，此调用将返回错误。

Response Example

{
  "id": "prod_12345",
  "name": "Premium Subscription",
  "type": "service",
  "active": true,
  "description": "Monthly access to premium features.",
  // ... other product fields
  "prices": [
    // ... list of associated price objects
  ]
}

更新产品

通过设置传递的参数值来更新指定产品。任何未提供的参数将保持不变。

Update Product

const product = await payment.products.update('prod_12345', {
  description: 'Updated: Monthly access to all premium features and priority support.',
  metadata: { 'tier': 'premium' }
});

参数

Name	Type	Description
`id`	`string`	必需。要更新的产品的 ID。
`name`	`string`	产品的名称。
`description`	`string`	一个可选的、面向用户的产品描述。
`images`	`string[]`	产品图片的 URL 列表。
`metadata`	`object`	与产品一起存储的键值数据。
`statement_descriptor`	`string`	信用卡账单的简短描述符。
`default_price_id`	`string`	要设置为此产品默认价格的价格 ID。
`unit_label`	`string`	产品单个单位的标签。
`features`	`object[]`	功能对象列表。

返回更新后的 Product 对象。

列出所有产品

返回产品的分页列表。产品按创建日期排序返回，最新创建的产品排在最前面。

List Products

const products = await payment.products.list({
  active: true,
  limit: 10
});

参数

Name	Type	Description
`active`	`boolean`	仅返回具有此活动状态的产品。
`name`	`string`	仅返回具有此名称的产品。
`description`	`string`	仅返回具有此描述的产品。
`type`	`string`	仅返回此类型的产品（例如，`credit`）。
`metadata.{key}`	`string`	按元数据中的特定键值对进行筛选。例如，`metadata.tier: 'premium'`。
`page`	`number`	要检索的页码。默认为 `1`。
`pageSize`	`number`	每页返回的对象数。默认为 `20`。

一个 Product 对象的分页列表。

Response Example

{
  "count": 50,
  "list": [
    {
      "id": "prod_12345",
      "name": "Premium Subscription",
      // ... other product fields
    },
    {
      "id": "prod_67890",
      "name": "Standard Plan",
      // ... other product fields
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}

搜索产品

返回与搜索查询匹配的产品列表。

Search Products

const products = await payment.products.search({ query: 'Premium' });

参数

Name	Type	Description
`query`	`string`	搜索查询字符串。搜索在 `name` 和 `description` 等字段上执行。
`page`	`number`	要检索的页码。默认为 `1`。
`pageSize`	`number`	每页返回的对象数。默认为 `20`。

与搜索查询匹配的 Product 对象的分页列表。

归档产品

归档一个产品，使其无法用于新的购买。此操作会切换产品的 active 状态。归档产品不会影响现有的订阅或购买。

Archive Product

const product = await payment.products.archive('prod_12345');

参数

Name	Type	Description
`id`	`string`	必需。要归档的产品的 ID。

返回更新后的 Product 对象，其 active 状态设置为 false（如果它已经被归档，则为 true）。

删除产品

永久删除一个产品。此操作无法撤销。只有当产品没有价格，或者其任何价格都未在任何交易中使用时，才能删除该产品。

Delete Product

const deletedProduct = await payment.products.del('prod_12345');

参数

Name	Type	Description
`id`	`string`	必需。要删除的产品的 ID。

返回已删除的 Product 对象。