产品

产品对象代表您向客户提供的商品、服务或数字信用。您可以将它们视为目录中的项目。每个产品可以有一个或多个相关联的价格。
此 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',
      },
    },
  ],
});
参数
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",
See all 5 lines
检索产品#检索现有产品的详细信息。
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 对象。

属性	类型	描述
`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`	最后更新的时间戳。

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[]`	要创建并附加到此产品的价格对象数组。请参阅下方的价格对象属性表。

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。

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[]`	功能对象列表。

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

概述

快速入门

SDK 结构

环境

核心概念

API 参考

产品

产品对象#

创建产品#

检索产品#

更新产品#

列出所有产品#

搜索产品#

归档产品#

删除产品#

价格

促销代码

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