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 to users based on their 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 the chosen variant and pass it into the proration endpoint before charging to show the user an accurate cost preview.
- Programmatic plan building — Use add_on_key to identify add-on types in your codebase independently of price IDs, which may change across environments or regions.
Authorization: Bearer YOUR_TOKEN
Expected Behavior:
- On success, the system returns 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 a given user.
- 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 the request fails, an appropriate error message will be returned.