Component Allocations

In order for Advanced Billing to add charges for a subscriber’s components, you must report to Advanced Billing the component’s status/amount. When we refer to the status we mean one of the following for each subscription.

Quantity used for quantity-based components
Amount allocated or recorded for metered-based and prepaid components
Or whether the feature was enabled or not - on/off components.

In the application, you can perform each of the following actions for a component:

View History: View the amount and dates when a component has been used.
Update Price Point: Update the price point being used for the component.
Change Global Component Pricing/Details: Change the name, description, unit price, etc. of a component.

The following options are unique to specific component types:

Update Quantity: Change the quantity allocated to a component. This option only appears on quantity-based components, recurring or one-time.
Toggle On/Off: Set a component to “on” or “off”. This option only appears in on/off components.
Purchase Prepaid Units: Purchase an allocation of a set number of units, with a proration strategy of your choosing. This option only appears on prepaid components.
Record Usage: Make note of recent usage for the billing period. This option only appears on metered and prepaid components and will not be immediately charged for once recorded.

Components are generally billed in advance, on the same billing cycle as the product they are associated with. The one exception is metered components, which are billed in arrears.

Component Billing Examples

The following examples illustrate the usage of components and when they will be billed to the subscriber.

Quantity-based Example

Quantity-based components renew and apply charges at the beginning of each recurring period. Also, you may elect to apply charges/proration when allocating a quantity-based component during the middle of a billing cycle, (aka: mid-recurring-period).

For example:

A subscriber has purchased a product on the 23rd of the month, and they’ll be billed for any quantity-based components on the 23rd of each month
This assumes the product is on a monthly billing cycle.
Advanced Billing looks at the quantity of components allocated on the renewal billing date and then bills accordingly for the allocated components.
The amount recorded will not reset to zero at the end of the billing period.

Metered-based Example

Metered-based components are recorded against a subscription throughout the recurring billing period. We refer to this as recording usage. Advanced Billing calculates the total usage at the end of the recurring period and applies the appropriate charges. At the beginning of the next billing period, the metered-based usage resets to zero.

For example:

Let’s say your subscriber signs up on the 1st of January
On January 10th, you record 10 metered components worth of usage
On January 20th, you record another 10 metered components worth of usage
When the monthly product renews on February 1st, the subscriber will be charged for the product renewal plus 20 metered components.
The recorded metered components will also reset to zero at this time.

Prepaid Examples

Prepaid components involve two steps. First, a variable number of units are purchased through an allocation. Then, usage is recorded on the subscription as those units are depleted. Overage pricing comes into effect if the usage recorded exceeds the units allocated.

To understand how units are marked as overage, it’s helpful to think of a subscriber as having an allocation balance and an overage balance at any given time. For example, if a prepaid component is configured with recurring allocations:

A new subscriber joins on March 15th on a monthly product.
On March 16th, they purchase 100 allocations. Then they use 101 units. At this point, they have 0 allocations remaining, and 1 unit in overage.
A week later, they purchase 200 allocations. At this point, they have 200 allocations and 1 unit still in overage.
Soon after, they record 199 usages. Now, there is 1 allocation remaining, with 1 still in overage.
Finally, the day before renewal, they record 50 usages. The result is 0 left in the allocation block, and 49 added to overage, for a total of 50.
On April 15th, the subscription renews. Their renewal charges consist of:
- The product charge for the following billing period, April 15th - May 15th
- 50 units in overage
- 300 allocations that are purchased again due to the recurring setting on the component

For another prepaid example, let’s assume the component has an expiration interval of 10 days and is configured to roll over leftover units:

On November 8th, a new subscription is created with an allocation of 500 units.
On November 11th, usage is reported for 200 units. 300 allocations remain, with none in overage.
On November 18th, the allocation officially expires.
On December 1st, another 200 units are reported in usage. Because the original allocation has expired, these 200 units are considered overage.
On the renewal date, December 8th, the following charges will be included on the invoice:
- The product charge for the following period, December 8th - January 8th
- 200 units as overage
- The original allocation of 500 units will not be applied again, since the component is not recurring
- While only 400/500 units of usage had been recorded, the remaining 100 will not roll over to the next period because the original allocation has expired.

Reporting Metered Component Usage

As depicted in the metered example above, you record the amount your subscriber consumes as units. At the end of the billing period, Advanced Billing will bill your customer for the total number of units reported. We will reset the component count to zero and the whole process starts over for the new billing period. The first time you record usage on a subscription the price point will get locked in, ensuring the usage is billed at that same price point in the future (unless you manually change the price point).

This differs from quantity-based components, which DO NOT reset to zero at the start of every billing period.

You can report metered usage in the application by navigating to a subscription and selecting the “Components (Line-Items)” tab. This will display a list of all the available components.

Click "actions" to reveal the context navigation and select the "Record Usage" link

