产品集合

将相关产品组合在一起，以便在客户门户中提供统一的结账体验、计划选择和无缝的升级/降级路径。

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

​

主要亮点

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

​

创建产品集合

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

1. Create the collection

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

   

   集合字段：

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

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

   

   产品组织：

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

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

3. Configure ordering and visibility

   控制集合中产品的显示顺序和可见性。

   配置选项：

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

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

​

集合结账

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

​

结账类型

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

​

集合结账体验

使用集合结账时：

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

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

​

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时，不能在会话创建时应用折扣码。如果启用，客户仍可以在结账时输入折扣码。

​

客户门户集成

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

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

​

计划管理操作

操作	描述	商家控制
查看当前计划	显示当前产品名称、价格和续订日期	始终可用
升级计划	移至同一集合中更高层级的产品	可配置（默认：允许）
降级计划	移至同一集合中较低层级的产品	可配置（默认：允许）
取消	完全取消订阅	始终可用

​

升级/降级规则

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

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

​

订阅设置

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

​

可用设置

设置	描述	默认
允许多个订阅	客户可以同时持有多个活动订阅	启用
允许订阅更新	客户可以随时通过客户门户升级或降级现有订阅	禁用

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

Subscription Plan Changes

了解有关比例调整模式和计划更改行为的更多信息。

​

管理集合

产品集合可以通过Dodo Payments仪表板或通过API进行管理。API提供对集合创建、更新、图像上传、存档和管理嵌套组和产品的全面控制。

​

仪表板操作

• 创建：设置新的集合与产品和组
• 更新：修改名称、描述、图像和产品组织
• 重新排序：拖放更改产品显示顺序
• 启用/禁用产品：控制结账时显示哪些产品
• 存档：隐藏集合而不永久删除（稍后可以解除存档）

​

API管理

以下端点允许您通过编程方式创建、更新、检索、存档和组织产品集合，包括管理嵌套组及其中的产品。

Listing Product Collections

使用GET请求到/product-collections端点，获取与您的帐户关联的所有产品集合。支持分页、按品牌筛选，并包括存档的集合。

List Product Collections API

在商品集合API文档中查阅请求和响应的详细结构。

Creating a Product Collection

通过向/product-collections端点发送POST请求，创建一个新的产品集合，包含名称、描述和品牌等详细信息。

Create Product Collection API

在创建产品集合API文档中查阅请求和响应的详细结构。

Retrieving a Product Collection

使用GET请求到/product-collections/{id}端点，获取有关特定产品集合（包括其组和产品项目）的详细信息。

Get Product Collection API

在获取产品集合API文档中查阅请求和响应的详细结构。

Updating a Product Collection

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

Update Product Collection API

在更新产品集合API文档中查阅请求和响应的详细结构。

Uploading Collection Images

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

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

Update Collection Images API

在更新集合图像API文档中查阅请求和响应的详细结构。

Archiving a Product Collection

通过向/product-collections/{id}端点发送DELETE请求来存档一个集合。这会隐藏集合以避免新用途，但不会永久移除。

Archive Product Collection API

在存档产品集合API文档中查阅请求和响应的详细结构。

Unarchiving a Product Collection

通过向/product-collections/{id}/unarchive端点发送POST请求，恢复存档的集合。

Unarchive Product Collection API

在解除存档产品集合API文档中查阅请求和响应的详细结构。

Managing Groups within a Collection

组让您可以在集合中组织产品（例如，“月度计划”与“年度计划”）。使用组端点添加、更新或移除集合中的组。

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

Create Group

将新组添加到产品集合。

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

从组中移除一个产品项。

​

最佳实践

• 逻辑分组：按计费周期（月度/年度）或功能层级（入门/专业/企业）组织产品
• 战略排序：将最受欢迎或推荐的计划放在首位，因为它将在结账时预选
• 使用清晰的命名：产品名称应清晰传达价值差异
• 启用双向操作：允许升级和降级以提供客户灵活性
• 考虑比例调整：选择符合您商业模式的比例调整模式
• 彻底测试：在上线前在测试模式下验证结账和计划更改流程

您已准备好创建产品集合并为客户提供统一的计划选择体验。

Products

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

Checkout

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

Customer Portal

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

Subscriptions

管理带有比例调整和计划更改的定期计划。