Product Collections

Group related products together for unified checkout experiences, plan selection, and seamless upgrade/downgrade paths within the Customer Portal.

Product Collections let you group related products (e.g., Starter, Pro, Enterprise plans) under one umbrella. Display all options in a single checkout, define upgrade/downgrade paths, and give customers the flexibility to switch plans directly from the Customer Portal.

​

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

Product Collections are created and managed from the dashboard or via API. Each collection acts as a container for related products.

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

Collections enable a unified checkout experience where customers can view and select from all available products in one place.

​

Checkout Types

Type	Description	Use Case
Collection Checkout	Displays all active products within a collection	Subscription plan selection, tiered pricing
Single Product Checkout	Displays only one specific product	Direct purchase, promotional links

​

Collection Checkout Experience

When using a collection checkout:

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

Collection checkout is ideal for subscription businesses where you want customers to compare plans side-by-side before purchasing.

​

API Integration

Create a checkout session for a collection:

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;

When using product_collection_id, discount codes cannot be applied at session creation. Customers can still enter discount codes during checkout if enabled.

​

Customer Portal Integration

Customers can upgrade or downgrade between products within the same collection directly from the Customer Portal.

Already have subscription products? Simply add them to a Product Collection to enable upgrade/downgrade flows in the Customer Portal. No need to recreate your products.

​

Plan Management Actions

Action	Description	Merchant Control
View Current Plan	Display current product name, price, and renewal date	Always available
Upgrade Plan	Move to a higher-tier product in the same collection	Configurable (default: allowed)
Downgrade Plan	Move to a lower-tier product in the same collection	Configurable (default: allowed)
Cancel	Cancel the subscription entirely	Always available

​

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

Customers cannot change to products outside their current collection. Create separate collections for distinct product lines.

​

Subscription Settings

Cấu hình cách đăng ký và thay đổi gói hoạt động trên toàn bộ doanh nghiệp của bạn từ Cài đặt → Đăng ký trong bảng điều khiển của bạn.

​

Available Settings

Setting	Description	Default
Allow Multiple Subscriptions	Customers can hold more than one active subscription at the same time	Enabled
Allow Subscription Updates	Customers can upgrade or downgrade their existing subscriptions anytime via Customer Portal	Disabled

Thay đổi gói qua Cổng thông tin khách hàng bị tắt theo mặc định. Kích hoạt “Cho phép Cập Nhật Đăng Ký” trong Cài đặt → Đăng ký để cho phép khách hàng nâng cấp hoặc hạ cấp giữa các sản phẩm trong cùng một bộ sưu tập.

Subscription Plan Changes

Learn more about proration modes and plan change behavior.

​

Managing Collections

Bộ sưu tập sản phẩm có thể được quản lý thông qua bảng điều khiển Dodo Payments hoặc lập trình thông qua API. API cung cấp toàn quyền kiểm soát việc tạo, cập nhật, tải lên hình ảnh, lưu trữ và quản lý các nhóm lồng ghép và sản phẩm.

​

Hoạt động trên Dashboard

• Tạo mới: Thiết lập bộ sưu tập mới với sản phẩm và nhóm
• Cập nhật: Chỉnh sửa tên, mô tả, hình ảnh và tổ chức sản phẩm
• Sắp xếp lại: Kéo và thả để thay đổi thứ tự hiển thị sản phẩm
• Bật/Tắt sản phẩm: Kiểm soát sản phẩm nào xuất hiện trong phần thanh toán
• Lưu trữ: Ẩn bộ sưu tập mà không xóa vĩnh viễn (có thể mở lại sau)

​

Quản lý API

Các endpoint sau cho phép bạn tạo, cập nhật, truy xuất, lưu trữ và tổ chức bộ sưu tập sản phẩm bằng lập trình — bao gồm quản lý các nhóm lồng ghép và sản phẩm trong chúng.

Listing Product Collections

Lấy tất cả bộ sưu tập sản phẩm liên kết với tài khoản của bạn bằng cách gửi yêu cầu GET đến endpoint /product-collections. Hỗ trợ phân trang, lọc theo thương hiệu và bao gồm cả các bộ sưu tập đã lưu trữ.

List Product Collections API

Xem cấu trúc yêu cầu và phản hồi chi tiết trong tài liệu API Danh sách Bộ sưu tập sản phẩm.

Creating a Product Collection

Tạo một bộ sưu tập sản phẩm mới bằng cách gửi yêu cầu POST đến endpoint /product-collections với các chi tiết như tên, mô tả và thương hiệu.

Create Product Collection API

Xem cấu trúc yêu cầu và phản hồi chi tiết trong tài liệu API Tạo Bộ sưu tập sản phẩm.

Retrieving a Product Collection

Lấy thông tin chi tiết về một bộ sưu tập sản phẩm cụ thể — bao gồm các nhóm và mặt hàng sản phẩm — bằng cách gửi yêu cầu GET đến endpoint /product-collections/{id}.

Get Product Collection API

Xem cấu trúc yêu cầu và phản hồi chi tiết trong tài liệu API Lấy Bộ sưu tập sản phẩm.

Updating a Product Collection

