Skip to main content
An addon is a purchasable unit you sell on top of a subscription: extra API capacity, a support tier, a usage booster, or a one-off setup fee added when the subscription is created. You define the addon once in the product catalogue, then attach it to individual subscriptions. Each attachment creates an addon association with its own start date, end date, and status, so the same addon can be sold to many subscriptions, or several times to the same one.

​
What an addon carries

An addon groups the same building blocks as a plan: All three are optional, with one constraint: an addon needs at least one charge that is compatible with the subscription before it can be attached. An addon that only carries entitlements cannot be attached.

​
Addon cadence

Cadence is chosen per attachment, not on the addon itself. The same addon can be recurring on one subscription and one-time on another.

​
Multiple instances

There is no uniqueness rule on the subscription and addon pair. Attaching the same addon twice is the supported way to buy two of it: each attachment gets its own association, its own line items, and its own copy of the addon’s entitlements. To sell several units under a single attachment instead, override the charge quantity when attaching. See quantity. Credit grants are tracked per addon, not per attachment: removing one attachment stops future credit grants for every attachment of that addon on the subscription.

​
Compatibility rules

At attach time, Flexprice selects the addon charges that fit the subscription:
  • The charge currency must match the subscription currency.
  • The charge billing period, together with its count, must equal the subscription’s or divide evenly into it. A monthly addon charge attaches to a monthly, quarterly, or annual subscription; a quarterly charge does not attach to a monthly one.
  • Daily and weekly charges must match the subscription’s period exactly, so a daily charge does not attach to a weekly subscription.
  • One-time charges skip the billing period check, but their currency must still match.
If no charge qualifies, the attachment is rejected.
Add an addon carrying a one-time charge, such as a setup fee, when the subscription is created; the charge bills on the first invoice. On an existing subscription, attach it with proration_behavior: "none" and change_at: "end_of_period" to bill it on the renewal invoice. Attached mid-period with none, the one-time charge is never invoiced, and with create_prorations the attach fails.

​
Lifecycle

The addon’s status and each association’s addon_status are separate. addon_status changes only when a pending attach is paid or the addon is removed. A future-dated attach is already active before it starts, and a onetime association stays active after its end_date.

​
Where addons appear

  • Subscription line items carry entity_type: "addon" and the association ID. In the dashboard, the charges table shows an Addon chip in its Source column when a subscription mixes plan and addon charges.
  • Invoices bill addon line items like any other line item.
  • Entitlements from addons merge into the subscription’s totals, listed with an addon source. Stacking (additive or parallel) controls how they combine with the plan’s allowances; see Entitlement grants.
  • Webhooks: addon changes fire subscription.updated. There are no separate addon.* events.

​
Quick start

  1. Create an addon and give it charges, entitlements, or credit grants.
  2. Add it to a subscription at creation time or through the subscription modification API.