Setting Component Allocations

In order for Chargify to assess charges for your Components, you must report to us the Component’s status (i.e. quantity used or allocated, or whether the feature was enabled or not) for each Subscription.

In the UI, 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. If your Customer subscribed to the parent Product on the 23rd of the month, then he’ll get billed for any Components on the 23rd of each month, assuming the product is on monthly billing cycle. Chargify simply looks at the quantity on the billing date and then bills accordingly.

The exception to advance billing is Metered Components, which are billed in arrears according to the usage recorded during the billing period.

Future releases may allow for averaging of the count, “high-water mark”, 95th percentile, etc. There are a number of approaches we’ve heard about that will be interesting to consider.

Reporting Metered Component usage

For Metered Components, you record the amount your customer uses some “widgets” (units). At the end of the billing period, Chargify will bill your customer for the total number of widgets reported, and then we will reset the widget count to zero and the whole process starts over for the new billing period.

Note: 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 Admin UI by navigating to a subscription and selecting the “Components (Line-Items)” tab. This will display a list of all the available components.

Click the ‘Ops’ button to reveal the context navigation and click the ‘Record Usage’ link.

Enter a quantity and (optionally) a memo, and press ‘Record’. The quantity must be an integer (whole number).

Note that 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 “widgets” (units) being utilized, but the assumption is that those widgets stay in use by your customer forever, until some 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.

Note: this differs from Metered Components, which DO reset to zero at the start of every billing period.

Quantity component allocations can be updated using the Admin UI 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 Chargify UI by selecting the component from the “Components (Line-Items)” tab when viewing a subscription.

Proration

Chargify supports proration 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.

Note that proration is done based on the length of the current billing period for the subscription, not the billing period configured for the product.

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 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 Site Settings, but it can also be overriden 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.

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

You can easily 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 UI. 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.

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:

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.

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

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

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.

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: