产品集合

产品集合让您可以将相关产品（例如，入门、专业、企业计划）组合在一个范畴内。显示所有选项于单一结账中，定义升级或降级路径，并让客户直接从客户门户灵活切换计划。

主要亮点

基于集合的结构：将相关产品（计划、层级、价格选项）放入一个集合中进行有序管理。
一个集合，多个产品：包括多个产品如入门、专业、终身等，每个产品都有自己的定价模式。
动态结账体验：在一个结账视图中显示集合中的所有产品，让客户选择他们喜欢的计划。
商家级控制：启用、禁用和重新排序集合中的产品。结账时第一个产品会自动预选。
生命周期意识：通过客户门户，允许客户在同一集合中的产品之间升级或降级。

创建产品集合

产品集合可以从仪表板或通过API创建和管理。每个集合都作为相关产品的容器。

Create the collection

定义集合名称和可选描述。在结账中上传图像以直观地代表集合。

集合字段：

名称（必需）：集合的显示名称（例如，“SaaS计划”，“许可层级”）
描述（可选）：在结账中显示的简要说明
图像（可选）：集合的视觉品牌

Add products to the collection

将现有产品添加到您的集合中。产品可以成组组织以获得更好的结构。

产品组织：

组：可选将产品组织到命名组中（例如，“月度计划”，“年度计划”）
未分组的产品：没有组的产品显示在集合级别
排序：拖放设置显示顺序

每个产品只能属于一个集合。如果一个产品已在其他集合中，您需要先将其移除。

Configure ordering and visibility

控制集合中产品的显示顺序和可见性。配置选项：

产品状态：启用或禁用集合中的单个产品
显示顺序：拖放设置产品在结账中出现的顺序

集合中的第一个产品会自动作为默认选项在结账时预选。重新排序产品以更改默认选择。

集合结账

集合实现统一的结账体验，客户可以在一个地方查看并选择所有可用产品。

结账类型

类型	描述	用例
集合结账	显示集合中的所有激活产品	订阅计划选择、分层定价
单产品结账	仅显示一个特定产品	直接购买、促销链接

集合结账体验

使用集合结账时：

显示所有激活的产品：客户可以看到集合中启用的每个产品
第一个产品预选：集合顺序中的第一个产品会自动被选中
显示产品详情：每个产品显示其名称、描述和定价
单一选择：客户选择一个产品进行购买
继续标准流程：选择后，结账将根据选定产品的定价和账单设置进行

集合结账非常适合于订阅型企业，客户可以在购买前并排比较计划。

API集成

为集合创建一个结账会话：

const session = await client.checkoutSessions.create({
  product_collection_id: 'pdc_abc123',
  product_cart: [], // Required: pass an empty array for collection checkout
  return_url: 'https://yoursite.com/return'
});

// Redirect customer to the checkout
window.location.href = session.checkout_url;

使用product_collection_id时，不能在会话创建时应用折扣码。如果启用，客户仍可以在结账时输入折扣码。

客户门户集成

客户可以直接从客户门户在同一集合内的产品之间升级或降级。

已有订阅产品？ 只需将它们添加到产品集合中以在客户门户中实现升级/降级流程。无需重新创建产品。

计划管理操作

操作	描述	Merchant 控制
查看当前计划	显示当前产品名称、价格和续订日期	始终可用
升级计划	将产品更换为同一集合中的更高等级产品	可配置（默认：禁用）
降级计划	将产品更换为同一集合中的更低等级产品	可配置（默认：禁用）
取消	完全取消订阅	始终可用

升级/降级规则

升级和降级仅在同一集合内的产品之间可用
根据您的订阅设置应用比例调整
每次升级、降级或取消时，都会向企业发送电子邮件通知

客户无法更改到当前集合外的产品。为不同的产品线创建单独的集合。

订阅设置

通过仪表板中的设置 → 订阅配置您的企业的订阅和计划变更方式。

可用设置

设置	描述	默认值
允许多个订阅	客户可以同时持有多个有效订阅	已启用
允许更新订阅	客户可以随时通过 Customer Portal 升级或降级现有订阅	已禁用
允许取消订阅	客户可以从 Customer Portal 取消自己的订阅	已启用
允许暂停订阅	客户可以从 Customer Portal 暂停和恢复自己的订阅	已禁用
暂停时计费使用量	基于使用量的暂停订阅会在暂停时就其欠付的使用量开具发票，而不是将使用量计入下一张常规发票	已启用
防止试用滥用	已经兑换过试用的客户将被降级为付费且无试用期的购买，而不是获得新的试用期	已禁用

客户门户的计划更改默认是禁用的。在设置 → 订阅中启用“允许订阅更新”，让客户可以在同一集合中的产品之间升级或降级。

关闭“允许取消订阅”后，客户将无法看到自助取消选项，并且通过 Customer Portal API 发出的取消请求将被拒绝。您在商户端发起的取消操作不受影响。请参阅取消订阅。

