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.

MethodPathPurposePermission
POST/merchants/:merchantId/add-onsCreate a recurring or one-time add-on.addons:write
GET/merchants/:merchantId/add-onsList add-ons. Filter with type and active.addons:read
GET/merchants/:merchantId/add-ons/:addOnIdRead one add-on with its plan attachments.addons:read
PATCH/merchants/:merchantId/add-ons/:addOnIdUpdate name, price, limits or proration behaviour.addons:write
POST/merchants/:merchantId/add-ons/:addOnId/archiveArchive without deleting history.addons:write
POST/merchants/:merchantId/add-ons/:addOnId/restoreRestore an archived add-on.addons:write
FieldTypeRequiredNotes
namestringYes—
descriptionstringNo—
typerecurring | one_timeYes—
intervaldaily | weekly | monthly | yearlyNoRequired for recurring add-ons.
intervalCountintegerNo—
pricenumberYes—
currencystringYes—
taxInclusivebooleanNo—
maxQuantityintegerNoEnforced when the add-on is attached or its quantity changes.
prorationBehaviorprorate | full_period | noneNo—

Plan eligibility and subscription add-ons

An add-on must be attached to a plan before a subscription on that plan can use it.

MethodPathPurposePermission
POST/merchants/:merchantId/plans/:planId/add-onsReplace the plan's add-on eligibility list.addons:write
DELETE/merchants/:merchantId/plans/:planId/add-ons/:addOnIdRemove an add-on from a plan.addons:write
GET/merchants/:merchantId/subscriptions/:subscriptionId/add-onsActive and cancelled add-ons with recurring amounts.addons:read
POST/merchants/:merchantId/subscriptions/:subscriptionId/add-onsAttach an add-on; optionally charge immediately.addons:write
PATCH/merchants/:merchantId/subscriptions/:subscriptionId/add-ons/:subscriptionAddOnIdChange quantity within maxQuantity.addons:write
DELETE/merchants/:merchantId/subscriptions/:subscriptionId/add-ons/:subscriptionAddOnIdCancel 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.