Create an Addon

An addon is created empty, then configured with charges, entitlements, and credit grants through the same APIs plans use. Only the charges are required before the addon can be attached to a subscription.

Via API

curl -X POST https://us.api.flexprice.io/v1/addons \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Support",
    "lookup_key": "addon-premium-support",
    "description": "24x7 support with a 1 hour response SLA"
  }'

Response

{
  "id": "addon_01JD2K3F4G5H6J7K8L9M0N1P2Q",
  "environment_id": "env_01K1TJJF0CJR410C6QVPYQTNV0",
  "tenant_id": "tenant_01K1TJDVNSN7TWY8CZY870QMNV",
  "name": "Premium Support",
  "lookup_key": "addon-premium-support",
  "description": "24x7 support with a 1 hour response SLA",
  "status": "published",
  "created_at": "2026-09-26T10:00:00Z",
  "updated_at": "2026-09-26T10:00:00Z",
  "created_by": "user_01K1TJDVNSN7TWY8CZY870QMNW",
  "updated_by": "user_01K1TJDVNSN7TWY8CZY870QMNW"
}

Request fields

Field	Type	Required	Description
`name`	string	Yes	Display name shown in the dashboard. Fixed charges created on the addon default their `display_name` to it.
`lookup_key`	string	Yes	Stable identifier for API calls. Unique among published addons and immutable after creation.
`description`	string	No	Internal note about what the addon is for
`metadata`	object	No	Key-value pairs for your own tracking

Add charges

Charges are prices created with entity_type: "ADDON". They use the same billing models, periods, and invoice cadences as plan prices. A fixed monthly charge billed in advance:

curl -X POST https://us.api.flexprice.io/v1/prices \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "ADDON",
    "entity_id": "<addon_id>",
    "type": "FIXED",
    "billing_model": "FLAT_FEE",
    "billing_period": "MONTHLY",
    "billing_period_count": 1,
    "invoice_cadence": "ADVANCE",
    "price_unit_type": "FIAT",
    "currency": "usd",
    "amount": "49"
  }'

A usage-based charge metered against a feature, billed in arrear:

curl -X POST https://us.api.flexprice.io/v1/prices \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "ADDON",
    "entity_id": "<addon_id>",
    "type": "USAGE",
    "meter_id": "<meter_id>",
    "billing_model": "FLAT_FEE",
    "billing_period": "MONTHLY",
    "billing_period_count": 1,
    "invoice_cadence": "ARREAR",
    "price_unit_type": "FIAT",
    "currency": "usd",
    "amount": "0.02"
  }'

Points specific to addon charges:

display_name defaults to the addon’s name on fixed charges.
min_quantity on a fixed charge becomes the default quantity when the addon is attached.
A charge’s billing period does not have to match the subscription’s. At attach time, a charge is included when its period equals the subscription period or divides evenly into it, and one-time charges are always included. See compatibility rules.
POST /v1/prices/bulk creates several charges in one call.

Add entitlements

Entitlements are created with entity_type: "ADDON" and carry the same fields as plan entitlements:

curl -X POST https://us.api.flexprice.io/v1/entitlements \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "ADDON",
    "entity_id": "<addon_id>",
    "feature_id": "<feature_id>",
    "feature_type": "metered",
    "usage_limit": 50000,
    "usage_reset_period": "MONTHLY",
    "aggregation_mode": "additive"
  }'

aggregation_mode controls stacking when the customer also holds a plan allowance on the same feature: additive merges both into one pool, parallel keeps a separate window per source. parallel works only for grant-based allowances; on a legacy allowance it fails with Parallel buckets only exist for grant-based entitlements; legacy entitlements always aggregate additively. Entitlement grants covers stacking, grant quotas, and the other fields in detail.

Every attachment adds its own copy of the addon’s entitlements. A subscription holding the same addon twice gets twice the allowance.

Add credit grants

A credit grant on an addon is a template. Nothing is granted until the addon is attached to a subscription; at that point the grant is cloned to the subscription and credits the customer’s prepaid wallet.

curl -X POST https://us.api.flexprice.io/v1/creditgrants \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "ADDON",
    "addon_id": "<addon_id>",
    "name": "Booster credits",
    "credits": "100",
    "cadence": "RECURRING",
    "period": "MONTHLY",
    "period_count": 1,
    "priority": 1,
    "expiration_type": "BILLING_CYCLE"
  }'

scope: "ADDON" requires addon_id, and the addon must be published.
start_date and end_date are not allowed on addon-scoped grants; the association’s dates apply instead.
All grants on one addon must share the same conversion_rate and topup_conversion_rate.

Manage existing addons

# Get an addon (embeds its prices, entitlements, and credit grants)
curl https://us.api.flexprice.io/v1/addons/<addon_id> \
  -H "x-api-key: <API_KEY>"

# Get by lookup key (published addons only)
curl https://us.api.flexprice.io/v1/addons/lookup/<lookup_key> \
  -H "x-api-key: <API_KEY>"

# Search addons
curl -X POST https://us.api.flexprice.io/v1/addons/search \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "lookup_keys": ["addon-premium-support"] }'

# Update an addon (name, description, and metadata only)
curl -X PUT https://us.api.flexprice.io/v1/addons/<addon_id> \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Premium Support Plus" }'

# Archive an addon
curl -X DELETE https://us.api.flexprice.io/v1/addons/<addon_id> \
  -H "x-api-key: <API_KEY>"

Deleting is a soft delete: the addon’s status becomes archived and it can no longer be attached. Only an addon that no subscription has ever used can be archived. Any active association, or any line item left by a past attachment, blocks the delete, which fails with Addon is currently active on one or more subscriptions. Remove it from all subscriptions before deleting.

Via dashboard

Create the addon

Go to Product catalog > Add-ons and click New add-on.

The Add-ons list under Product catalog with the New add-on button

Fill in the Name, an optional Description, and the Lookup key (it fills in from the name and cannot be changed later), then click Create add-on. You land on the new addon’s page.

The Create add-on form with a name, description, and lookup key

Add charges

On the Charges tab, click Add charges. Choose Fixed or Usage and click Continue, fill in the currency, billing period, billing model, and price (a usage charge also needs its Metered feature), and click Create charge. Repeat for each charge.

Add entitlements

On the Entitlements tab, click Add entitlement and select a Feature. For a metered feature, set the Value type, the Value (or Unlimited), and the Usage resets window. Advanced holds Window starts and Stacking (Additive or Parallel). Click Create entitlement.

Add credit grants

On the Credit grants tab, click Add credit grant. Choose One-time or Recurring, set the Name, Credits, Expiry, and Priority (and optionally a Conversion rate), and click Create credit grant.

The addon page groups its configuration in tabs: Charges, Entitlements, Credit grants, Contracts, and Information.

An addon page on the Charges tab with one fixed charge

To archive from the dashboard, select Archive in the ⋯ menu on the addon’s page, or Archive add-on in the list’s row menu. The list shows published addons by default; set its Status filter to Archived to see archived ones.

Next step

Add the addon to a subscription at creation time or through the subscription modification API.

Start Here

Usage Metering

Pricing and Packaging

Entitlements

Customers

Subscriptions

Credits and Wallets

Enterprise Billing

Invoicing and Taxes

Payments and Checkout

Reporting and Data

Self-hosting

Platform and Security

Via API

Request fields

Add charges

Add entitlements

Add credit grants

Manage existing addons

Via dashboard

Next step