Add-ons for Subscriptions

Add-ons are supplementary products attached to subscriptions. Customers choose a quantity at checkout or when updating their subscription, and the add-on is billed on the parent subscription’s cycle.

Seat-Based Billing

Create add-ons for additional team seats or user licenses.

Usage Extensions

Extend usage limits, API calls, or data allowances with add-ons.

What Are Add-ons?

Add-ons are supplementary products that customers can purchase alongside their main subscription. They’re perfect for seat-based billing, feature upgrades, usage extensions, and service add-ons.

Add-ons attached to subscription products in the dashboard

Key Benefits

Add-ons enable flexible pricing models, revenue optimization through upsell opportunities, simplified management from one dashboard, and customer choice in customizing their subscriptions.

Creating Add-ons

Add-ons are created as separate products in the dashboard, then attached to subscription products. This lets you reuse add-ons across multiple subscriptions and manage pricing independently.

Add-on Configuration

When creating add-ons, you can configure:

Pricing: Set the add-on amount (price) in the smallest currency unit. The add-on is billed on the parent subscription’s cycle
Currency: Set the base price in any currency Dodo Payments can charge. The searchable currency selector pins USD, GBP, EUR, and INR to the top; customers outside your base currency are billed through Adaptive Currency
Quantity: Customers choose a quantity when the add-on is attached to a subscription
Availability: Attach the add-on to subscription products through each product’s addons list. The add-on itself has no availability setting
Tax settings: Configure the appropriate tax_category

Getting Started

Ready to implement add-ons in your subscription business? Here’s how to get started:

Plan Your Add-ons

Identify the additional features, services, or capacity that would benefit your customers as add-ons.Consider:

What do customers frequently request?
What features could be monetized separately?
What would create natural upgrade paths?

Create Your First Add-on

Use the Dodo Payments dashboard or API to create your first add-on product.

Dashboard Guide

Follow our step-by-step guide to create add-ons in the dashboard.

Attach to Subscriptions

Connect your add-ons to the appropriate subscription products where they should be available.

Test Integration

Create test checkout sessions with different add-on combinations to ensure everything works correctly.

Monitor Performance

Track add-on adoption rates and revenue impact to optimize your pricing strategy.

Common Use Cases

Seat-based billing: Additional team members, user licenses, or concurrent users
Feature upgrades: Premium features, advanced analytics, or priority support
Usage extensions: Extra storage, API calls, or bandwidth allowances
Service add-ons: Professional services, training, or consultation hours

Integration Examples

Checkout Sessions with Add-ons

When creating a checkout session, include add-ons with quantities:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_123',
      quantity: 1,
      addons: [
        {
          addon_id: 'addon_456',
          quantity: 3 // 3 additional seats
        }
      ]
    }
  ],
  customer: { email: 'customer@example.com' },
  return_url: 'https://yourapp.com/success'
});

session = client.checkout_sessions.create(
    product_cart=[
        {
            "product_id": "pdt_123",
            "quantity": 1,
            "addons": [
                {
                    "addon_id": "addon_456",
                    "quantity": 3  # 3 additional seats
                }
            ]
        }
    ],
    customer={"email": "customer@example.com"},
    return_url="https://yourapp.com/success"
)

curl -X POST https://test.dodopayments.com/checkouts \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_cart": [
      {
        "product_id": "pdt_123",
        "quantity": 1,
        "addons": [
          {
            "addon_id": "addon_456",
            "quantity": 3
          }
        ]
      }
    ],
    "customer": {"email": "customer@example.com"},
    "return_url": "https://yourapp.com/success"
  }'

To let customers add or remove add-ons themselves on the checkout page, set the allow_editing_addons feature flag to true when creating the session. It defaults to false and applies only to subscription products.

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  feature_flags: {
    allow_editing_addons: true // customers can edit add-ons at checkout
  },
});

Plan Changes with Add-ons

Modify existing subscriptions to add, remove, or update add-ons:

