产品和价格

产品和价格是 PaymentKit 目录中的基本要素。产品代表你销售的商品（例如，软件订阅、实体商品或积分包），而价格则决定了该产品的收费金额和频率。一个产品可以有多个价格，从而实现灵活的计费模式（例如，按月订阅与按年订阅）。

本指南将引导你使用 PaymentKit SDK 管理产品及其关联价格。有关所有可用 API 方法和参数的完整列表，请参阅 产品 API 参考 和 价格 API 参考。

首先，我们来直观地了解一下产品和价格之间的关系。

管理产品#

payment.products 对象提供了创建、检索、更新和管理系统中产品的方法。

创建产品#

如需创建新产品，请使用 payment.products.create 方法。你需要提供名称、类型和可选的描述。

参数

名称	类型	描述
name	string	必填。 产品名称，会向客户显示。
description	string	产品的可选描述。
type	string	必填。 产品类型。可以是 service（服务）、good（商品）或 credit（积分）。
active	boolean	产品当前是否可供购买。默认为 true。
metadata	object	一组键值对，用于存储有关该对象的附加信息。

示例：创建服务类产品

响应示例

列出产品#

如需检索产品列表，请使用 payment.products.list 方法。你可以筛选和分页显示结果。

参数

名称	类型	描述
active	boolean	（可选）设为 true 以仅返回有效的产品。
name	string	（可选）按名称筛选产品。
page	number	（可选）用于分页的页码。默认为 1。
pageSize	number	（可选）每页的项目数。默认为 20。
order	string	（可选）排序顺序（例如 'created_at:ASC'）。

示例：列出有效的产品

响应示例

管理价格#

拥有产品后，你可以使用 payment.prices 对象为其创建一个或多个价格。

创建价格#

价格可以是一次性购买，也可以是周期性订阅。对于周期性价格，你必须指定计费周期。

参数

名称	类型	描述
product_id	string	必填。 此价格所属产品的 ID。
type	string	必填。 定价类型。可以是 one_time（一次性）或 recurring（周期性）。
unit_amount	string	必填。 价格金额，为字符串格式。
currency_id	string	必填。 此价格的货币 ID。
active	boolean	该价格当前是否可供购买。默认为 true。
recurring	object	当 type 为 recurring 时必填。一个定义周期性计费行为的对象。
quantity_available	number	此价格的总可用数量。
quantity_limit_per_checkout	number	单个订单中客户可购买的最大数量。

recurring 对象

名称	类型	描述
interval	string	必填。 计费频率。可以是 day（天）、week（周）、month（月）或 year（年）。
interval_count	number	必填。 订阅计费之间的间隔数（例如，interval: 'month', interval_count: 3 表示按季度计费）。
usage_type	string	用量类型。可以是 licensed（固定价格）或 metered（按用量计费）。默认为 licensed。

示例：创建周期性月度价格

响应示例

管理价格库存#

对于库存有限的产品，你可以使用 inventory 方法调整价格的可用数量。这对于管理供应有限的商品很有用。

参数

名称	类型	描述
priceId	string	必填。 要更新的价格的 ID。
quantity	number	必填。 用于增加或减少库存的数量。
action	string	必填。 要执行的操作。必须是 increment（增加）或 decrement（减少）。

示例：增加价格的库存

响应示例

现在你已了解如何创建和管理产品与价格，可以开始销售它们了。下一步是为你的客户创建结账体验。请在 结账会话指南 中了解如何操作。