Setting Component Allocations

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

  • Quantity used for quantity-based components
  • Amount allocated or recorded for metered-based 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 Usage History: View the amount and dates when a component has been used.
  • Record Usage: Make note of recent usage for the billing period.
  • 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.

Components are billed in advance, on the same billing cycle as the product they are associated with.

Component Billing Examples

The following examples illustrate the usage of components and when they will be billed to the subscriber. Please keep in mind the following very important attributes of components:

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).
Metered-based components are recorded against a subscription throughout the recurring billing period. We refer to this as recording usage. Chargify 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.

Quantity-based 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 monthly billing cycle.
  • Chargify 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 components are billed in arrears according to the usage recorded during the billing period.

  • 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 monthy 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.

Reporting Metered Component Usage

As depicted in the example above, for metered components, you record the amount your subscriber consumes as units. At the end of the billing period, Chargify 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.

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.

Options for recording metered usage
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.

A common use-case 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 quanity to 3 and Chargify will bill your customer $300 every billing period until you change the quantity.

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.

Proration

Chargify support 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 next_billing_date.

For example:

  • The current_period_started_at date is January 1, 2020
  • The next_billing_date date has been modified to be February 15, 2010
  • 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 next_billing_date, 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, Chargify 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 Chargify 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.

Select the appropriate global component setting

Proration Scheme Types

  • Prorate + Accrue (prorate-delay-capture): A charge is added for the prorated amount due, but the card is not charged until the subscription’s next renewal

  • Prorate + Process (prorate-attempt-capture): A charge is added and we attempt to charge the credit card on file. If it fails, the charge will be accrued until the next renewal.

  • Full Cost + Accrue (full-price-delay-capture): A charge is added for the full price of the component change, but the card is not charged until the subscription’s next renewal.

  • Full Cost + Process (full-price-attempt-capture): A charge is added for the full price of the component change, and we attempt to charge the credit card on file. If it fails, the charge will be accrued until the next renewal.

  • No Cost Change (no-prorate): No charge is added.

The available downgrade schemes are:

  • Prorate: A credit is added for the amount owed.

  • No-prorate: No credit is added

NOTE: Proration uses the current price of the component as well as the current tax rates. If either has changed since the beginning of the period, 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

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

Updating Component Quantities

Each Chargify Site defaults the proration setting to prorate + accrue.

Update Quantity is signifigantly 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

  • Prorate + Accrue (prorate-delay-capture): When you allocate a quantity-based component under this scheme, no charges are applied at this time. There are no negative implications to the subscription.

  • Prorate + Process (prorate-attempt-capture): In this case, if the prorated transaction fails to process, you will receive the following warning message:

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.

  • Full Cost + Accrue (full-price-delay-capture): When you allocate a quantity-based component under this scheme, no charges are applied at this time. There are no negative implications to the subscription.

  • Full Cost + Process (full-price-attempt-capture): In this case, the subscription will exhibit the same attributes as the “Prorate + Process” failure above. The same warning will be received and the subscription balance will increase.

  • No Cost Change (no-prorate): When you allocate a quantity-based component under this scheme, no charges are applied at this time. There are no negative implications at this time.

Failed Metered Components

Metered componenents 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:

  1. The current balance is not increased
  2. The component is recorded against the subscription.
  3. The allocation for the metered-quantity appears in the “Activity” tab
  4. 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.

If the Cost Decreases

When you decrease the amount of components allocated to a subscription, Chargify gives you the option to choose the following:

  • Prorate and add a credit against future charges
  • Do not prorate component downgrades
Options to control price decreases

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

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

  1. On January 1, you have a subscription signup/payment for a $50.00/month product.
  2. Also, on January 1, you allocate 100 $1 quantity-based components for a total of $100
  3. She pays immediately for this component change
  4. If you have elected to Prorate and add a credit against future charges, the subscriber will receive a transactional based credit for the unused portion of the remaning billing period.
  5. If you select Do not prorate component downgrades no credit will be generated.
Transaction examples during proration

Updating the Price Point

The price point used on a component can be updated when allocating a new quantity, or it can be changed separately from the main components (Line Items) view:

Select "Update Price Point"
Select the new price point