Enter a quantity and (optionally) a memo, and press Record.
The quantity must be an integer (whole number).
If you enter a decimal amount for the quantity, it will be silently truncated (not rounded). For example, if you enter 5.5, it becomes 5.
All recorded usage for a billing period will be tallied and charged at the end of the period.

Reporting Quantity-based Allocations

For quantity-based components, you can record when your customer changes the quantity of units purchased. The assumption is that those units purchased stay in use by your customer forever, until a future change. The exception is for one-time quantity-based components, which will reset to 0 after being allocated.

A common use-case for recurring quantity-based components is software license fees, where you want to collect $100/month for each employee of your customer who accesses your service. So you might set the quantity to 3 and Advanced Billing will bill your customer $300 every billing period until you change the quantity.

By comparison, a one-time quantity-based component is useful for one-time charges, such as a professional service completed.

Quantity component allocations can be updated using the application by selecting the component from the “Components (Line-Items)” tab when viewing a subscription.

Reporting On/off Component Status

On/off components can be toggled using the application by selecting the component from the “Components (Line-Items)” tab when viewing a subscription.

Reporting Prepaid Component Status

Prepaid components will have two primary screens used to report usage: “Record Usage” and “Purchase Prepaid Units”.

Prepaid components involve purchasing units and recording usage for those units.

First, the subscriber will want to purchase prepaid units, also referred to as creating a prepaid allocation. This screen looks much like the “Update Quantity” page for quantity-based components. However, the proration settings are not included, due to the nature of prepaid components.

Second, once units have been purchased, a subscriber may begin using them. As they do so, the usage can be tracked in Advanced Billing with the “Record Usage” page shown below.

If units are recorded accidentally or otherwise need to be reversed, it’s possible to pass a negative amount to detract from the current usage reported.

Record prepaid usage for a subscription.

Current Prepaid Usage

Within the components table for the subscription, the current usage column breaks down total units recorded compared to total allocations purchased. If any usage is recorded as overage, a small yellow box is shown to denote this.

To the right, the cost column contains two numbers. On the top is the total cost of that component. On the bottom in parentheses is the amount that overages contributed to.

Below, the subscription has purchased 10 allocations, and recorded usage for all 10 of them, for a total of $20. In addition, 1 more unit was recorded as overage at a cost of $3. In total, the component is valued at $23.

Prepaid usage is broken down by recorded usage compared to total allocations, and overages are noted accordingly.

Proration

Advanced Billing supports the application of prorated charges for quantity-based and on/off components. Depending on your proration scheme, changes to the allocated quantity during a period will result in either a charge or a credit to the subscription. Alternately, you can elect to not apply proration.

Proration Period

Proration is based on the length of the current billing period for the subscription, not the billing period configured for the product. By this we mean, proration will be calculated by using the amount of time that has passed between the current_period_started_at and the current_period_ends_at.

For example:

The current_period_started_at date is January 1, 2020
The current_period_ends_at date has been modified to be February 15, 2020
The length of the recurring period is 1 month
Let’s assume a component was allocated on the 15th of January, proration will be applied for the remaining 30 days of the billing period.
The proration period left is not 15 days.

If you modify the current_period_ends_at, you may need to calculate and apply any prorations manually for that billing period.

Similarly, if you have a trial period that is not the same length as the product’s billing period, then you may need to calculate and apply any prorations manually during the trial period.

Proration Upgrades vs. Downgrades

When changing the allocation of a quantity-based component, Advanced Billing considers the change an upgrade if the new computed cost is greater than the previous cost, and a downgrade if it is less.

Proration Schemes

The action that Advanced Billing takes when a prorated allocation occurs is called the proration scheme. The default scheme is defined under your site configuration, under Components.

The proration scheme can also be selected at the time that the allocation is created. Because it is often unclear at the time whether the change will be an upgrade or a downgrade, you will set both schemes when the allocation is created.

NOTE: This setting can be overridden by the Component Proration setting.

Select the appropriate global component setting

Proration Scheme Types

Upgrade Scheme:

“Charge the full amount of the difference in quantity.”: A charge is added for the full price of the component change.
“Charge the prorated amount of the difference in quantity.”: A charge is added for the prorated price of the component change.
“Do Not Charge.”: No charge is added.

Accrue Upgrade Scheme:

“Charge immediately.”: If an option above was selected to charge the customer it will be attempted right away. If it fails, the charge will be accrued until the next renewal.
“Accrue to the next billing period.”: If an option above was selected to charge the customer it will be attempted at next renewal.

Dunning Scheme:

“Leave the charges on the subscription to pay for at renewal.”: If this option is selected and the mid-period allocation charge fails the charges will be accrued.
“Initiate dunning for the subscription.”: This option allows for dunning to be initiated if a mid-period allocation charge fails.

Downgrade Scheme:

