> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Add-ons for Subscriptions
> Attach add-ons to subscriptions for seat-based billing, feature upgrades, and flexible pricing. Customers choose quantities at checkout or via the API.
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.
Create add-ons for additional team seats or user licenses.
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.
## 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](/features/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:
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?
Use the Dodo Payments dashboard or API to create your first add-on product.
Follow our step-by-step guide to create add-ons in the dashboard.
Connect your add-ons to the appropriate subscription products where they should be available.
Create test checkout sessions with different add-on combinations to ensure everything works correctly.
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:
```typescript Node.js theme={null}
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'
});
```
```python Python theme={null}
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"
)
```
```bash cURL theme={null}
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`](/developer-resources/checkout-session#optional-fields) feature flag to `true` when creating the session. It defaults to `false` and applies only to subscription products.
```typescript theme={null}
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:
```typescript Node.js theme={null}
// 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
});
```
```python Python theme={null}
# 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:
```typescript theme={null}
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:
Use the `POST /addons` endpoint to create new add-ons with custom pricing, descriptions, and configuration options.
View the complete API documentation for creating add-ons.
Modify existing add-ons using the `PATCH /addons/{id}` endpoint to update pricing, descriptions, or tax categories.
Learn how to update add-on details programmatically.
Use `GET /addons` to list all add-ons or `GET /addons/{id}` to retrieve specific add-on details.
Access the complete listing and retrieval API documentation.
Update add-on images using the `PUT /addons/{id}/images` endpoint for better product presentation.
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
## Related
Guide to implementing per-seat pricing with add-ons.
Full checkout session API and configuration.
Subscription lifecycle, billing cycles, and renewal.
Show prices in local currencies at checkout.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.