Billing Mode & Proration
Introduction
Billing Mode
Chargebee allows you to choose the billing mode for your site. This is the granularity of time to which your services are billed. You can account for services either to the day or to the millisecond. In other words, when you bill your customers, the minimum accountable duration can be either a day or a millisecond.
There are two billing modes: day-based and millisecond-based.
- Day-based billing: Subscription renewals align with the exact start timestamp of the original subscription, and prorated charges and credits are calculated based on the number of days, regardless of the subscription's start or change timestamp.
- Millisecond-based billing: Subscriptions renew at the exact original start timestamp, and prorated charges and credits are calculated using the time difference between creation and modification, to millisecond precision. This is the default setting.
If you signed up for Chargebee Billing before May 19, 2026, your site uses the earlier definition of day-based billing. In that definition, when a subscription starts, regardless of the actual start time, its start timestamp is set to the beginning of the day (00:00:00.000) and its end timestamp is set to the end of the last day of the billing period (23:59:59.999), and renewals run at 00:00:00 of the day. The new day-based definition described on this page applies to sites created on or after that date.
Proration
Changes can be made to subscriptions in the middle of their terms. For example, a subscription may be upgraded or downgraded to a different plan, or quantities may be added or removed. Since this introduces a change in the price of the subscription, prorated credits and charges can be raised to ensure proper billing.
Since billing mode can be either day-based or millisecond-based, proration follows suit. When proration happens, the minimum accountable duration for the charges or credits is either a day or a millisecond, as set by the billing mode.
For per-unit add-ons, you can configure proration separately for each subscription line item when editing a subscription. See Item Level Proration.
Prorate fixed amount coupons
Fixed amount coupons can be prorated when they are applied in the middle of a subscription term. When proration is enabled in the proration settings, any fixed amount coupon added during a subscription change or mid-term update is automatically prorated for the remaining portion of the billing period.
Proration of fixed amount coupons follows the same rules as subscription proration. When proration applies, the coupon discount is calculated based on the remaining duration of the term, using the same day-based or millisecond-based logic as other prorated charges or credits, as set by the billing mode.
Configuration
Configuring billing mode
To configure your preferred billing mode in your Chargebee Billing site, follow these steps:
- Go to Settings > Configure Chargebee > Billing LogIQ > Billing & Invoices > Billing Mode.
- On the Billing mode pop-up, the Millisecond-based setting is selected by default. You can choose from the following options:
- Day-based: Billing and proration are accounted for in whole days. The subscription starts at the exact timestamp, and the renewal aligns to this timestamp. However, prorated charges and credits are calculated based on the number of days in the term, regardless of the time of day the subscription started or was changed. See Understanding billing mode and proration.
- Millisecond-based: This is the default setting, where billing is done to the millisecond. The subscription starts at the exact timestamp, and the renewal aligns to this timestamp. However, prorated charges and credits are calculated using the time difference between creation and modification, to millisecond precision. The end-of-term timestamp is one billing period after the subscription start timestamp. See Understanding billing mode and proration.
Note
For sites created before May 19, 2026, day-based billing behaves differently: start timestamps are set to the begin ÿÿ ning of the day (00:00:00.000), term-end timestamps to the end of the last day (23:59:59.999), and renewals run at 00:00:00. With this earlier definition, when day-based billing is enabled you must also set whether the date of cancellation is billed (see subscription cancellation settings).
- Click Apply to save your changes.
Configuring proration for subscription change
To enable the default behavior for proration when changing any subscription, follow these steps:
- Go to Settings > Configure Chargebee > Billing LogIQ > Billing & Invoices > Prorate credits/charges.
- Enable the toggle to enable proration during subscription change by default.
- Click Apply to save your changes.
While actually changing the subscription, you can override the default setting by using the Apply prorated credits and charges checkbox on the change subscription page.
The following table outlines the proration behavior for subscription changes when the site-level setting is enabled, and the subscription-level setting is either enabled or disabled.
| IF the... | Subscription Change 1 | AND | Behavior | Subscription Change 2 | Behaviour |
|---|---|---|---|---|---|
| apply prorated credits and charges checkbox is | enabled | Prorated credits or charges are created as applicable for this change | enabled | Prorated credits or charges are created as applicable for this change. | |
| disabled | Prorated credits or charges are not created. | ||||
| disabled | * No changes were made to the subscription's billing term A change was made to either the subscription's items or their prices. | Prorated credits or charges are not created. | enabled | A prorated invoice is generated for the updated subscription. Also, prorated credits will not be issued/generated. | |
| disabled | Prorated credits or charges are not created. |
Example Let's review an example of when the apply prorated credits and charges checkbox is disabled.
A customer's original subscription plan is as follows:
Plan Term: July 1 - July 31 Plan Price: $100
Change 1: When the checkbox is disabled and the changes are applied immediately. The customer decides to update their plan on July 15. Plan Term: July 15-July 31 Plan Price: $50
Outcome: No credits are issued to the customer.
Change 2: When the checkbox is enabled and the changes are applied immediately. The customer decides to update their plan again on July 20. Plan Term: July 20- July 31 Plan Price: $150
Outcome: In this example, the customer will receive a prorated invoice for the period(July 20 - July 31) based on the new plan. However, the customer will not be issued prorated credits for the unused period.
- Proration for subscription cancellation must be configured under subscription cancellation settings.
- Another occasion when proration can be done is when you change the next billing date or — in case of a non-renewing subscription — change the cancellation date of a subscription.
- Proration via API: If you are an API user, then it may be helpful to know which API calls have the proration feature in them. We list them below:
Note
Chargebee provides only time-based billing, which suits services billed based on time of use, such as SaaS. If you sell subscriptions for physical goods billed based on deliveries, disable proration.
Configuring proration for fixed amount coupons
To enable proration for fixed amount coupons, follow these steps:
- Go to Settings > Configure Chargebee > Billing LogIQ > Billing & Invoices > Prorate fixed amount coupons.
- Enable the toggle to prorate fixed amount coupons applied mid-term during subscription changes by default.
- Click Apply to save your changes.
Understanding day-based billing mode and proration
Subscription update: Plan change
When a subscription is updated mid-term and day-based billing mode is selected, prorated charges and credits are calculated based on the number of days.
The day-based formula is:
- Credits for the unused period from the old plan = (Old plan amount / Regular term in days) × Remaining term in days
- Charges for the new plan = (New plan amount / Regular term in days) × Remaining term in days
- Net charge for the subscription change = Charges for the new plan − Credits for the unused period of the old plan
Example
A customer, Acme Inc., subscribes to a monthly plan of $300 on July 23, 2025, at 12:30 PM and upgrades to a monthly plan of $600 on August 1, 2025, at 10:00 AM.
| Detail | Value |
|---|---|
| Subscription term start timestamp | Jul 23, 2025, 12:30:33.756 |
| Subscription term end timestamp | Aug 23, 2025, 12:30:33.755 |
| Subscription change timestamp | Aug 1, 2025, 10:00:00.000 |
| Regular term | 31 days |
| Remaining term | 22 days |
Applying the day-based formula:
- Credits for the unused period from the old plan = ($300 / 31) × 22 = $212.90
- Charges for the new plan = ($600 / 31) × 22 = $425.81
- Net charge for the subscription change = $425.81 − $212.90 = $212.91
Subscription cancellation
When a subscription is canceled, prorated credits are calculated based on the remaining number of days in the term. The remaining number of days for the credit calculation depends on the timestamp of the subscription cancellation. Whether the cancellation date itself is billed depends on your subscription cancellation settings.
Assuming the cancellation date is considered for billing:
- If a subscription is canceled at a timestamp less than or equal to the creation timestamp, the system treats it as a same-day cancellation, and the remaining days are counted from the day of cancellation to the term end.
- If a subscription is canceled at a timestamp greater than the creation timestamp, the system treats it as a next-day cancellation, and the remaining days are counted from the next day of cancellation to the term end.
Example
Acme Inc. subscribes to a monthly plan of $300 with a term that starts on September 1, 2025, at 10:00 AM and renews on October 1, 2025 — a 30-day term, so $10 per day. The $300 invoice is paid, and the cancellation date is set to be billed in the subscription cancellation settings.
| Detail | Value |
|---|---|
| Plan amount (monthly) | $300 |
| Term | Sep 1 – Oct 1, 2025 (30 days) |
| Subscription creation timestamp | Sep 1, 2025, 10:00:00 AM |
| Per-day rate | $300 / 30 = $10 per day |
The number of remaining days credited depends on how the cancellation time of day compares with the subscription's creation time of day (10:00 AM):
- Same-day cancellation: The customer cancels on September 21, 2025, at 09:00 AM. Because 09:00 AM is before the 10:00 AM creation time, it falls within the September 20, 10:00 AM – September 21, 10:00 AM billing day, so the cancellation is treated as occurring on September 20 and that day counts as remaining. Remaining days = September 20–30 = 11 days, so the prorated credit = $10 × 11 = $110.
- Next-day cancellation: The customer cancels on September 21, 2025, at 02:00 PM. Because 02:00 PM is after the 10:00 AM creation time, the cancellation day is billed and the remaining days start the next day. Remaining days = September 22–30 = 9 days, so the prorated credit = $10 × 9 = $90.
Because the original invoice is paid, the credit is issued as a refundable credit note.
Understanding millisecond-based billing mode and proration
Subscription update: Plan change
When a subscription is updated mid-term and millisecond-based billing mode is selected, prorated charges and credits are calculated using the exact time difference between the subscription's creation and the change, to millisecond precision.
The millisecond-based formula is:
- Credits for the unused period from the old plan = (Old plan amount / Regular term in milliseconds) × Remaining term in milliseconds
- Charges for the new plan = (New plan amount / Regular term in milliseconds) × Remaining term in milliseconds
- Net charge for the subscription change = Charges for the new plan − Credits for the unused period of the old plan
Example
A customer, Acme Inc., subscribes to a monthly plan of $1,000 on January 10, 2019, at 16:02:35.480 and upgrades to a monthly plan of $2,700 on February 1, 2019, at 10:03:43.223.
| Detail | Value |
|---|---|
| Subscription term start timestamp | Jan 10, 2019, 16:02:35.480 |
| Subscription term end timestamp | Feb 10, 2019, 16:02:35.479 |
| Subscription change timestamp | Feb 1, 2019, 10:03:43.223 |
| Regular term (31 days) | 2,678,400,000 milliseconds |
| Remaining term (9 days, 5 hrs, 58 min, 52 s, 257 ms) | 799,132,257 milliseconds |
Applying the millisecond-based formula:
- Credits for the unused period from the old plan = (1,000 / 2,678,400,000) × 799,132,257 = $298.36
- Charges for the new plan = (2,700 / 2,678,400,000) × 799,132,257 = $805.58
- Net charge for the subscription change = $805.58 − $298.36 = $507.22
Subscription cancellation
When a subscription is canceled, prorated credits are calculated using the exact remaining time in the term, to millisecond precision, rather than rounded to whole days. Whether the cancellation date itself is billed depends on your subscription cancellation settings.
The prorated credit is calculated as:
- Prorated credit for the unused period = (Plan amount / Regular term in milliseconds) × Remaining term in milliseconds
Example
Acme Inc. subscribes to a monthly plan of $1,000 with a term of January 10, 2019, 16:02:35.480 to February 10, 2019, 16:02:35.479 (regular term = 2,678,400,000 ms), and the $1,000 invoice is paid. The customer cancels the subscription on February 1, 2019, 10:03:43.223, leaving 799,132,257 ms in the term.
| Detail | Value |
|---|---|
| Plan amount (monthly) | $1,000 |
| Regular term | 2,678,400,000 ms (Jan 10 – Feb 10, 2019) |
| Cancellation timestamp | Feb 1, 2019, 10:03:43.223 |
| Remaining term | 799,132,257 ms |
- Prorated credit for the unused period = ($1,000 / 2,678,400,000) × 799,132,257 = $298.36
Because the original invoice is paid, the $298.36 credit is issued as a refundable credit note.
Billing mode change
Information
- You can change the billing mode only on your Chargebee TEST site.
- On your LIVE site, you can change only from millisecond-based to day-based billing mode. Once changed, you can't switch back to millisecond-based mode.
Here's how changing the billing mode affects subscriptions.
Millisecond-based to day-based
Under the current day-based definition, switching from millisecond-based to day-based billing preserves your subscription timestamps. Start, activation, renewal, and trial timestamps remain at their exact values, and renewals continue to align with the subscription's original start timestamp. Only proration changes: from this point, prorated charges and credits are calculated based on the number of days.
Warning
For sites created before May 19, 2026, switching from millisecond-based to day-based billing results in the loss of timestamp information. Under the earlier definition, all start timestamps (subscription start, activation, renewal, and trial start) are set to the beginning of the day (00:00:00.000), and all term-end timestamps are set to the end of the previous day (23:59:59.999). Any start and end timestamp data more granular than a day is lost and cannot be recovered, so switching back to millisecond-based billing is not possible.
Example
Earlier definition — Billing mode: millisecond-based; Plan period: 1 month; Trial period: 10 days.
- Trial start: Apr 25, 2019, 16:28:09.034 → Apr 25, 2019, 00:00:00.000
- Subscription start: May 5, 2019, 16:28:09.034 → May 5, 2019, 00:00:00.000
- Term end: Jun 5, 2019, 16:28:09.033 → Jun 4, 2019, 23:59:59.999
- Next renewal: Jun 5, 2019, 16:28:09.034 → Jun 5, 2019, 00:00:00.000
Although renewal times are aligned with the start of the day under this definition, the renewal can take 2–3 hours to complete due to the volume of operations.
Day-based to millisecond-based
When switching from day-based to millisecond-based billing, the subscription data is unchanged. Billing and proration for the site then happen to the millisecond. This switch is allowed only on the test site.
Note
When prorated credits are raised against invoices, the amounts are always calculated according to the billing mode in which the invoice was generated. For example, if an invoice was generated in millisecond-based billing, then even after switching the site to day-based billing, any prorated credits against that invoice are still calculated to the millisecond.
Proration mechanism
Proration for plans and add-ons is accomplished in two parts:
- The calculation of credits for items (plan-specific or add-on-specific) unsubscribed from, for the unused time period of the current billing term.
- The calculation of charges for the newly subscribed items for the remaining portion of the current billing period.
During a subscription change, prorated credits or charges are issued based on the type of change (upgrade, downgrade, or quantity change) and the status of the current term's invoice. For example:
- When the current term's invoice is in a Payment Due or Not Paid state, the credits generated during a subscription change are of the type Adjustment. These credits are automatically applied to the invoice, reducing the invoice's due amount.
- If the current term's invoice is in a Paid state, the credits generated are of the type Refundable and are automatically applied to future invoices.
Examples of day-based billing proration
The following examples demonstrate proration in Chargebee for day-based billing.
Plan quantity downgrade (paid invoice)
Subscription created with plan quantity 2 on September 1; plan amount $10; invoice generated $10 × 2 = $20; invoice is Paid. Subscription changed on September 16 to quantity 1. No invoice is generated, and prorated refundable credits of $5 × 1 = $5 are issued. Credits for the quantity of 1 for the unused period of 15 days are generated. Since the current term's invoice is Paid, the credit note is of the type Refundable.
Plan quantity downgrade (payment due invoice)
Subscription created with plan quantity 3 on September 1; plan amount $20; invoice generated $20 × 3 = $60; invoice is unpaid. Subscription changed on September 1 to quantity 2. No new invoice is generated; adjustment credits $10 × 1 = $10 are created and adjusted against the Payment Due invoice, reducing the final invoice amount to $50. Since the current term's invoice is unpaid, a credit note of the type Adjustment is created for the price of 1 quantity.
Plan quantity downgrade (partially paid invoice)
A subscription is created for a monthly plan priced at $30 per unit: start date September 1, quantity 3 units, invoice generated $30 × 3 = $90, payment received $80, payment due $10. The quantity is reduced to 2 on September 15:
- Prorated amount for the unused service = plan price × unused quantity × fraction of time unused = $30 × 1 × 0.5 = $15.
- Total amount for the term = $90 − $15 = $75.
- Since $80 has already been paid, a refundable credit note for $80 − $75 = $5 is generated.
- An adjustment credit note for the original unpaid amount of $10 is also generated.
Plan quantity upgrade (paid invoice)
Subscription created with plan quantity 1 on October 1; plan amount $10; invoice generated $10; invoice is paid. Subscription changed on October 16 to quantity 3. No credit note is created, and a new invoice is generated for the 2 additional quantities: $5 × 2 = $10. Proration in the case of a plan quantity upgrade is calculated and applied the same way regardless of the invoice status (Paid, Payment Due, Not Paid, or Partially Paid).
Plan change downgrade (paid invoice)
Subscription created with Plan A ($60) on March 1; invoice is paid. Plan downgraded to Plan B ($30) on March 11. An invoice of $20 is generated for Plan B's amount for the period of 20 days, and prorated Refundable Credits of $40 are created for Plan A's unused period; $20 is applied against the invoice and the remaining $20 is available for future use. If the previous invoice was unpaid, Adjustment Credits are created and applied instead.
Mid-term change of quantity for quantity-based pricing models
The following examples show how proration happens when changing the quantity mid-term for plans with tiered, volume, or stairstep pricing.
The volume and tiered examples below both use the following per-unit tier structure. In volume pricing, every unit is billed at the single per-unit price of the tier into which the total quantity falls. In tiered pricing, units are filled from the lowest tier upward, and each unit is billed at the price of the tier it falls in.
| Tier | 1 | 2 | 3 |
|---|---|---|---|
| Units | 1–100 | 101–200 | 201 or more |
| Price | $5 | $4 | $3 |
Volume pricing
- New subscription sign-up: September 1, 90 units. Since 90 units falls under tier 1, the billing price is 90 × $5 = $450.
- On subscription change: September 16, increased to 110 units. Since 110 units now falls under tier 2, the new billing price is 110 × $4 = $440.
- Prorated billing price for the new subscription period (September 16 – September 30): $440 × 15/30 = $220
- Credits on the original subscription for that period: $225.
- For the subscription change, refundable credits of $225 − $220 = $5 are raised.
Tiered pricing
- New subscription sign-up: September 1, 90 units. Since 90 units falls under tier 1, the billing price is 90 × $5 = $450.
- On subscription change: September 16, increased to 110 units. Since 110 units now falls under tier 1 and tier 2, the new billing price is 100 × $5 (tier 1) + 10 × $4 (tier 2) = $500 + $40 = $540.
- Prorated billing price for the new subscription period (September 16 – September 30): $540 × 15/30 = $270
- Credits on the original subscription for that period: $225
- For the subscription change, a charge of $270 − $225 = $45 is created.
Stairstep pricing
Consider the following stairstep pricing for a monthly plan:
| Step | Units in step | Price |
|---|---|---|
| 1 | 1–100 | $300 |
| 2 | 101–200 | $550 |
| 3 | 201 or more | $700 |
In stairstep pricing, the whole subscription is billed at the single flat price of the step into which the quantity falls; it is not multiplied by the number of units.
- New subscription sign-up: September 1, 90 units. Since 90 units falls in step 1 (1–100), the billing price is the flat $300.
- On subscription change: September 16, increased to 110 units. Since 110 units now falls in step 2 (101–200), the new billing price is the flat $550.
- Prorated billing price for the new subscription period (September 16 – September 30, 15 days): $550 × 15/30 = $275
- Credits on the original subscription for that period: $300 × 15/30 = $150
- For the subscription change, a charge of $275 − $150 = $125 is created.
Examples of millisecond-based billing proration
The following examples demonstrate proration in Chargebee for millisecond-based billing.
Example 1 — Subscription upgrade scenario.
Plan A: monthly, $1,000. Plan B: monthly, $2,700. The customer subscribes to Plan A starting January 10, 2019, 16:02:35.480.
| Detail | Value |
|---|---|
| Subscription start timestamp | Jan 10, 2019, 16:02:35.480 |
| Subscription end timestamp | Feb 10, 2019, 16:02:35.479 |
| Subscription change timestamp | Feb 1, 2019, 10:03:43.223 |
| Regular term (31 days) | 2,678,400,000 milliseconds |
| Remaining term (9 days, 5 hrs, 58 min, 52 s, 257 ms) | 799,132,257 milliseconds |
- Credits for the unused period from the old plan = (1,000 / 2,678,400,000) × 799,132,257 = $298.36
- Charges for the new plan = (2,700 / 2,678,400,000) × 799,132,257 = $805.58
- Net charge for the subscription change = $805.58 − $298.36 = $507.22
Example 2 — Subscription downgrade scenario.
Plan A: monthly, $2,000. Plan B: monthly, $1,700. The customer subscribes to Plan A starting January 10, 2019, 16:02:35.480.
| Detail | Value |
|---|---|
| Subscription start timestamp | Jan 10, 2019, 16:02:35.480 |
| Subscription end timestamp | Feb 10, 2019, 16:02:35.479 |
| Subscription change timestamp | Feb 1, 2019, 10:03:43.223 |
| Regular term (31 days) | 2,678,400,000 milliseconds |
| Remaining term (9 days, 5 hrs, 58 min, 52 s, 257 ms) | 799,132,257 milliseconds |
- Credits for the unused period from the old plan = (2,000 / 2,678,400,000) × 799,132,257 = $596.72
- Charges for the new plan = (1,700 / 2,678,400,000) × 799,132,257 = $507.21
- Net charge for the subscription change = $507.21 − $596.72 = ($89.51)
A credit note for $89.51 is generated.
Note
For a subscription with multiple changes in a single billing period, if you set the prorate setting for a subscription change to False, Chargebee will not prorate subsequent changes within the same billing period, even if you later set the same prorate setting to True.
FAQ
Can I have products with different billing modes in Chargebee?
No. Billing mode is a site-wide setting and cannot be changed for specific plans or add-ons in Chargebee.
Was this article helpful?