Add Addons to a Subscription

​

Before you start

• The addon must be published.
• The subscription must be active or draft. Trialing subscriptions cannot take addons.
• The addon needs at least one charge compatible with the subscription: same currency, and a billing period that equals or divides evenly into the subscription’s (daily and weekly charges must match it exactly). An addon with no compatible charge, including an entitlement-only addon, is rejected. See compatibility rules.
• One-time charges qualify whatever their billing period, and each bills on the invoice whose period contains its start date. On an existing subscription, a one-time charge attached with none to start mid-period is never invoiced, because that period’s advance invoice has already gone out; attach it with change_at: "end_of_period" to bill it on the renewal invoice. With create_prorations, attaching or removing an addon that carries a one-time charge fails with line item billing_period must equal or strictly divide the subscription billing_period.
• Metered features must not conflict: if the plan, an addon already on the subscription, or another addon in the same request entitles the same feature, their usage_reset_period values have to agree, or the request fails with Feature <feature_id> is already measured over <period>, but this addon measures it over <period>. The exception is an addon removed in the same request: when it ends on or before the new addon starts, their reset periods may differ, so you can swap them in one request.
• A future-dated change cannot cut into a running entitlement grant window. That covers attaching an addon that grants a metered feature with a grant window already running on the subscription, and removing an addon whose grant window is running. Apply such changes immediately or at the period end; a date in between fails with Apply this change immediately, or schedule it for the period end.

​

At subscription creation

curl -X POST https://us.api.flexprice.io/v1/subscriptions \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "<customer_id>",
    "plan_id": "<plan_id>",
    "currency": "usd",
    "billing_period": "MONTHLY",
    "start_date": "2026-10-01T00:00:00Z",
    "addons": [
      { "addon_id": "<addon_id>" },
      {
        "addon_id": "<addon_id_2>",
        "cadence": "onetime",
        "override_line_items": [
          { "price_id": "<price_id>", "quantity": 3 }
        ]
      }
    ]
  }'

• start_date defaults to the subscription start date.
• No separate proration settlement is created at creation. The addon’s in-advance charges land on the subscription’s first invoice, and its in-arrear charges on the period-end invoice.
• An addon start_date after the subscription start is charged only for the time it covers. A short first period from a calendar billing cycle is prorated only when the subscription is created with proration_behavior: "create_prorations".
• The new subscription must start active or draft. If it starts trialing, or incomplete because of its payment_behavior, the request fails with Addon can only be added to active or draft subscriptions.
• A single request accepts at most 20 addon entries.

​

Attach addons to an existing subscription

curl -X POST https://us.api.flexprice.io/v1/subscriptions/<subscription_id>/modify/execute \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "addon",
    "addon_bulk_params": {
      "adds": [
        {
          "addon_id": "<addon_id>",
          "proration_behavior": "create_prorations"
        },
        {
          "addon_id": "<addon_id_2>",
          "change_at": "end_of_period"
        }
      ]
    }
  }'

{
  "subscription": { "...": "..." },
  "changed_resources": {
    "addon_associations": [
      {
        "id": "addon_assoc_01JD2M4G5H6J7K8L9M0N1P2Q3R",
        "addon_id": "addon_01JD2K3F4G5H6J7K8L9M0N1P2Q",
        "addon_status": "active",
        "start_date": "2026-10-12T10:00:00Z",
        "change_action": "created"
      },
      {
        "id": "addon_assoc_01JD2M4G5H6J7K8L9M0N1P2Q3S",
        "addon_id": "addon_01JD2K3F4G5H6J7K8L9M0N1P2R",
        "addon_status": "active",
        "start_date": "2026-11-01T00:00:00Z",
        "change_action": "created"
      }
    ],
    "line_items": [ { "change_action": "created" } ],
    "invoices": [ { "action": "created", "status": "PENDING" } ]
  }
}

​

Addon attach fields

​

