API REFERENCE
Add-ons
Add-ons are merchant-scoped extras that can be invoiced on top of a plan: recurring with an interval, or billed exactly once.
Create an add-on
Recurring add-ons carry an interval and interval count. One-time add-ons are billed on attachment and flagged as billed.
| Method | Path | Purpose | Permission |
|---|---|---|---|
| POST | /merchants/:merchantId/add-ons | Create a recurring or one-time add-on. | addons:write |
| GET | /merchants/:merchantId/add-ons | List add-ons. Filter with type and active. | addons:read |
| GET | /merchants/:merchantId/add-ons/:addOnId | Read one add-on with its plan attachments. | addons:read |
| PATCH | /merchants/:merchantId/add-ons/:addOnId | Update name, price, limits or proration behaviour. | addons:write |
| POST | /merchants/:merchantId/add-ons/:addOnId/archive | Archive without deleting history. | addons:write |
| POST | /merchants/:merchantId/add-ons/:addOnId/restore | Restore an archived add-on. | addons:write |
| Field | Type | Required | Notes |
|---|---|---|---|
| name | string | Yes | — |
| description | string | No | — |
| type | recurring | one_time | Yes | — |
| interval | daily | weekly | monthly | yearly | No | Required for recurring add-ons. |
| intervalCount | integer | No | — |
| price | number | Yes | — |
| currency | string | Yes | — |
| taxInclusive | boolean | No | — |
| maxQuantity | integer | No | Enforced when the add-on is attached or its quantity changes. |
| prorationBehavior | prorate | full_period | none | No | — |
Plan eligibility and subscription add-ons
An add-on must be attached to a plan before a subscription on that plan can use it.
| Method | Path | Purpose | Permission |
|---|---|---|---|
| POST | /merchants/:merchantId/plans/:planId/add-ons | Replace the plan's add-on eligibility list. | addons:write |
| DELETE | /merchants/:merchantId/plans/:planId/add-ons/:addOnId | Remove an add-on from a plan. | addons:write |
| GET | /merchants/:merchantId/subscriptions/:subscriptionId/add-ons | Active and cancelled add-ons with recurring amounts. | addons:read |
| POST | /merchants/:merchantId/subscriptions/:subscriptionId/add-ons | Attach an add-on; optionally charge immediately. | addons:write |
| PATCH | /merchants/:merchantId/subscriptions/:subscriptionId/add-ons/:subscriptionAddOnId | Change quantity within maxQuantity. | addons:write |
| DELETE | /merchants/:merchantId/subscriptions/:subscriptionId/add-ons/:subscriptionAddOnId | Cancel the add-on; billed periods are untouched. | addons:write |
Error behaviour
- 400 when a quantity exceeds the add-on's maxQuantity.
- 400 when the add-on currency does not match the subscription currency.
- 409 when the same add-on is already active on the subscription.
Add-on revenue appears as its own line item on invoices, so finance can reconcile recurring extras separately from the base plan fee.