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: January 1
• Billing period: Monthly (Jan 1 – Jan 30)
• Usage at time of change: 60,000 tasks already consumed when change is initiated on Jan 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.
• 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.

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 are billed at the updated rate at the end of the term.

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

Change date: Jan 15
Change: Professional Monthly price changes from $50 → $60

Expected outcome:

• A prorated charge is invoiced on change for the remaining period (Jan 16 – Jan 30): $30
• A prorated adjustment credit note is created for the unused portion at the old price (Jan 16 – Jan 30): $25
• Starting next cycle, recurring price becomes $60/month

Example 2: Metered(postpaid) addon price change

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

Expected outcome:

• All overages for the current term are billed at $0.20 per task at the end of the term.

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.
• Entitlements for the new plan/addon are granted in full for the remainder of the term, and apply to usage timestamps after the change.

Example 1: Upgrade with no overages at time of change

Change date: Jan 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: Jan 15
Upgrade: Professional Monthly → Team Monthly
Usage consumed by Jan 15: 120,000 tasks

Resulting behavior:

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 (for example, quantity 2 → 2× price).
• Entitlements scale linearly with the updated quantity for the entire billing period.
• Until the change, the old quantity and price remain effective.
• After the change, the new quantity and price take effect immediately.
• 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.

Example: Quantity upgrade for a plan

Change date: Jan 15
Change: Professional Monthly quantity 1 → 2

Resulting behavior:

Scenario 4: 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: Jan 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
}

Resulting behavior:

• Usage up to Jan 15 is finalized.
• Overage charges are calculated immediately:
  • 20,000 × $0.10 = $2,000
• An invoice is generated immediately.
• A new billing term starts on Jan 15.
• Usage tracking restarts from zero for the new term.

Scenario 5: One-time top-up of entitlements mid-term

Scenario

You want to grant a customer additional included usage mid-term without changing their plan, pricing, or usage configuration. This is typically used for one-off needs or temporary spikes.

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: $0
   • 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

Example: One-time tasks top-up

Create an addon:

Change date: Jan 15

Action: Attach the addon to the subscription

Resulting behavior:

• Customer immediately receives 50,000 additional tasks.
• Total usable entitlements for the remainder of the billing period become 150,000 tasks.
• No charges are applied (addon priced at $0).
• Addon expires automatically at the end of the current billing cycle.
• Top-up does not recur in the next billing period.