This endpoint is the starting point for any add-on purchase or upgrade flow — call it first to get available options and their product_id values, then pass those IDs into the proration or subscription update endpoints.
Common use cases:
- Add-on pricing display — Render a live add-on marketplace in your billing UI showing real prices per interval and currency without hardcoding values.
- Currency-aware pricing — Filter by currency to show the correct price based on your billing region (e.g. EUR vs USD).
- Interval comparison — Show monthly vs yearly pricing side by side by grouping variants with the same add_on_key but different interval values — yearly variants typically offer a discount.
- Proration preparation — Collect the product_id of your chosen variant and pass it into the proration endpoint before confirming to see an accurate cost preview.
- Programmatic plan building — Use add_on_key to identify add-on types in your codebase independently of price IDs.
Authorization: Bearer YOUR_TOKEN
Expected Behavior:
- On success, you receive a flat array of all available add-on variants, grouped logically by add_on_key and differentiated by interval and currency.
- The same add-on (e.g. SMS) will appear up to 4 times — monthly USD, monthly EUR, yearly USD, yearly EUR. Always filter by both interval and currency to select the correct variant for your billing region.
- Use add_on_key to group variants of the same add-on type in your UI rather than relying on title, which is a display value only.
- If your request fails, an appropriate error message will be returned.