Addon quantity

• Override the charge quantity: pass override_line_items with the fixed charge’s price_id and the quantity. This is what the dashboard’s Quantity input does.
• Attach the addon again: list the same addon_id more than once in adds, or attach it again in a later request. Each attachment is an independent association with its own line items and entitlements, so two attachments of a seat addon are two seats.

​

Remove addons from a subscription

curl -X POST https://us.api.flexprice.io/v1/subscriptions/<subscription_id>/modify/execute \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "addon",
    "addon_bulk_params": {
      "removes": [
        {
          "addon_association_id": "<addon_association_id>",
          "effective_date": "2026-10-15T00:00:00Z",
          "proration_behavior": "create_prorations"
        }
      ]
    }
  }'

​

Addon removal fields

• The default, removing at period end, produces zero credit: the customer keeps the addon until the date they already paid for.
• A onetime addon cannot be removed at all: attaching it already set its end date, so a removal fails with This addon is already marked for removal.
• An addon that carries a one-time charge can be removed only without create_prorations; with it, the removal fails with line item billing_period must equal or strictly divide the subscription billing_period.
• The association’s addon_status flips to cancelled as soon as the removal is accepted, even when the end date is in the future. Billing and entitlements continue until the end_date, but the association no longer appears in GET /v1/subscriptions/{id}/addons/associations, which lists active associations only.
• A second removal of the same association fails with This addon is already marked for removal.

​

Attach and remove addons in one request

curl -X POST https://us.api.flexprice.io/v1/subscriptions/<subscription_id>/modify/execute \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "addon",
    "addon_bulk_params": {
      "removes": [
        {
          "addon_association_id": "<basic_support_association_id>",
          "change_at": "immediate",
          "proration_behavior": "create_prorations"
        }
      ],
      "adds": [
        {
          "addon_id": "<premium_support_addon_id>",
          "change_at": "immediate",
          "proration_behavior": "create_prorations"
        }
      ]
    }
  }'

• A request holds between 1 and 20 entries across adds and removes.
• The same addon may appear more than once in adds. An association may appear only once in removes; a repeat fails with Each addon association can be removed at most once per request.
• Each entry keeps its own timing and proration setting, with one exception: two attaches that start within the current period and grant the same feature through entitlement grants must use the same start date, or the request fails with Send them as separate changes, or give both the same date.
• Everything runs in a single transaction: removals first, then attaches. If any entry fails, nothing is applied.
• An addon removed here no longer blocks a replacement that measures the same metered feature over a different reset period, as long as the removal takes effect no later than the attach. See Before you start.
• All charges and credits from the request are netted into one settlement document, described below.
• The response lists every association the request touched: attaches with change_action: "created", and removals with change_action: "ended", addon_status: "cancelled", and their end_date.

​

Proration and settlement

• Fixed charges billed in advance are prorated on attach, and credited for unused time on removal, capped at what was invoiced for the period containing the removal date, or at list price when nothing has been invoiced for it yet.
• Fixed charges billed in arrear raise no upfront charge; the next invoice bills the prorated amount.
• Usage charges are never prorated; usage is billed at period end as usual.
• A charge on a different cadence from the subscription is prorated against its own period, not the subscription’s.

​

Entitlements and credit grants on attach

• The addon’s entitlements join the subscription’s from the association start and leave at its end. With create_prorations, a mid-cycle attach prorates entitlement grant quotas for the time left in the window, and the first credit grant for the time left in the period; with none, both are granted in full. Quota already granted is never taken back.
• The override_entitlements array on subscription creation rejects addon entitlements.
• The addon’s credit grants are cloned to the subscription and credit the prepaid wallet. Recurring grants repeat each period while the association is active. Removing the addon cancels future grant applications without clawing back credits already granted. Grants are tracked per addon, not per attachment, so removing one attachment of a duplicated addon stops future grants for all of its attachments.

​