// Add add-ons to existing subscription
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [
    { addon_id: 'addon_123', quantity: 2 }
  ]
});

// Remove all existing add-ons
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [] // Empty array removes all existing add-ons
});

# Add add-ons to existing subscription
client.subscriptions.change_plan(
    'sub_123',
    product_id='pdt_new',
    quantity=1,
    proration_billing_mode='difference_immediately',
    addons=[
        {'addon_id': 'addon_123', 'quantity': 2}
    ]
)

# Remove all existing add-ons
client.subscriptions.change_plan(
    'sub_123',
    product_id='pdt_new',
    quantity=1,
    proration_billing_mode='difference_immediately',
    addons=[]
)

Dynamic Pricing

Calculate total costs dynamically based on add-on selections:

interface AddonSelection {
  price: number;
  quantity: number;
}

function calculateTotalCost(basePrice: number, addons: AddonSelection[]) {
  const addonTotal = addons.reduce((sum, addon) => 
    sum + (addon.price * addon.quantity), 0
  );
  return basePrice + addonTotal;
}

API Management

Dodo Payments provides a comprehensive API for managing add-ons programmatically:

Create Add-ons

Use the POST /addons endpoint to create new add-ons with custom pricing, descriptions, and configuration options.

API Reference

View the complete API documentation for creating add-ons.

Update Add-ons

Modify existing add-ons using the PATCH /addons/{id} endpoint to update pricing, descriptions, or tax categories.

API Reference

Learn how to update add-on details programmatically.

List and Retrieve

Use GET /addons to list all add-ons or GET /addons/{id} to retrieve specific add-on details.

API Reference

Access the complete listing and retrieval API documentation.

Image Management

Update add-on images using the PUT /addons/{id}/images endpoint for better product presentation.

API Reference

Learn how to manage add-on images via API.

Best Practices

Start simple: Launch with 2-3 core add-ons and expand options based on customer feedback and usage.
Maintain pricing clarity: Clearly communicate add-on pricing and value, so customers understand what they’re getting for the extra cost.
Test thoroughly: Validate add-on combinations to ensure pricing calculations remain accurate and checkout flows function smoothly.

Design Considerations

Clear Value Proposition: Each add-on should have a clear benefit that customers can understand
Logical Grouping: Group related add-ons together in your checkout flow
Flexible Quantities: Allow customers to adjust quantities of add-ons as needed
Transparent Pricing: Show total costs clearly throughout the checkout process

Seat-Based Billing

Guide to implementing per-seat pricing with add-ons.

Checkout Sessions

Full checkout session API and configuration.

Subscriptions

Subscription lifecycle, billing cycles, and renewal.

Adaptive Currency

Show prices in local currencies at checkout.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Seat-Based Billing

Usage Extensions

What Are Add-ons?

Key Benefits

Creating Add-ons

Add-on Configuration

Getting Started

Dashboard Guide

Common Use Cases

Integration Examples

Checkout Sessions with Add-ons

Plan Changes with Add-ons

Dynamic Pricing

API Management

API Reference

API Reference

API Reference

API Reference

Best Practices

Design Considerations

Seat-Based Billing

Checkout Sessions

Subscriptions

Adaptive Currency

Seat-Based Billing

Usage Extensions

​What Are Add-ons?

​Key Benefits

​Creating Add-ons

​Add-on Configuration

​Getting Started

Dashboard Guide

​Common Use Cases

​Integration Examples

​Checkout Sessions with Add-ons

​Plan Changes with Add-ons

​Dynamic Pricing

​API Management

API Reference

API Reference

API Reference

API Reference

​Best Practices

​Design Considerations

​Related

Seat-Based Billing

Checkout Sessions

Subscriptions

Adaptive Currency

What Are Add-ons?

Key Benefits

Creating Add-ons

Add-on Configuration

Getting Started

Common Use Cases

Integration Examples

Checkout Sessions with Add-ons

Plan Changes with Add-ons

Dynamic Pricing

API Management

Best Practices

Design Considerations

Related