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

Configure how subscriptions and plan changes work across your business from the Subscription Settings section in your dashboard.

​

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

Plan changes via Customer Portal are disabled by default. Enable “Allow Subscription Updates” in your Subscription Settings to let customers upgrade or downgrade between products in the same collection.

Subscription Plan Changes

Learn more about proration modes and plan change behavior.

​

Managing Collections

Koleksi Produk dapat dikelola melalui dasbor Dodo Payments atau secara terprogram melalui API. API menyediakan kontrol penuh atas pembuatan koleksi, pembaruan, unggah gambar, pengarsipan, dan pengelolaan grup bersarang dan produk.

​

Operasi Dasbor

• Buat: Atur koleksi baru dengan produk dan grup
• Perbarui: Modifikasi nama, deskripsi, gambar, dan organisasi produk
• Urutkan ulang: Drag dan drop untuk mengubah urutan tampilan produk
• Aktifkan/Nonaktifkan produk: Kontrol produk mana yang muncul di checkout
• Arsipkan: Sembunyikan koleksi tanpa menghapusnya secara permanen (dapat diarsipkan kembali nanti)

​

Manajemen API

Endpoint berikut memungkinkan Anda untuk membuat, memperbarui, mengambil, mengarsipkan, dan mengatur koleksi produk secara terprogram — termasuk mengelola grup bersarang dan produk di dalamnya.

Ambil semua koleksi produk yang terkait dengan akun Anda menggunakan permintaan GET ke endpoint /product-collections. Mendukung paginasi, pemfilteran berdasarkan merek, dan termasuk koleksi yang diarsipkan.

Lihat struktur permintaan dan respons detail dalam dokumentasi API Daftar Koleksi Produk.

Buat koleksi produk baru dengan mengirimkan permintaan POST ke endpoint /product-collections dengan detail seperti nama, deskripsi, dan merek.

Lihat struktur permintaan dan respons detail dalam dokumentasi API Buat Koleksi Produk.

Dapatkan informasi detail tentang koleksi produk tertentu — termasuk grup dan item produknya — menggunakan permintaan GET ke endpoint /product-collections/{id}.

Lihat struktur permintaan dan respons detail dalam dokumentasi API Dapatkan Koleksi Produk.

Ubah detail koleksi produk (nama, deskripsi, merek, dll.) dengan mengirimkan permintaan PATCH ke endpoint /product-collections/{id}.

Lihat struktur permintaan dan respons detail dalam dokumentasi API Perbarui Koleksi Produk.

Asosiasikan gambar dengan koleksi dengan mengunggahnya melalui URL yang telah ditandatangani sebelumnya. Minta URL unggah dari endpoint /product-collections/{id}/images, kemudian PUT gambar ke URL yang dikembalikan dalam waktu 60 detik.

URL yang telah ditandatangani sebelumnya akan kedaluwarsa dalam 60 detik, jadi gambar harus diunggah dalam rentang waktu tersebut.

Lihat struktur permintaan dan respons detail dalam dokumentasi API Perbarui Gambar Koleksi.

Arsipkan koleksi dengan mengirimkan permintaan DELETE ke endpoint /product-collections/{id}. Ini menyembunyikan koleksi dari penggunaan baru tetapi tidak menghapusnya secara permanen.

Lihat struktur permintaan dan respons detail dalam dokumentasi API Arsipkan Koleksi Produk.

Pulihkan koleksi yang diarsipkan dengan mengirimkan permintaan POST ke endpoint /product-collections/{id}/unarchive.

Lihat struktur permintaan dan respons detail dalam dokumentasi API Pulihkan Koleksi Produk.

Grup memungkinkan Anda mengatur produk di dalam koleksi (misalnya, “Rencana Bulanan” vs. “Rencana Tahunan”). Gunakan endpoint grup untuk menambah, memperbarui, atau menghapus grup dalam koleksi.

• Buat grup: POST /product-collections/{id}/groups
• Perbarui grup: PATCH /product-collections/{id}/groups/{group_id}
• Hapus grup: DELETE /product-collections/{id}/groups/{group_id}

Tambahkan grup baru ke koleksi produk. Ubah nama atau atribut grup. Hapus grup dari koleksi.

Kelola item produk individual di dalam grup — tambahkan produk baru, perbarui item yang sudah ada (seperti urutan tampilan), atau hapus sepenuhnya.

• Tambahkan produk ke grup: POST /product-collections/{id}/groups/{group_id}/items
• Perbarui item grup: PATCH /product-collections/{id}/groups/{group_id}/items/{item_id}
• Hapus item grup: DELETE /product-collections/{id}/groups/{group_id}/items/{item_id}

Tambahkan satu atau lebih produk ke grup dalam koleksi. Perbarui item produk dalam grup. Hapus item produk dari grup.

​

Praktik Terbaik

• Kelompokkan secara logis: Atur produk berdasarkan interval penagihan (bulanan/tahunan) atau tingkat fitur (pemula/pro/enterprise)
• Atur secara strategis: Letakkan rencana paling populer atau yang direkomendasikan terlebih dahulu, karena akan dipilih sebelumnya saat checkout
• Gunakan nama yang jelas: Nama produk harus jelas menyampaikan perbedaan nilai
• Aktifkan kedua arah: Izinkan naik atau turun peringkat untuk memberikan fleksibilitas kepada pelanggan
• Pertimbangkan proration: Pilih mode proration yang sesuai dengan model bisnis Anda
• Uji secara menyeluruh: Verifikasi aliran checkout dan perubahan rencana dalam mode uji sebelum ditayangkan

Anda siap untuk membuat koleksi produk dan menawarkan pelanggan pengalaman pemilihan rencana yang terpadu.

Buat produk sekali pakai, berlangganan, atau berbasis penggunaan untuk ditambahkan ke koleksi.

Tampilkan produk koleksi dalam pengalaman checkout terpadu.

Biarkan pelanggan naik atau turun peringkat dalam koleksi yang sama.

Kelola rencana berulang dengan proration dan perubahan rencana.