Product Collections

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.

Ảnh chụp màn hình của trang thanh toán Bộ sưu tập Sản phẩm hiển thị nhiều sản phẩm được hiển thị

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.

Create the collection

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

Ảnh chụp màn hình của biểu mẫu tạo Bộ sưu tập Sản phẩm trong bảng điều khiển hiển thị các trường cho tên, mô tả và tải lên hình ảnh

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

Add products to the collection

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

Ảnh chụp màn hình của trang sản phẩm Bộ sưu tập Sản phẩm hiển thị danh sách sản phẩm và khả năng thêm chúng vào bộ sưu tập

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.

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:

All active products displayed: Customers see every enabled product in the collection
First product pre-selected: The first product in the collection order is automatically selected
Product details shown: Each product displays its name, description, and pricing
Single selection: Customer selects one product to purchase
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
Xem gói hiện tại	Hiển thị tên sản phẩm, giá và ngày gia hạn hiện tại	Luôn khả dụng
Nâng cấp gói	Chuyển sang sản phẩm cấp cao hơn trong cùng một collection	Có thể cấu hình (mặc định: đã tắt)
Hạ cấp gói	Chuyển sang sản phẩm cấp thấp hơn trong cùng một collection	Có thể cấu hình (mặc định: đã tắt)
Hủy	Hủy toàn bộ subscription	Luôn khả dụng

Ảnh chụp màn hình của giao diện thay đổi gói cổng thông tin khách hàng Bộ sưu tập Sản phẩm hiển thị các hành động quản lý gói

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.

Ảnh chụp màn hình của trang cài đặt đăng ký hiển thị công tắc Cho phép Nhiều Đăng Ký và Cho phép Cập Nhật Đăng Ký

Available Settings

Setting	Description	Default
Cho phép nhiều subscription	Khách hàng có thể duy trì nhiều subscription đang hoạt động cùng lúc	Đã bật
Cho phép cập nhật subscription	Khách hàng có thể nâng cấp hoặc hạ cấp các subscription hiện có bất kỳ lúc nào thông qua Customer Portal	Đã tắt
Cho phép hủy subscription	Khách hàng có thể tự hủy subscription của mình từ Customer Portal	Đã bật
Cho phép tạm dừng subscription	Khách hàng có thể tự tạm dừng và tiếp tục subscription của mình từ Customer Portal	Đã tắt
Tính phí usage khi tạm dừng	Subscription tính phí theo usage bị tạm dừng sẽ được lập hóa đơn cho usage còn nợ tại thời điểm tạm dừng, thay vì chuyển usage sang hóa đơn định kỳ tiếp theo	Đã bật
Ngăn lạm dụng trial	Khách hàng đã sử dụng trial trước đó sẽ được chuyển sang giao dịch trả phí không có trial, thay vì nhận một trial mới	Đã tắt

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.

Tắt “Allow Subscription Cancellation” sẽ ẩn tính năng tự hủy đối với customers và từ chối các yêu cầu hủy được thực hiện thông qua Customer Portal API. Các thao tác hủy của riêng merchant không bị ảnh hưởng. Xem Hủy một Subscription.

“Cho phép tạm dừng subscription” chỉ áp dụng cho Customer Portal — bạn có thể tạm dừng và tiếp tục từ dashboard hoặc API bất kể tùy chọn này được đặt như thế nào. “Tính phí usage khi tạm dừng” chỉ áp dụng cho subscription tính phí theo usage và được ghi nhận theo từng billing cycle, vì vậy việc thay đổi tùy chọn này giữa chu kỳ không làm thay đổi cách chu kỳ đang diễn ra được quyết toán. Xem Tạm dừng và tiếp tục subscription.

Để biết chi tiết về cách các lần sử dụng trial được đối chiếu và ghi nhận, hãy xem Ngăn lạm dụng trial.

Subscription Plan Changes

Tìm hiểu thêm về các chế độ proration và cách hoạt động của việc thay đổi gói.

Quản lý collection

Product Collections có thể được quản lý thông qua dashboard của Dodo Payments hoặc lập trình bằng API. API cung cấp toàn quyền kiểm soát việc tạo, cập nhật, tải hình ảnh lên, lưu trữ collection, cũng như quản lý các group lồng nhau và product.

Thao tác trên dashboard

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

Ảnh chụp màn hình dashboard Product Collection hiển thị các thao tác quản lý collection

Quản lý API

