产品集合

Product Collections 可将相关产品（例如 Starter、Pro、Enterprise 方案）归入同一集合。在单个结账页面中显示所有选项，定义升级/降级路径，并允许客户直接从 Customer Portal 切换方案。

主要亮点

Product Collections 可让您：

将相关产品（方案、层级、定价选项）分组，以便统一管理。
包含多个产品，例如 Starter、Pro 和 Lifetime，每个产品都可以使用自己的定价模式。
在一个结账视图中显示所有产品，方便客户比较并选择首选方案。
允许客户通过 Customer Portal 在同一集合中的产品之间升级或降级。
控制哪些产品可见、显示顺序以及结账时默认选中的产品。

创建 Product Collection

您可以从控制面板或通过 API 创建和管理集合。

Create the collection

为集合定义名称和可选描述。上传一张图片，以便在结账时代表该集合。

控制面板中 Product Collection 创建表单的截图，显示名称、描述和图片上传字段

集合字段：

Name（必填）：显示名称（例如 “SaaS Plans”、“License Tiers”）。
Description（可选）：在结账时显示的简短说明。
Image（可选）：用于集合的视觉品牌元素。

Add products to the collection

将现有产品添加到集合中。将产品整理到不同组中，以获得更清晰的结构。

Product Collection 产品页面的截图，显示产品列表以及将产品添加到集合的功能

产品组织：

Groups：可选地将产品整理到命名组中（例如 “Monthly Plans”、“Annual Plans”）。
Ungrouped products：未分组的产品会显示在集合层级。
Ordering：拖放以设置显示顺序。

每个产品只能属于一个集合。如果产品已经属于其他集合，请先将其移除。

Configure ordering and visibility

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

Product status：启用或停用集合中的单个产品。
Display order：拖放以设置产品在结账时的显示顺序。

集合中的第一个产品会在结账时自动预选。重新排列产品即可更改默认选中的产品。

集合结账

集合支持统一的结账体验，客户可以在一个位置查看并选择所有可用产品。

结账类型

类型	描述	使用场景
Collection Checkout	显示集合中的所有活跃产品	订阅方案选择、分层定价
Single Product Checkout	仅显示一个指定产品	直接购买、促销链接

Collection Checkout 体验

使用集合结账时：

集合中的所有活跃产品都会显示。
集合顺序中的第一个产品会自动预选。
每个产品都会显示其名称、描述和价格。
客户选择一个产品进行购买。
结账会使用所选产品的定价和计费设置继续进行。

对于订阅业务，Collection Checkout 非常适合让客户在购买前并排比较方案。

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'
});

window.location.href = session.checkout_url;

使用 product_collection_id 时，无法在创建会话时预先应用折扣码。如果已启用，客户仍可在结账过程中输入折扣码。

Customer Portal 集成

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

已经有订阅产品？将其添加到 Product Collection，即可在 Customer Portal 中启用升级/降级流程。无需重新创建产品。

方案管理操作

操作	描述	商户控制
View Current Plan	显示当前产品名称、价格和续订日期。	始终可用。
Upgrade Plan	切换到同一集合中层级更高的产品。	可配置（默认：停用）。
Downgrade Plan	切换到同一集合中层级更低的产品。	可配置（默认：停用）。
Cancel	完全取消订阅。	始终可用。

升级/降级规则

只有同一集合中的产品之间支持升级和降级。
Customer Portal 方案更改的按比例计费遵循 Settings → Subscriptions 中的默认升级和降级行为，每个集合都可以覆盖这些默认设置。通过 Change Plan API 进行的方案更改，会使用请求中发送的 proration_billing_mode。
每次升级、降级或取消时，都会向企业发送电子邮件通知。

客户无法切换到当前集合之外的产品。请为不同的产品线创建单独的集合。

订阅设置

您可以在控制面板的 Settings → Subscriptions 中配置企业范围内订阅和方案更改的工作方式。

可用设置