“Credit the full amount of the difference in quantity.”: A full credit is added for the amount owed.
“Credit the prorated amount of the difference in quantity.”: A prorated credit is added for the amount owed.
“Do Not Credit.”: No credit is added.

Proration Credit Calculation: Proration uses the current price of the component as well as the current tax rates and calculates the difference between the cost at the current quantity and the new quantity. If the price or taxes have changed, or if the previous allocation was not charged for, then you may want to calculate the amount and apply the proration manually by adding a charge or credit to the subscription.

NOTE: If component allocations are changed on a subscription in an end of life state such as Canceled, the quantity will be updated, but there will be no financial impact. No charge or credit will be added to the subscription.

Viewing Component Usage History

Under the component details for a subscription, click Actions > View History the history of that component. Note that the exact button text will vary based on the component. Below, a metered component’s usage history is shown.

View the past month's usage per component by selecting "View Usage History"

For prepaid components in particular, we will denote which quantities are new allocations (“prepaid”), and which are units being recorded (“used”).

Prepaid history is divided between used and prepaid quantities. This component has purchased 10 allocations and used 12 units in total.

Updating Component Quantities

Each Advanced Billing Site defaults the upgrade proration settings to prorate and accrue.

Update Quantity is significantly different than Record Usage in the application.

When you are updating a quantity, this is specifically for a quantity-based component.
This is often confused with Record Usage which is only for metered components.
The true difference is metered components reset to zero at the beginning of each billing period.

Example of updating a quantity-based component

Component Allocations for Invoice-Based Subscribers

In the event that you allocate any type of component for a subscriber that is active and on an invoice-based payment method, charges for the components will accrue till the next billing period.

Regarding proration, when you add a component under any proration scheme, charges will accrue until the next billing timestamp.

Component Allocations for Automatic-Based Subscribers without Payment Method

The same rules apply for automatic-based subscribers for component allocations, as mentioned in the above section.

It’s important to note that if you have a subscription that is currently active or past due and without a payment method on file, but is using the automatic payment-based method, you may still add components for this subscriber.

Once again, to ensure the clarity of this workflow, you may allocate any type of component for a subscriber that is on an invoice-based payment method, charges will accrue till the next billing period.

Regarding proration, when you add a component under any proration scheme, charges will accrue until the next billing timestamp.

Failed Component Allocations

In the event that you allocate a component against a subscription and the charge is not successful, please be aware of the following:

Failed Quantity-Based Components

If you selected “Charge immediately.” and one of the upgrade charge options (prorated or full), and the payment fails, you will receive the following warning:

WARNING: The payment for the upgrade charge was declined, but we still changed the component quantity. This subscriber now has an outstanding amount due. We'll attempt to capture this amount at the next normal renewal. Alternatively, you may want to revert the quantity change.

Another way of specifying this is, the charge will be accrued until the next renewal. Additionally, the balance due is increased by the amount of the failed component allocation.

Failed Metered Components

Metered components do not charge the card of file instantly when they are allocated. For clarity, we wanted to cover this use case in order to make the distinction clear.

When you allocate metered-based components against a subscription, they are always scheduled to be billed at the end of the payment period. There are no negative implications of recording usage against a subscription if the card on file is not valid.

Another way of saying this is if the current card on file does not support the charges, it is irrelevant since no attempt at charging the allocated amount is done at the time of recording. What is important to keep in mind, is that when the “next billing” timestamp arrives for the subscription, if the card on file cannot support the charges, the subscription will transition to past due.

Please note the additional attributes:

The current balance is not increased
The component is recorded against the subscription.
The allocation for the metered-quantity appears in the “Activity” tab
The “Next Billing” amount due increases by the cost of the allocated metered-based component

Failed On/Off Components

Since on/off components utilize proration, the scenarios for transaction failures will follow the examples provided in quantity-based component allocations. Please see the section above for examples of what occurs during failed quantity-based component allocations.

Failed Prepaid Allocations

Although prepaid components do not use proration, each allocation is charged for immediately. Consequently, if the payment fails, it will follow the same scenario as on/off and quantity-based components–namely, the allocation will still be saved, and the amount due will be accrued until renewal.

If the Cost Decreases

When you decrease the number of components allocated to a subscription, Advanced Billing gives you the option to choose the following:

Credit the prorated amount of the difference in quantity.
Do Not Credit.

These controls allow you to add a credit, or not, as you decrease the number of components attached to a subscription.

As an example, please match the outlined numbers to the image below for clarity:

On January 1, you have a subscription signup/payment for a $50.00/month product.
Also, on January 1, you allocate 100 $1 quantity-based components for a total of $100
She pays immediately for this component change
If you have elected to Credit the prorated amount of the difference in quantity., the subscriber will receive a transactional-based credit for the unused portion of the remaining billing period.
If you select Do Not Credit. No credit will be generated.