Các endpoint sau đây cho phép bạn lập trình để tạo, cập nhật, truy xuất, lưu trữ và sắp xếp Product Collections — bao gồm quản lý các group lồng nhau và product bên trong chúng.

Listing Product Collections

Lấy tất cả Product Collections liên kết với tài khoản của bạn bằng request GET đến endpoint /product-collections. Hỗ trợ phân trang, lọc theo brand và bao gồm cả các collection đã lưu trữ.

List Product Collections API

Xem cấu trúc request và response chi tiết trong tài liệu API List Product Collections.

Creating a Product Collection

Tạo Product Collection mới bằng cách gửi request POST đến endpoint /product-collections cùng các thông tin như tên, mô tả và brand.

Create Product Collection API

Xem cấu trúc request và response chi tiết trong tài liệu API Create Product Collection.

Retrieving a Product Collection

Lấy thông tin chi tiết về một Product Collection cụ thể — bao gồm các group và product item của collection — bằng request GET đến endpoint /product-collections/{id}.

Get Product Collection API

Xem cấu trúc request và response chi tiết trong tài liệu API Get Product Collection.

Updating a Product Collection

Sửa đổi thông tin của Product Collection (tên, mô tả, brand, v.v.) bằng cách gửi request PATCH đến endpoint /product-collections/{id}.

Update Product Collection API

Xem cấu trúc request và response chi tiết trong tài liệu API Update Product Collection.

Uploading Collection Images

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

Pre-signed URL hết hạn sau 60 giây, vì vậy hình ảnh phải được tải lên trong khoảng thời gian đó.

Update Collection Images API

Xem cấu trúc request và response chi tiết trong tài liệu API Update Collection Images.

Archiving a Product Collection

Lưu trữ collection bằng cách gửi request DELETE đến endpoint /product-collections/{id}. Thao tác này ẩn collection khỏi các mục đích sử dụng mới nhưng không xóa collection vĩnh viễn.

Archive Product Collection API

Xem cấu trúc request và response chi tiết trong tài liệu API Archive Product Collection.

Unarchiving a Product Collection

Khôi phục collection đã lưu trữ bằng cách gửi request POST đến endpoint /product-collections/{id}/unarchive.

Unarchive Product Collection API

Xem cấu trúc request và response chi tiết trong tài liệu API Unarchive Product Collection.

Managing Groups within a Collection

Group giúp bạn sắp xếp product bên trong collection (ví dụ: “Gói hàng tháng” so với “Gói hàng năm”). Sử dụng các endpoint group để thêm, cập nhật hoặc xóa group trong collection.

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

Create Group

Thêm group mới vào Product Collection.

Update Group

Sửa đổi tên hoặc thuộc tính của group.

Delete Group

Xóa group khỏi collection.

Managing Products within a Group

Quản lý từng product item bên trong group — thêm product mới, cập nhật item hiện có (chẳng hạn như thứ tự hiển thị) hoặc xóa hoàn toàn.

Thêm product vào group: POST /product-collections/{id}/groups/{group_id}/items
Cập nhật group item: PATCH /product-collections/{id}/groups/{group_id}/items/{item_id}
Xóa group item: DELETE /product-collections/{id}/groups/{group_id}/items/{item_id}

Add Products to Group

Thêm một hoặc nhiều product vào group trong collection.

Update Group Item

Cập nhật product item trong group.

Delete Group Item

Xóa product item khỏi group.

Thực tiễn tốt nhất

Nhóm theo cách hợp lý: Sắp xếp product 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 (starter/pro/enterprise)
Sắp xếp có chiến lược: Đặt gói phổ biến hoặc được đề xuất nhất ở vị trí đầu tiên vì gói này sẽ được chọn trước trong checkout
Đặt tên rõ ràng: Tên product nên truyền đạt rõ sự khác biệt về giá trị
Cho phép cả hai chiều: Cho phép nâng cấp và hạ cấp để mang lại sự linh hoạt cho khách hàng
Cân nhắc proration: Chọn chế độ proration phù hợp với mô hình kinh doanh của bạn
Kiểm thử kỹ lưỡng: Xác minh các luồng checkout và thay đổi gói trong test mode trước khi đưa vào sử dụng thực tế

Bạn đã sẵn sàng tạo Product Collections 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 product one-time, subscription hoặc tính phí theo usage để thêm vào collection.

Checkout

Hiển thị product trong collection bằng trải nghiệm checkout 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 collection.

Subscriptions

Quản lý các gói định kỳ với proration và thay đổi gói.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Key Highlights

Creating a Product Collection