Pricing Plan Basics
- Introduction
- Billing Frequency
- Status
- Setup Charge
- Recurring Charge
- Tracked Items
- Access Control
- Changing from Plan to Plan
- Free Pricing Plans
- Free Trials on Paid Plans
- Scripted Billing with Webhooks
1. Introduction
Cheddar's pricing plan system is easy to deploy, use, and maintain.
Our pricing plan configuration is deceptively simple. By that, we mean not only is configuring pricing plans quick and easy, but it is also extremely flexible. If you can imagine a pricing model, Cheddar's pricing plan configuration probably supports it.
To start, let's break down the anatomy of a pricing plan:
2. Billing Frequency
Pricing plans can be configured to bill on several frequencies:
- Daily
- Weekly
- Bi-Weekly (every two weeks)
- Monthly
- Bi-monthly (every two months)
- Quarterly (every three months)
- Semi-Annually (every six months)
- Annually
- Biennially (every two years)
- None (no recursion)
It is possible to bill on other frequencies. Just shoot us a question and let us know what you'd like to do.
2.1 Invoice Period
The invoice period is the effective span of time that the invoice is used to bill the customer for. A customer's initial invoice period starts at the moment of signup and ends at the moment of the billingDatetime of the first invoice. Those two moments are the same if the initial invoice is billed on signup. Subsequent invoice periods start and end on the billingDatetime of an invoice, down to the second.
2.2 Recurring vs. Non-recurring
You might be wondering what the "None (no recursion)" frequency means. That's pretty simple, actually. A subscription with a pre-defined recurring frequency will always have a current invoice period with a definitive end, according to the current invoice billingDatetime. If the customer is subscribed to a pricing plan without a defined frequency (the "None" option), then the current period will not have a pre-defined end, by default. In other words, the "current" or "pending" invoice will not have a set billingDatetime. On subscriptions of this type, it is up to you or your system to determine when the current period will end.
You may change the billingDatetime on the current invoice anytime you like, whether the invoice already has a bill date or not. By changing the bill date (or setting it in the case of a non-recurring subscription), you can decide when the current invoice period will end and when the customer will be charged for that invoice. You can even set it to now or today's date to transact the current invoice immediately.
A non-recurring subscription is handy for several revenue models. For example, a "pay-as-you-go" (PAYG) model where the customer pays in advance for credits and must pay again when their credits are depleted calls for a custom billing frequency. Another example is a simple "one-click" buying model. In this case, use a non-recurring plan to "house" customers' payment information. Then when they decide to buy, execute the current invoice (after adding some charges or tracked item overage) by setting the bill date to now. Or, use a one-time invoice.
2.3 Calculating Next Bill Date
Cheddar automatically calculates the next bill date for you for recurring plans. However, you might want to calculate it yourself. There are two components of the calculation: the plan billingFrequencyUnit ('days' or 'months') and billingFrequencyQuantity (the # of days or months). So, if billingFrequencyUnit=months and billingFrequencyQuantity=2 and the last bill date occurred on 2018-02-15, then the next bill date will be 2018-04-15, exactly 2 months later.
Some months have 31 days, so what happens when the next month only has 30? When the frequency is monthly, the next bill date is always one month from the last bill date. If the bill date is on the 15th, for example, it will be on the 15th of every month. If the first one is on the 31st, and the next month only has 30 days, then the next bill date will be on the 1st of the following month. Every subsequent bill will then be on the 1st.
3. Status
The status doesn't mean much really. It is just a way of grouping pricing plans into two groups. They are labeled 'Active' and 'Inactive' but you can think of them as anything. We consider the two statuses to mean 'Public' and 'Private' because we have some pricing plans that are offered to the public (the plans on the pricing page of our website) and some that are private (plans reserved for special internal purposes or legacy plans).
Specifically regarding the hosted pages: Only 'Active' plans are shown on the hosted pages. If you want to prevent a plan from being available in the pricing plan selector on hosted pages, just uncheck the 'Active' box for that plan.
4. Setup Charge
The setup charge is a flat amount billed once. You may choose to charge the setup fee at the time of signup or attach it to the first recurring invoice (which may be delayed or transacted at the time of setup).
An alternative to a configured setup charge is to use a custom charge for the fee at any time. You may also choose to use a one-time invoice to execute a transaction for any amount at any time.
5. Recurring Charge
The recurring charge is just that: the flat amount that is billed to the subscriber on the plan's billing frequency. You may choose to transact the first recurring invoice (with the recurring charge) immediately upon signup for the plan or you may delay the first recurring invoice for some time in the future after signup. Delaying the first recurring invoice can be used to facilitate a trial period. When delaying the first recurring invoice, the invoice period is considered to be the time between the moment of signup and the first billing date.
6. Tracked Items
Tracked Items are the ingredients of the special sauce of Cheddar. They can perform amazing feats never before seen by human eyes (not really but they make Cheddar pretty powerful). A tracked item can be used for something as simple as indicating whether a feature on your website should be available to the subscriber or for something resembling a traditional transaction micro-billing model, even recurring discounts. And that's not all...
6.1 Theory of Operation
6.1.1 Two General Components
6.1.1.1 Tracked Item Configuration
The first component is the tracked item configuration within pricing plans. Tracked item configuration, together with pricing plans, can be considered the structure of a pricing model. Pricing plans are like configuration foundations and items are the building blocks. The configuration is set and typically does not change. Changes to pricing plan item configuration (or creating new pricing plans) would be considered a change to your pricing model (e.g., increasing/decreasing prices, adding items, etc). See Pricing Plan Configuration Changes for more on changing your pricing and/or grandfathering pricing.
Each pricing plan contains distinct configuration for each item. The following fields are configured for each item for each pricing plan:
- Quantity Included: The quantity of this item that is included or "bundled" in the pricing plan. If the included quantity is set to zero (0), no amount of this item comes with a subscription to this pricing plan. May be defined up to 4 decimal places. May be negative.
- Overage Amount: The price of each quantity over the Quantity Included. If set to zero (0), no amount over the Quantity Included setting is available on this plan. May be defined up to 4 decimal places. May be negative.
- Reset: Whether or not customer item quantity should be reset to zero (0) at the beginning of a new invoice period.
6.1.1.2 Customer Quantity Settings
The second component is the setting of the quantity used by each of your customers. Customer item quantity is set to zero (0) by default for each item. A customer's quantity of a particular item can be changed from time to time according to your specifications (e.g. according to a customer's usage of a particular feature of your service). Cheddar may also be configured to make an important change to your customers' tracked item quantity using the "reset" option. More on that below.
6.1.2 How The Two Components Work Together
The two components of tracked items work together with the subscribed pricing plan to achieve significant flexibility in your pricing model. The components are used to calculate the variable charges incurred by a customer during the previous invoice period.
If the customer's quantity of an item is greater than the quantity included on the subscribed pricing plan, then we multiply the difference by the overage amount which results in the charge line item for the additional quantity of the item on the invoice. For example, if the included quantity equals 10, the overage amount equals 3.50, and the customer's quantity is set to 12, the charge for that item will be 7.00 or (12 - 10) * 3.50 = 7.00.
Next, we examine whether or not the configuration for the tracked items include the "Reset" flag (also referred to as "Is Periodic"). If a tracked item is configured to Reset, then customers' quantity of the item is automatically reset to zero at the beginning of the next invoice period. Otherwise, the customer's quantity for that tracked item is untouched.
6.1 Examples
Here are a few tracked item recipes that should give you an idea of the capabilities of the tracked item system using various combinations of configurations. Again, we'll assume that the plan bills on a monthly frequency:
6.1.1 Enable/Disable Feature Toggle
Using these settings will allow/disallow access to the Whatchamacallit feature. So to make this work, you use the API to ask Cheddar to which plan your customer is currently subscribed. The result from the API contains information on whether or not the currently subscribed plan includes an available quantity of the Whatchamacallit item. You control access to the Whatchamacallit feature in your application's based on this information. You can also think of this technique as a pricing plan-specific Access Control List (ACL).
- Name: Whatchamacallit
- Quantity Included: 1 (if you set it to zero, it's not available on this pricing plan)
- Overage Amount: 0.00 (this doesn't really matter)
- Reset: No (or Yes if the feature should be automatically turned off at the end of the period)
- Set a customer's quantity of the item to (1) if the customer uses it or (0) if they don't.
6.1.2 Charge for "Add-ons"
Using these settings will charge access to the MixIn add-on. So to make this work, you use the API to ask Cheddar to which plan your customer is currently subscribed. The result from the API contains information on whether or not the customer has selected the MixIn. You control access to the MixIn add-on in your application based on this information. You can also think of this technique as a customer-specific access control list (ACL).
- Name: MixIn
- Quantity Included: 0
- Overage Amount: 14.95
- Reset: No
- Set a customer's quantity of the item to the number of MixIns they should be charged for on each recurring invoice.
6.1.3 Hard Usage Limits
Track access of and restrict access to a usage feature (Thingamabob) of your application with a HARD limit. Subscribers of the plan with the following item settings can only have 100 Thingamabobs per billing cycle. If they want more, they have to change to another plan that has a higher quantity included.
- Name: Thingamabob
- Quantity Included: 100 (this is the limit)
- Overage Amount: 0.00 (zero indicates that the quantity included is a hard limit)
- Reset: Yes (this indicates that the customer's usage should be reset after each billing instance -- so, in other words, the quantity included is a hard limit per billing cycle)
- Set customers' quantity of this item as they use it. If you try to set a quantity over 100, the API returns an error indicating that the customer cannot use more of that item (presumably unless they upgrade -- UPSELL!). See Using Item Quantity Restrictions for Upselling for more detail on error codes.
6.1.4 Soft Usage Limits
Track access of and restrict access to a usage feature (Thingamajig) of your application with a SOFT limit. Subscribers of the plan with the following item settings can have up to 50 Thingamajigs per billing cycle without incurring additional charges. Each item used over the 50 included are added to the next invoice at $0.99 each.
- Name: Thingamajig
- Quantity Included: 50 (this is the limit)
- Overage Amount: 0.99 (a non-zero value indicates that the quantity included is a soft limit -- each item over the quantity included is billed at $0.99 each)
- Reset: Yes (this indicates that the customer's usage should be reset after each billing instance -- so, in other words, the quantity included is a hard limit per billing cycle)
- Set customers' quantity of this item as they use it. A customer with a quantity over 50 will be charged for the difference (e.g. if quantity=65 then the charge will be 15x0.99=14.85)
6.1.5 Usage Limits for the Life of the Subscription
Track access of and restrict access to a usage feature (Doohicky) of your application with a HARD limit for THE LIFE OF THE SUBSCRIPTION. Subscribers of the plan with the following item settings can have up to 500 Doohickies for the life of the subscription. If they want more Doohickies, they have to change to a different plan that includes more Doohickies.
- Name: Doohicky
- Quantity Included: 500 (this is the limit)
- Overage Amount: 0.00 (zero indicates that the quantity included is a hard limit)
- Reset: No (this indicates that the quantity included is the limit for the life of the subscription)
- Set customers' quantity of this item as they use it. If you try to set a quantity over 500, the API returns an error indicating that the customer cannot use more of the item (presumably unless they upgrade -- UPSELL!). See Using Item Quantity Restrictions for Upselling for more detail on error codes.
6.1.6 "Micro Billing" or "Metered Usage"
Micro-billing for a usage feature (Doodad) of your application. Subscribers of the plan with the following item settings are billed for each Doodad they use.
- Name: Doodad
- Quantity Included: 0 (there aren't any included in the plan)
- Overage Amount: 0.19 (we'll bill subscribers for each Doodad they use at $0.19 each)
- Reset: No (this doesn't really matter but if you want Cheddar to track how many Doodads someone has ever used, this should be "No". A "Yes" value will tell Cheddar only to remember how many they've used in the current billing cycle.)
- Set customers' quantity of this item as they use it. A customer with positive quantity of this item will be charge for each (e.g. if quantity=65 then the charge will be 65x0.19=12.35)
Metered Usage for an amount of Prepaid Credits for your application. Subscribers of the plan with the following item settings are allotted a specified amount of Prepaid credit for the invoice period which will decrease over the period.
- Name: Prepaid Credits
- Quantity Included: 99999999.9 -- Unlimited Yes, this is confusing. What this indicates in the case of prepaid credits is that you can prepay for an unlimited number of credits (as far as Cheddar is concerned)
- Overage Amount: 0 There's no such thing as overage with prepaid credits. You could, however, set this to the amount you charge per credit so you can make it different on each plan and use Cheddar's config as the authority on what you charge on each plan
- Reset: No The current quantity allocated to the customer is carried over to the next billing cycle. If set to Yes, the quantity is reset to zero at the beginning of each billing cycle
- Set a customer's quantity of the item equal to the quantity they've paid for to-date. As the customer uses the credits, decrement the customer's quantity of the item in Cheddar. When the customer's quantity gets low, prompt the customer to buy more or simply automatically charge them (with permission, of course). Use a one-time invoice to charge for additional credits. One-time invoices can be executed at-will as long as the customer's subscription has a valid payment method on file.
6.1.7 Recurring Discounts
Recurring discount (Discount). Subscribers of the plan with the following item settings are given a discount on each invoice.
- Name: Discount
- Quantity Included: 0 (there aren't any included in the plan)
- Overage Amount: -0.01 (note the negative amount - we'll discount the invoice by 0.01 for each quantity)
- Reset: No
- Set a customer's quantity of the item to the discount amount. If the customer has a quantity of 45.50, the customer will receive a 45.50 discount on each recurring invoice.
6.1.8 Unlimited Usage
An item with unlimited quantity included. Subscribers of the plan with the following item settings are not restricted and are never charged overage.
- Name: Hugs
- Quantity Included: 99999999.9 (the magic number to indicate infinity)
- Overage Amount: 0 (overage amount is required to be zero)
- Reset: No/Yes (your choice!)
- Set customer's quantity of the item as the item is used.
6.2 Fractions
Both Quantity Included and Overage Amount can be set with accuracy up to 4 decimal places. Further, when setting an individual customer's quantity of an item, the customer's quantity can be set to a value up to 4 decimal places. This enables merchants to charge for usage or items with fractions of a penny, or for fractions of a unit of usage. A couple of examples:
- Disk Space. Subscribers of the plan with the following item settings are charged for fractions of a gigabyte of data storage.
- Name: Storage
- Quantity Included: 0 (or 1, for example, to include 1Gb with the plan)
- Overage Amount: 10.00 ($10 per gigabyte)
- Reset: No (Cheddar will not reset customers' quantities to zero at the beginning of each billing cycle)
- When setting a customer's quantity for the item, calculate the number of megabytes and divide by 1024. If the customer is using 60Mb, you would set the customer's quantity to 0.0586. At $10 per gig, the customer is charged $0.59 for storage.
- Timed usage. Subscribers of the plan with the following item settings are charged for fractions of a minute of chat time.
- Name: Chat Time
- Quantity Included: 0 (or 60, for example to include 1 hour with the plan)
- Overage Amount: 0.0546 (approximately 5.5 cents per minute)
- Reset: Yes (Cheddar resets customers' quantities to zero at the beginning of each billing cycle)
- When setting a customer's quantity, calculate the number of seconds and divide by 60. If the customer used 1 hour, 32 minutes, 14 seconds of chat time, you would set the customer's quantity to 92.2333 (5534 seconds divided by 60). At $0.0546 per minute, the customer is charged $5.04 for chat time.
7. Access Control
Pricing plan configuration, including tracked item configuration, along with customers' quantity of items should be used as part of your application's access control system. In other words, your application should provide a level of service to a customer according to what they pay you for that service. As such, allowing or denying access to various aspects of your system or limiting usage of consumable elements of your service is an integral part of your application's interaction with Cheddar.
7.1 Using Item Quantity Restrictions for Upselling
The concept of access control also provides for an opportunity to present a clear and logical upgrade path for your customers. Using a well-developed Access Control List (ACL) powered by Cheddar pricing plans and tracked items in your application, you can prompt your customers to change to a higher priced plan to gain access to your service at a higher level.
When a customer attempts to update a tracked item quantity or change to a pricing plan in a way that doesn't align with the item or plan limits you've set in Cheddar, the API will return a 412 error (Precondition Failed). If this happens, the auxCode attribute of the error node will give you the info you need to identify the cause of the error and pass along a message to your customer about why the item or plan change failed.
For example, if you utilize hard limits in your tracked items configuration, requests to Cheddar to update an amount to a value higher than the hard limit will return an error with the aux code attribute quantity:notLessThanOrEqual. Here's an example of the error response your application would receive in this scenario:
<?xml version="1.0" encoding="UTF-8"?>
<error id="85" code="412" auxCode="quantity:notLessThanOrEqual">
'401' is not less than or equal to '400'
</error>
When your application receives this response, it can prompt the customer to upgrade to a plan that includes a higher limit of the item.
In some cases, customers may try to update an item for less than the allowed amount. In this case Cheddar will return an error with the aux code quantity:notGreaterThanOrEqual. Here's an example of that error response:
<?xml version="1.0" encoding="UTF-8"?>
<error id="97" code="412" auxCode="quantity:notGreaterThanOrEqual">
'-1' is not greater than or equal to '0'
</error>
There's also an itemQuantityConflict error which results from a customer trying to change to a plan that has an item configuration that precludes changing to that plan according to the customer's current quantity of an item.
<?xml version="1.0" encoding="UTF-8"?>
<error id="31" code="412" auxCode="planCode:itemQuantityConflict:STORAGE">
Item quantity (11.28) of "Gigabytes of Storage" conflicts with the target pricing plan
</error>
Questions about how Cheddar handles errors in other situations? Check-out the Error Handling Knowledge Base article.
8. Changing from Plan to Plan
You might think of this as plan upgrades or plan downgrades. Due to the nature of Cheddar's flexibility, it is impossible to definitively know if a plan change is an upgrade or a downgrade, so we just call it a plan change. You may configure a pricing plan to behave in one of two different ways when a customer changes her subscription to the plan. The first option is very simple. When a customer changes plans, the invoice period stays the same. The only difference is that the new plan's settings are enforced on the next billing date. Here's an example:
A customer signs up for Plan A, a monthly plan, on 2019-10-25. The customer's next invoice is set to be billed on 2019-11-25. The customer changes to Plan B on 2019-10-29. The customer's billing date is still 2019-11-25. The invoice will now include the recurring charge for Plan B. The new subscription will retain the tracked item usage information from the previous plan and the tracked items will be subject to the configuration of the new plan.
The second option is a little less simplistic. When a customer changes plans, the previous plan recurring charge amount is prorated and entered in the invoice as an adjustment. The invoice is then transacted immediately and a new invoice period begins. Here's an example:
A customer signs up for Plan A, a monthly plan with a recurring charge of $50, on 2019-10-12. The customer's next invoice is set to be billed on 2019-11-12. The customer changes to Plan B, a monthly plan with a recurring charge of $100, on 2019-10-20. The customer has paid for a month starting on 2019-10-12 but has only received 8 days of service. Based on a 30 day month, the customer has received $13.33 worth of service on Plan A. The difference ($50 - $13.33 = $36.67) is entered as a custom credit on the current invoice. The current invoice now contains the new recurring charge of $100 and a custom credit of $36.67 for a net amount of $63.33. The invoice is transacted and a new invoice period begins. The customer will then be charged $100 on 2019-11-20. The new subscription will retain the tracked item usage information from the previous plan and the tracked items will be subject to the configuration of the new plan.
This behavior is different if the the customer changes from a free plan to a non-free plan. Changing from a free plan to a non-free plan is synonymous with initially signing up for the free plan. See the "Free" Pricing Plans KB article for more information.
Click here for a more in-depth discussion about pricing plan changes.
9. Free Pricing Plans
Cheddar behaves differently when interacting with "free" pricing plans. A pricing plan is free if the plan:
- Has a setup charge amount equal to zero.
- Has a recurring charge amount equal to zero.
- Does NOT have potential for tracked item usage overage charges. All overage amount settings are equal to zero.
In other words, if it's impossible to incur charges for the subscribed pricing plan, then it is considered free. Some of the things that Cheddar does differently when a customer's subscribed plan is free are:
- Payment information is not required when subscribing the customer to the plan. If there's no potential for incurring charges, then we don't need payment... Amazing.
- If the customer changes from a free plan to a non-free plan, the behavior is the same as if the customer initially signed up for the non-free plan to begin with.
- Custom charges are disabled for subscriptions to free plans. * See below for a workaround.
- The email notification configuration includes preferences for disabling individual notification types based on whether or not the customer's subscribed plan is free. Email Notification Configuration
- Email notification templates include an embedded variable called
$plan.isFreefor use in the template. Email Notification Configuration - Customer API response includes a flag indicated whether or not the subscribed plan is free.
Free plans are most often used for a freemium strategy. Or, simply for subscribers who you want to anoint with unlimited free access to your system. You know, like your mom.
10. Free Trials on Paid Plans
You may choose to allow customers to signup for a paid plan without a payment method. That sounds like the definition of a free trial. Those customers have the opportunity to use your service without paying until they've learned about its value by using it over a period of time. You can make that period of time as long or as short as you wish by setting the plan to initially bill some number of days or months after signup. Or, you can override a default plan setting when subscribing the customer using the initialBillDate param via the API.
10.1 Converting Free Customers To Paying Customers
This is the name of the game and Cheddar has several tools at your disposal to help in this effort:
- Use the New Subscription Email Notification or the New Subscription Webhook to inform the new customer about the terms of the trial
- Use the Bill Reminder Email Notification or the Bill Reminder Webhook to warn trial subscribers of an impending end to their trial period
- Extend the trial period using the
changeBillDateparam of the Update Subscription API call. You could trigger your app to do this via the Bill Reminder Webhook or you can, as always do it manually via the admin GUI.
11. Scripted Billing with Webhooks
One of Cheddar's most powerful features is its robust webhook system. In particular, the Subscription Billable Webhook allows you to script billing behavior in Cheddar. If the above plan configurations don't meet your specific needs, scripted billing ensures you get all the benefits of Cheddar (customer communication, dunning, recurring management, etc.) without compromising any of your billing requirements.
For example, let's say you wanted to implement custom tiered billing logic in Cheddar where the first 1-100 widgets used in a given month are billed at $1 each, but widgets over 100 used are billed at $2 dollars. Inside Cheddar you could set up 3 tracked items:
- Widgets (A utility Tracked Item to track the total number of widgets)
- Tier 1 Widgets (billed at $2 each)
- Tier 2 Widgets (billed at $1 each)
When an invoice is generated in Cheddar you can listen for the Subscription Billable Webhook, and build a script in your codebase that allocates the widget usage as you see fit between tiers. This same scripting workflow can be used for all kinds of custom behaviors like commissions, bill date synchronization, contracted price increases, and hundreds more custom scenarios.
For more information about using the power of Cheddar's scripted billing check out this article on Invoice Review.