Mid-Term Subscription Change Scenarios in Usage Based Billing

Introduction

This document describes how mid-term subscription changes behave in Usage Based Billing for non-metered (prepaid) items and metered (postpaid) usage-based addons, including proration, credits, entitlements, and overage invoicing.

This document is intended for:

• Billing admins and operations users managing subscriptions mid-cycle.
• Support teams explaining proration and overage outcomes to customers.
• Developers implementing subscription changes via API.

Sample Subscription

Throughout this document, the following baseline subscription is used for examples:

• Subscription start date: Jun 1
• Billing period: Monthly (Jun 1 – Jun 30)
• Usage at time of change: 60,000 tasks already consumed when change is initiated on Jun 15

Subscription Line Items:

Key concepts used in this document

• Prepaid/non-metered item: Charged in advance for the term (e.g., a monthly plan fee). Proration and credit notes apply when changing mid-term.
• Postpaid/metered addon: Charged based on usage, typically invoiced at the end of the term.
• Entitlements/included usage: Units included with a plan/addon (e.g., tasks per month). These affect overage calculations.
• Billing period: The date range for which an item's charges apply. Drives when invoices are generated and when overages are settled.
• Entitlement grant period: The date range during which a granted entitlement quota is valid and can be consumed. By default, this matches the billing period of the item granting the entitlement.
• Prorated charge: A new charge computed for the remaining portion of the billing term after a change.
• Prorated adjustment credit note: A credit computed for the unused portion of a prepaid item being replaced or repriced.

Scenario 1: Changing the price of a plan/addon mid-term

Scenario

You update the price of a plan or addon while the subscription is active.

Behavior

If the item is non-metered (prepaid)

• A prorated adjustment credit note is created for the unused prepaid portion at the old price.
• A new prorated invoice is created for the remaining period at the new price.
• The new recurring price applies starting the next billing cycle.
• The entitlement grant period is not reset by a price change alone.

If the item is metered (postpaid)

• The new price is applied for the entire term (from the beginning of the term).
• All usage overages for that term, including usage recorded before the price change are billed at the updated rate at the end of the term.
• The entitlement grant period is not affected by the price change.

Note: Because the updated price applies retroactively to all unbilled usage in the current term, avoid mid-term price changes for metered items unless you intend all usage in that term to be billed at the new rate.

Example 1: Non-metered (prepaid) plan price change

Change date: Jun 15

Change: Professional Monthly price changes from $50 → $60

Example 2: Metered (postpaid) addon price change

Change date: Jun 15

Change: Tasks Monthly overage price changes from $0.10 → $0.20 per task

Scenario 2: Changing a plan or prepaid addon mid-term

Scenario

You switch a customer from one plan to another higher-value plan (upgrade), or swap a prepaid addon mid-term.

Behavior

When a plan or prepaid addon is changed mid-term:

• The old plan/addon remains active until the change time.
• A prorated adjustment credit note is created for the unused portion of the old prepaid plan/addon.
• If any overages exist under the old plan/addon's entitlements, they are invoiced at the end of the term.
• The new plan/addon becomes active immediately after the change.
• Charges for the new plan/addon are prorated based on the remaining time in the billing period.
• The entitlement grant for the new item is given in full for the billing period of that item and entitlements are not prorated by time. Usages are attributed to the entitlement grant based on the usage timestamp. This means that usages sent with backdated timestamps will get attributed to the previous plan/ addon's entitlement grant.

Example 1: Upgrade with no overages at time of change

Change date: Jun 15

Upgrade: Professional Monthly ($50/mo, 100K tasks included) → Team Monthly ($100/mo, 500K tasks included)

Resulting behavior:

Example 2: Upgrade with overages at time of change

Change date: Jun 15

Upgrade: Professional Monthly → Team Monthly

Usage consumed by Jun 15: 120,000 tasks

Resulting behavior:

Note: If you want to offset usage that already occurred earlier in the billing period, you must backdate the subscription change to an earlier date. Backdating can only go as far back as the most recent billing date.

Scenario 3: Changing the quantity of a plan/addon mid-term

Scenario

You increase the quantity of a prepaid (non-metered) item during an active billing period.

Behavior

When a plan's quantity changes mid-term:

• The plan price scales linearly with quantity (e.g., quantity 2 → 2× price).
• Entitlements scale linearly with the updated quantity and apply from the start of the current billing period, and not just from the change date. This means the new total entitlement quota is retroactively valid for the full term.
• Until the change, the old quantity and price remain effective for billing.
• After the change, the new quantity and price take effect immediately for billing purposes.
• A prorated adjustment credit note is created for the unused portion of the old price.
• A prorated charge is invoiced for the remaining billing period based on the new quantity.
• Usage overages are:
  • Not invoiced immediately.
  • Billed at the end of the billing term.
  • Calculated only for usage exceeding the updated entitlement for the full term (since the new entitlement quota applies from term start).

Important: Because entitlements apply retroactively to the start of the term, usage that appeared to be overage under the old quantity may no longer be overage after the quantity increase. Overages are always settled against the entitlement that is active at the end of term.

Example: Quantity upgrade for a plan

Change date: Jun 15

Price: $50/unit/mo, 100K tasks included per unit