Payment-gated addon changes

{
  "type": "addon",
  "checkout": {
    "payment_provider": "razorpay",
    "success_url": "https://example.com/success"
  },
  "addon_bulk_params": {
    "adds": [
      { "addon_id": "<addon_id>", "proration_behavior": "create_prorations" }
    ]
  }
}

• Checkout requires an active subscription; a request against a draft subscription is rejected.
• override_line_items and line_item_commitments cannot be combined with checkout; the request is rejected.
• Only entries with create_prorations put an amount on the checkout. When the netted amount is not a charge, including when no entry uses create_prorations, no session opens and the change applies immediately without payment. The request must still pass the checks above.
• While payment is pending, each attached association’s addon_status is pending: no line items, no entitlements, no credit grants. Removals in the same request wait too; the addons they end stay active until the customer pays.
• Completion applies the whole change, removals included. Expiry or cancellation of the session archives the pending associations, and the removals never happen.
• While the session is open, an addon it is set to remove cannot be removed by another request (Complete or cancel the pending checkout for this subscription first), and neither can a pending association (Complete or cancel the pending checkout for this addon first).
• One open checkout session is allowed per subscription.

​

Plan changes and cancellation

• A swap-in-place plan change (/change/v2) keeps addon associations by default. Its entity_policies.addons object sets a default_behaviour of carry or drop, with per-association overrides. Dropped addons end at the change, and are credited for unused time only when the change uses proration_behavior: "create_prorations" or billing_period_behaviour: "anchor_at_effect".
• The legacy plan change (/change/execute) cancels the subscription and creates a new one; addons are not carried over.
• Cancelling a subscription cancels its addon associations, ends their line items, and stops future credit grant applications. Scheduled cancellations do this when they take effect.

​

Webhooks

​

Via dashboard

​

While creating a subscription

1. Pick an addon under Addon. It opens as a card listing the charges compatible with the subscription’s billing period and currency. To add more, pick them under Add another addon; each gets its own card, and an addon you picked leaves the list.
2. Set the Quantity on each fixed charge. Usage charges show “pay as you go”.
3. Use a charge’s row menu for Override Price, or Configure Commitment on usage charges.
4. Optionally set a Start date on each card, then click Add addons.

​

On an existing subscription

• Remove: under Current addons, the trash icon marks an addon for removal. The row is tagged Removing and asks when it Ends: End of current period (preset), Now, or a Custom date inside the current period. Its Proration is preset to No proration; choose Prorate to credit unused time. Undo keeps the addon. An addon already scheduled to end shows its end date and cannot be marked.
• Attach: pick an addon under Addon (labelled Add addon once the subscription has addons), and more under Add another addon. Each opens as a card with its charges, quantities, overrides, and commitments, as in the subscription form. Starts sets Now (preset), End of current period, or a Custom date. Advanced options holds the Cadence (Recurring or One-time) and Proration (Prorate or No proration); opening it presets Recurring and No proration.

• Configure: changes the addon’s charges on this subscription. A fixed charge takes a new quantity, a new price on a flat-fee charge without a custom price unit, and an effective date; click Preview to see the resulting charges or credits, then Apply changes. A usage charge opens a price override with an optional effective date and the charge’s commitment settings. An addon with several charges lists them first.
• Cancel: removes that one addon. It asks for an Effective end date (preset to the current period end and limited to the current period) and a Proration choice, preset to None.

​

Legacy addon requests

• addon_params on the modification API changes one addon per request: "action": "add" with the attach fields under add, or "action": "remove" with the removal fields under remove. It is applied as a batch of one entry. It cannot be sent together with addon_bulk_params, and a removal sent this way cannot carry checkout.
• POST /v1/subscriptions/addon and DELETE /v1/subscriptions/addon are deprecated. POST takes the attach fields plus subscription_id and an optional inline checkout; DELETE takes the removal fields and finds the subscription from the association.