设置	描述	默认值
Allow Multiple Subscriptions	客户可以同时持有多个活跃订阅。	已启用
Allow Subscription Updates	客户可以随时通过 Customer Portal 升级或降级现有订阅。	已停用
Allow Immediate Cancellation	客户可以结束订阅并立即失去访问权限。	已启用
Allow Cancellation at Next Billing Date	客户可以在已支付期间结束时取消订阅。	已启用
Allow Subscription Pause	客户可以从 Customer Portal 暂停和恢复自己的订阅。	已停用
Bill Usage at Pause	基于用量的暂停订阅会在暂停时为已产生的用量开具发票，而不是将用量结转到下一张常规发票。	已启用
Prevent Trial Misuse	已兑换过试用的客户会被降级为付费且无试用期的购买，而不是获得新的试用期。	已停用
Payment Method Reminder	在计费开始前，向启用了 Card-Optional at Zero Price 的订阅客户发送电子邮件，提醒其添加支付方式的天数（1 至 30 天）。	3 天

默认情况下，通过 Customer Portal 进行的方案更改处于停用状态。请在 Settings → Subscriptions 中启用 “Allow Subscription Updates”，允许客户在同一集合中的产品之间升级或降级。

两个取消设置彼此独立，因此您可以允许客户使用已支付的剩余周期，同时仅保留即时取消给自己使用，也可以反过来设置。停用其中一个选项会在 Customer Portal 中隐藏该选项，并通过 Customer Portal API 拒绝相关请求。您在商户端发起的取消操作不受影响。请参阅取消订阅。

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

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

“Payment Method Reminder” 仅适用于启用了 Card-Optional at Zero Price 的订阅；对于已经要求添加卡片的订阅，该设置不会产生任何影响。完整流程（包括忽略提醒时会发生什么）请参阅没有卡片时会发生什么。

Subscription Plan Changes

详细了解按比例计费模式和方案更改行为。

管理集合

通过控制面板或以编程方式通过 API 管理集合。

控制面板操作

Create：使用产品和组设置新集合。
Update：修改名称、描述、图片和产品组织方式。
Reorder：拖放以更改产品显示顺序。
Enable/Disable products：控制哪些产品显示在结账页面中。
Archive：隐藏集合而不永久删除它（之后可以取消归档）。

API 管理

使用以下端点以编程方式创建、更新、获取、归档和组织 Product Collections，包括管理嵌套组和产品。

Listing Product Collections

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

List Product Collections API

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

Creating a Product Collection

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

Create Product Collection API

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

Retrieving a Product Collection

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

Get Product Collection API

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

Updating a Product Collection

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

Update Product Collection API

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

Uploading Collection Images

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

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

Update Collection Images API

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

Archiving a Product Collection

向 /product-collections/{id} 端点发送 DELETE 请求，以归档集合。此操作会隐藏集合，使其无法用于新的用途，但不会永久删除它。

Archive Product Collection API

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

Unarchiving a Product Collection

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

Unarchive Product Collection API

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

Managing Groups within a Collection

组可以帮助您整理集合中的产品（例如将 “Monthly Plans” 与 “Annual Plans” 区分开）。使用组端点在集合中添加、更新或移除组。

Create a group：POST /product-collections/{id}/groups
Update a group：PATCH /product-collections/{id}/groups/{group_id}
Delete a group：DELETE /product-collections/{id}/groups/{group_id}

Create Group

向 Product Collection 添加新组。

Update Group

修改组的名称或属性。

Delete Group

从集合中移除组。

Managing Products within a Group

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

Add products to a group：POST /product-collections/{id}/groups/{group_id}/items
Update a group item：PATCH /product-collections/{id}/groups/{group_id}/items/{item_id}
Delete a group item：DELETE /product-collections/{id}/groups/{group_id}/items/{item_id}

Add Products to Group

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

Update Group Item

更新组中的产品项。

Delete Group Item

从组中移除产品项。

最佳实践

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

Products

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

Checkout

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

Customer Portal

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

Subscriptions

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

主要亮点

创建 Product Collection

集合结账