“允许暂停订阅”仅控制 Customer Portal——无论该设置如何，你都可以从控制面板或 API 暂停和恢复订阅。“暂停时计费使用量”仅适用于基于使用量的订阅，并且按计费周期记录，因此在周期中途更改该设置不会改变当前周期的结算方式。请参阅暂停和恢复订阅。

有关如何匹配和记录试用兑换的详细信息，请参阅防止试用滥用。

Subscription Plan Changes

进一步了解按比例分摊模式和计划变更行为。

管理集合

Product Collections 可以通过 Dodo Payments 控制面板进行管理，也可以通过 API 以编程方式进行管理。API 提供对集合创建、更新、图像上传、归档，以及嵌套组和产品管理的完整控制。

控制面板操作

创建：设置包含产品和组的新集合
更新：修改名称、描述、图像和产品组织方式
重新排序：拖放以更改产品显示顺序
启用/禁用产品：控制哪些产品显示在结账页面中
归档：隐藏集合，但不会永久删除（之后可以取消归档）

API 管理

以下 endpoints 允许你以编程方式创建、更新、检索、归档和组织 Product Collections，包括管理嵌套组及其中的产品。

Listing Product Collections

使用 GET 请求向 /product-collections endpoint 获取与你的账户关联的所有 Product Collections。支持分页、按品牌筛选以及包含已归档集合。

List Product Collections API

在 List Product Collections API 文档中查看详细的请求和响应结构。

Creating a Product Collection

通过向 /product-collections endpoint 发送 POST 请求，并提供名称、描述和品牌等详细信息，创建新的 Product Collection。

Create Product Collection API

在 Create Product Collection API 文档中查看详细的请求和响应结构。

Retrieving a Product Collection

使用 GET 请求向 /product-collections/{id} endpoint 获取特定 Product Collection 的详细信息，包括其组和产品项目。

Get Product Collection API

在 Get Product Collection API 文档中查看详细的请求和响应结构。

Updating a Product Collection

通过向 /product-collections/{id} endpoint 发送 PATCH 请求，修改 Product Collection 的详细信息（名称、描述、品牌等）。

Update Product Collection API

在 Update Product Collection API 文档中查看详细的请求和响应结构。

Uploading Collection Images

通过预签名 URL 上传图像，将其关联到集合。向 /product-collections/{id}/images endpoint 请求上传 URL，然后在 60 秒内将图像 PUT 到返回的 URL。

预签名 URL 将在 60 秒后过期，因此必须在此时间范围内上传图像。

Update Collection Images API

在 Update Collection Images API 文档中查看详细的请求和响应结构。

Archiving a Product Collection

通过向 /product-collections/{id} endpoint 发送 DELETE 请求来归档集合。这样会隐藏集合，使其无法用于新的用途，但不会永久删除它。

Archive Product Collection API

在 Archive Product Collection API 文档中查看详细的请求和响应结构。

Unarchiving a Product Collection

通过向 /product-collections/{id}/unarchive endpoint 发送 POST 请求来恢复已归档的集合。

Unarchive Product Collection API

在 Unarchive Product Collection API 文档中查看详细的请求和响应结构。

Managing Groups within a Collection

组可以帮助你在集合中组织产品（例如，“月度计划”和“年度计划”）。使用组 endpoints 在集合中添加、更新或删除组。

创建组：POST /product-collections/{id}/groups
更新组：PATCH /product-collections/{id}/groups/{group_id}
删除组：DELETE /product-collections/{id}/groups/{group_id}

Create Group

向 Product Collection 添加新组。

Update Group

修改组的名称或属性。

Delete Group

从集合中删除组。

Managing Products within a Group

管理组中的各个产品项目——添加新产品、更新现有项目（例如显示顺序），或将其完全删除。

向组添加产品：POST /product-collections/{id}/groups/{group_id}/items
更新组项目：PATCH /product-collections/{id}/groups/{group_id}/items/{item_id}
删除组项目：DELETE /product-collections/{id}/groups/{group_id}/items/{item_id}

Add Products to Group

向集合中的组添加一个或多个产品。

Update Group Item

更新组中的产品项目。

Delete Group Item

从组中删除产品项目。

最佳实践

合理分组：按计费周期（月度/年度）或功能等级（starter/pro/enterprise）组织产品
策略性排序：将最受欢迎或推荐的计划放在首位，因为它会在结账时预先选中
使用清晰的命名：产品名称应清楚传达价值差异
启用双向变更：同时允许升级和降级，为客户提供灵活性
考虑按比例分摊：选择符合业务模式的按比例分摊模式
充分测试：上线前在测试模式下验证结账和计划变更流程

你现在可以创建 Product Collections，并为客户提供统一的计划选择体验。

Products

创建一次性、订阅或基于使用量的产品，以添加到集合中。

Checkout

在统一的结账体验中显示集合产品。

Customer Portal

让客户在同一集合中升级或降级。

Subscriptions

通过按比例分摊和计划变更管理周期性计划。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

主要亮点

创建产品集合

集合结账