Product Collections

​

Key Highlights

• Collection-based structure: Group related products (plans, tiers, pricing options) under a single collection for organized management.
• One collection, many products: Include multiple products like Starter, Pro, Lifetime, etc., each with its own pricing model.
• Dynamic checkout experience: Display all products from a collection in one checkout view, letting customers choose their preferred plan.
• Merchant-level control: Enable, disable, and reorder products within each collection. The first product is automatically pre-selected at checkout.
• Lifecycle awareness: Enable customers to upgrade or downgrade between products in the same collection via the Customer Portal.

​

Creating a Product Collection

1

Create the collection

Define the collection with a name and optional description. Upload an image to visually represent the collection in checkout.

Collection fields:

• Name (required): Display name for the collection (e.g., “SaaS Plans”, “License Tiers”)
• Description (optional): Brief explanation shown in checkout
• Image (optional): Visual branding for the collection

2

Add products to the collection

Add existing products to your collection. Products can be organized into groups for better structure.

Product organization:

• Groups: Optionally organize products into named groups (e.g., “Monthly Plans”, “Annual Plans”)
• Ungrouped products: Products without a group appear at the collection level
• Ordering: Drag and drop to set the display order

Each product can only belong to one collection. If a product is already in another collection, you’ll need to remove it first.

3

Configure ordering and visibility

Control the display order and visibility of products within the collection.Configuration options:

• Product status: Enable or disable individual products within the collection
• Display order: Drag and drop to set the sequence products appear in checkout

The first product in the collection is automatically pre-selected as the default at checkout. Reorder products to change which one is selected by default.

​

Collection Checkout

​

Checkout Types

​

Collection Checkout Experience

1. All active products displayed: Customers see every enabled product in the collection
2. First product pre-selected: The first product in the collection order is automatically selected
3. Product details shown: Each product displays its name, description, and pricing
4. Single selection: Customer selects one product to purchase
5. Standard flow continues: After selection, the checkout proceeds with the chosen product’s pricing and billing settings

​

API Integration

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;

​

Customer Portal Integration

​

Plan Management Actions

​

Upgrade/Downgrade Rules

• Upgrades and downgrades are only available between products within the same collection
• Proration is applied based on your subscription settings
• Email notifications are sent to the business on every upgrade, downgrade, or cancellation

​

Subscription Settings

​

Available Settings

​

Managing Collections

​

仪表板操作

• 创建：设置带有产品和组的新集合
• 更新：修改名称、描述、图片和产品组织
• 重新排序：拖放以更改产品显示顺序
• 启用/禁用产品：控制哪些产品出现在结账中
• 归档：隐藏集合而不是永久删除它（以后可以取消归档）

​

API 管理

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

• 向组中添加产品：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}

​

最佳实践

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