Change: Professional Monthly quantity 1 → 2

Resulting behavior:

Entitlement impact:

• Before the change: entitlement quota = 100,000 tasks (Jun 1 – Jun 30).
• After the change: entitlement quota = 200,000 tasks, valid from Jun 1 – Jun 30.
• If 120,000 tasks were used before Jun 15, no overage is due at end of term (120K < 200K).
• Overages at end of term are calculated against the 200,000-task entitlement for the full billing period.

Scenario 4: Overriding entitlements only on an active subscription mid-term

Scenario

You want to increase (or decrease) a customer's included usage quota for the current term without changing their plan, price, quantity, or addon configuration. This is a direct entitlement override at the subscription level — no item swap, no billing change.

This is distinct from a top-up addon (Scenario 6): rather than attaching a new item, you are modifying the entitlement value of an existing item already on the subscription.

How to apply

Use item price level entitlement overrides to modify default entitlements granted.

Behavior

• The updated entitlement quota takes effect immediately.
• The new entitlement is valid from the start of the current billing term — not from the override date. This means usage already consumed in the term is measured against the new quota.
• No invoice or credit note is generated. Entitlement overrides are a UBB-level change and do not trigger proration or billing.
• The billing period and subscription term are not affected.
• Only the overridden feature is changed. All other features and addons on the subscription remain unaffected.
• Because entitlements apply retroactively to the start of the term, usage that appeared to be overage may no longer be overage after the entitlements increase. Overages at end of term are calculated against the new (overridden) entitlement quota for the full billing period.

Example: Increase included tasks mid-term

Change date: Jun 15

Change: Professional Monthly included tasks overridden from 100,000 → 150,000

Usage consumed before override: 60,000 tasks

Resulting behavior:

Overage impact:

• Before the override, a customer consuming 110,000 tasks by Jun 30 would incur 10,000 tasks of overage.
• After the override (150,000 tasks from Jun 1), those same 110,000 tasks fall entirely within the included quota, no overage at end of term.
• Overages are always settled at the end of term against the entitlement that is active at that point.

Scenario 5: Invoicing usage overages at the time of subscription change

Scenario

You want usage overages to be invoiced immediately when a subscription change occurs, instead of waiting until end of term.

Solution

Use the invoice_usages parameter during the subscription change API call.

Required conditions

All of the following must be true:

• Contact Chargebee Support to enable a backend site setting: Invoice_overages
• Enable the following site setting in your Chargebee Billing site:
  • Navigate to Configure Chargebee > Billing LogIQ > Metered Billing.
  • Enable Invoice and charge for usage-based items when a subscription is changing
• This behavior is API-only:
  • Cannot be triggered via UI.
  • Must be done using the Subscriptions change API.
• invoice_usages can be used only with force_term_reset=true:
  • This resets the billing term and starts a new term.

Example: Invoice overages immediately on change

Change date: Jun 15

Usage so far: 120,000 tasks

Included usage: 100,000 tasks

Overages so far: 20,000 tasks

Overage rate: $0.10 per task (current plan)

API parameters:

{
  "invoice_usages": true,
  "force_term_reset": true
}

Scenario 6: Top-up of entitlements mid-term

Scenario

You want to grant a customer additional included usage mid-term without changing their plan, pricing, or entitlement configuration.

Recommended approach

Create and attach a non-metered addon that grants additional included usage by following these steps:

1. Create a non-metered addon with the following specifications:
   • Price: $100
   • Included usage: the number of units to top up
2. Attach the addon to the subscription when needed.
3. If it should apply only once, set the addon billing cycle to 1 during the subscription update so it:
   • Applies immediately
   • Applies for only one billing cycle
   • Does not recur at renewal
4. If this top up will be used to grant additional entitlements in every billing cycle, then choose the Billing Cycles as 'Forever'.
   • Applies immediately
   • Applies for all future billing cycles and is billed again at renewal.

Entitlement grant period for top-up addons

The billing period of the top-up addon becomes its entitlement grant period. This means:

• If the addon is attached on Jun 16, its billing period is Jun 16 – Jun 30, and the entitlement is only valid for usage with a timestamp of Jun 16 or later.
• Usage that occurred before Jun 16 (and is still unbilled/on-demand) will not be offset by the new top-up entitlement.
• If you want the top-up to offset usage that already occurred earlier in the billing period, you must backdate the addon to an earlier date. Backdating can only go as far back as the most recent billing date for the relevant addon.

Subscription context:

• Annual plan starting Jun 1. Enterprise Plan: $990/year, 100,000 tasks included.
• On-demand overage addon: $0.01/task, billed monthly (renews 1st of each month).
• Usage Jun 1 – Aug 15: 100,000 tasks (quota exhausted).
• Usage Aug 16 – Aug 31: 10,000 tasks (all overage).
• Sep 1: Overage invoice generated → 10,000 × $0.01 = $100.
• Usage Sep 1 – Sep 15: 15,000 tasks.
• Sep 16: Recurring Top-Up addon is attached (50,000 tasks).
• Usage Sep 16 – Sep 30: 10,000 tasks.

Addon definition:

Case 1: Top-up attached on Sep 16 (no backdating)

Case 2: Top-up backdated to Sep 1