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.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

​

Dashboard Operations

• Create: Set up new collections with products and groups
• Update: Modify name, description, image, and product organization
• Reorder: Drag and drop to change product display order
• Enable/Disable products: Control which products appear in checkout
• Delete: Remove a collection (products remain but are unlinked)

​

Best Practices

• Group logically: Organize products by billing interval (monthly/annual) or feature tier (starter/pro/enterprise)
• Order strategically: Place your most popular or recommended plan first, as it will be pre-selected at checkout
• Use clear naming: Product names should clearly communicate value differences
• Enable both directions: Allow both upgrades and downgrades to give customers flexibility
• Consider proration: Choose a proration mode that aligns with your business model
• Test thoroughly: Verify checkout and plan change flows in test mode before going live