Chỉnh sửa chi tiết của một bộ sưu tập sản phẩm (tên, mô tả, thương hiệu, v.v.) bằng cách gửi yêu cầu PATCH đến endpoint /product-collections/{id}.

Update Product Collection API

Xem cấu trúc yêu cầu và phản hồi chi tiết trong tài liệu API Cập nhật Bộ sưu tập sản phẩm.

Uploading Collection Images

Liên kết một hình ảnh với một bộ sưu tập bằng cách tải lên qua URL được ký sẵn. Yêu cầu một URL tải lên từ endpoint /product-collections/{id}/images, sau đó PUT hình ảnh đến URL được trả về trong vòng 60 giây.

URL được ký sẵn sẽ hết hạn sau 60 giây, vì vậy hình ảnh phải được tải lên trong khung thời gian đó.

Update Collection Images API

Xem cấu trúc yêu cầu và phản hồi chi tiết trong tài liệu API Cập nhật Hình ảnh Bộ sưu tập.

Archiving a Product Collection

Lưu trữ một bộ sưu tập bằng cách gửi yêu cầu DELETE đến endpoint /product-collections/{id}. Điều này ẩn bộ sưu tập khỏi việc sử dụng mới nhưng không loại bỏ vĩnh viễn.

Archive Product Collection API

Xem cấu trúc yêu cầu và phản hồi chi tiết trong tài liệu API Lưu trữ Bộ sưu tập sản phẩm.

Unarchiving a Product Collection

Khôi phục một bộ sưu tập đã lưu trữ bằng cách gửi yêu cầu POST đến endpoint /product-collections/{id}/unarchive.

Unarchive Product Collection API

Xem cấu trúc yêu cầu và phản hồi chi tiết trong tài liệu API Bỏ lưu trữ Bộ sưu tập sản phẩm.

Managing Groups within a Collection

Nhóm cho phép bạn tổ chức các sản phẩm bên trong một bộ sưu tập (ví dụ: “Gói hàng tháng” so với “Gói hàng năm”). Sử dụng các endpoint nhóm để thêm, cập nhật hoặc xóa nhóm trong bộ sưu tập.

• Tạo một nhóm: POST /product-collections/{id}/groups
• Cập nhật một nhóm: PATCH /product-collections/{id}/groups/{group_id}
• Xóa một nhóm: DELETE /product-collections/{id}/groups/{group_id}

Create Group

Thêm một nhóm mới vào bộ sưu tập sản phẩm.

Update Group

Chỉnh sửa tên hoặc thuộc tính của một nhóm.

Delete Group

Loại bỏ một nhóm khỏi bộ sưu tập.

Managing Products within a Group

Quản lý các mặt hàng sản phẩm riêng lẻ bên trong một nhóm — thêm sản phẩm mới, cập nhật các mặt hàng hiện có (chẳng hạn như thứ tự hiển thị), hoặc xóa chúng hoàn toàn.

• Thêm sản phẩm vào nhóm: POST /product-collections/{id}/groups/{group_id}/items
• Cập nhật một mặt hàng nhóm: PATCH /product-collections/{id}/groups/{group_id}/items/{item_id}
• Xóa một mặt hàng nhóm: DELETE /product-collections/{id}/groups/{group_id}/items/{item_id}

Add Products to Group

Thêm một hoặc nhiều sản phẩm vào nhóm trong bộ sưu tập.

Update Group Item

Cập nhật một mặt hàng sản phẩm trong nhóm.

Delete Group Item

Loại bỏ một mặt hàng sản phẩm khỏi nhóm.

​

Thực hành tốt nhất

• Nhóm hợp lý: Tổ chức sản phẩm theo khoảng thời gian thanh toán (hàng tháng/hàng năm) hoặc cấp tính năng (khởi đầu/chuyên nghiệp/doanh nghiệp)
• Sắp xếp chiến lược: Đặt kế hoạch phổ biến nhất hoặc được đề xuất đầu tiên, vì nó sẽ được chọn trước trong phần thanh toán
• Sử dụng tên rõ ràng: Tên sản phẩm nên truyền đạt rõ ràng sự khác biệt về giá trị
• Cho phép cả hai hướng: Cho phép cả nâng cấp và hạ cấp để mang lại sự linh hoạt cho khách hàng
• Xem xét tính tương đối giá: Chọn một chế độ tương đối giá phù hợp với mô hình kinh doanh của bạn
• Kiểm tra kỹ lưỡng: Xác minh quy trình thanh toán và thay đổi kế hoạch trong chế độ thử nghiệm trước khi đưa lên thực tế

Bạn đã sẵn sàng để tạo bộ sưu tập sản phẩm và cung cấp cho khách hàng trải nghiệm lựa chọn gói thống nhất.

Products

Tạo các sản phẩm một lần, đăng ký hoặc dựa trên việc sử dụng để thêm vào bộ sưu tập.

Checkout

Hiển thị sản phẩm trong bộ sưu tập trong trải nghiệm thanh toán thống nhất.

Customer Portal

Cho phép khách hàng nâng cấp hoặc hạ cấp trong cùng một bộ sưu tập.

Subscriptions

Quản lý kế hoạch định kỳ với việc tương đối giá và thay đổi kế hoạch.