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.
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 tell our API every time 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.
The API calls required to report usage are detailed in API: Metered Usage.
Reporting Quantity-based allocations
For Quantity-based Components, you tell our API every time 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.
The API calls required to report allocated quantities are detailed in API: Quantity Alocations.
Reporting On/Off component status
You report the status of On/Off Components (i.e. “enabled” or not) using
allocated_quantity similarly to Quantity-based components. Report a
1 for on and
0 for off.
On/Off components can be toggled using the Admin UI by selecting the component from the “Components (Line-Items)” tab when viewing a subscription.
The API calls required to report allocated quantities are detailed in API: Quantity Alocations (they behave much like Quantity-based allocations).
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.
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, both through the API as well as the Admin UI. 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.
The available ‘upgrade’ schemes are:
- 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-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-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.
- 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.
- 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.