Pricing Plan Changes (Upgrade/Downgrade)
- What happens when a customer switches from one plan to another?
- What happens on plan change when the customer has tracked item usage?
- What happens on plan change when there is a setup fee?
- What if the new plan doesn't include enough of item X?
- Overriding Default Behavior
1 What happens when a customer switches from one plan to another?
1.1 Paid Plan -> Paid Plan
Your choice. The simple answer is to just subject the customer to the new pricing plan's configuration on the pre-existing future billing date. The other option is to prorate the current billing period, apply a credit to the current invoice, transact the current invoice immediately and restart the customer's billing cycle at the moment of the plan change. Examples of each option follow (in fancy ascii art):
- Plan A: $45/month
- Plan B: $80/month
1.1.1 Simple Option - "Upgrade"
(1) (2) (3)
$45 $80
... ----|------------x-----------------|---- ...
May May Jun
8 20 8
1. Jill is on Plan A and is billed $45
2. Jill changes to Plan B
3. Jill is on Plan B and is billed $80
1.1.2 Simple Option - "Downgrade"
(1) (2) (3)
$80 $45
... ----|------------x-----------------|---- ...
May May Jun
8 20 8
1. Jill is on Plan B and is billed $80
2. Jill changes to Plan A
3. Jill is on Plan A and is billed $45
1.1.3 Prorate Option - "Upgrade"
(1) (2)
$45 $53
... ----|------------x
May | (3)
8 | $80
|------------------------------|---- ...
May Jun
20 20
1. Jack is on Plan A and is billed $45
2. Jack changes to Plan B. Calculating a prorated amount based on a standard 30
day month at the $45/mo rate, each day is worth $1.50 ($45 divided by 30 days).
He has received service for 12 days since his last bill on Plan A, worth
$18 ($1.50/day x 12 days). The remainder of the month is worth $27 ($45-$18).
A credit for $27 is added to a new invoice transacted immediately for a net
amount of $53 ($80-$27).
3. Jack is on Plan B and is billed $80 one month after plan change (2)
If you'd like to display the amount to the user prior to the upgrade, use this simple formula to match the prorated amount:
A = Plan A recurring charge amount
B = Plan B recurring charge amount
D = Days remaining until next (current) invoice bill date
Prorated charge = B - ( A - ( ( A / 30) * D ) )
1.1.4 Prorate Option - "Downgrade"
(1) (2)
$80 $0 (-$3)
... ----|------------x
May | (3)
8 | $42
|------------------------------|---- ...
May Jun
20 20
1. Jack is on Plan B and is billed $80.
2. Jack changes to Plan A. Calculating a prorated amount based on a standard 30
day month at the $80/mo rate, each day is worth $2.67 ($80 divided by 30 days).
He has received service for 12 days since his last bill on Plan B, worth
$32 ($2.67/day x 12 days). The remainder of the month is worth $48 ($80-$32).
A credit for $48 is added to a new invoice transacted immediately for a net
amount of -$3 ($45-$48). This effectively results in a $3 credit which is carried
over to the next invoice (3).
3. Jack is on Plan A and is billed $42 ($45 - $3) one month after plan change (2)
If you'd like to display the amount to the user prior to the downgrade, use this simple formula to match the prorated amount:
A = Plan A recurring charge amount
B = Plan B recurring charge amount
D = Days remaining until next (current) invoice bill date
Prorated charge/credit = A - ( B - ( ( B / 30) * D ) )
1.2 Free Plan -> Paid Plan
When a customer switches from a "free" plan to a paid plan, Cheddar considers it a new signup. In other words, it is not considered a plan change. A "free" plan is one that does not have a setup fee, a recurring fee or any tracked item overage charges. Read more about "free" plans.
2 What happens on plan change when the customer has tracked item usage?
The customer's quantity remains on the new subscription. The customer's usage will now be subject to the tracked item configuration of the new pricing plan. More fancy ascii art:
- Plan A: $45/month
- Item X: $5 overage amount
- Item Y: $10 overage amount
- Plan B: $80/month
- Item X: $4 overage amount
- Item Y: $9 overage amount
2.1 Simple Option - "Upgrade"
(1) (2) (3)
$70 $102
... ----|------------x-----------------|---- ...
May May Jun
8 20 8
1. Jill is on Plan A and is billed $70
* Item X quantity= 1
* Item Y quantity= 2
* $45 + (1 x $5) + (2 x $10)
2. Jill changes to Plan B
3. Jill is on Plan B and is billed $102
* $80 + (1 x $4) + (2 x $9)
2.2 Prorate Option - "Upgrade"
(1) (2)
$70 $78
... ----|------------x
May | (3)
8 | $102
|------------------------------|---- ...
May Jun
20 20
1. Jack is on Plan A and is billed $70
* Item X quantity=1
* Item Y quantity=2
* $45 + (1 x $5) + (2 x $10)
2. Jack changes to Plan B. Calculating a prorated amount based on a standard 30
day month at the $45/mo rate, each day is worth $1.50 ($45 divided by 30 days).
He has received service for 12 days since his last bill on Plan A, worth
$18 ($1.50/day x 12 days). The remainder of the month is worth $27 ($45-$18).
A credit for $27 is added to a new invoice transacted immediately for a net
amount of $53 ($80-$27) plus overage under the Plan A item configuration for a
total of $78.
* $53 + (1 x $5) + (2 x $10)
3. Jack is on Plan B and is billed $102 one month after plan change (2)
* $80 + (1 x $4) + (2 x $9)
3 What happens on plan change when there is a setup fee?
The answer to that question is very simple. You choose whether or not the setup fee is charged upon plan change or not. If the plan is configured to charge the setup fee upon plan change, it is added to the next billable invoice. If you use the simple option for plan changes, the new setup fee is added to the future billable invoice. If you use the prorate option for plan changes, the new setup fee is added to the prorated invoice that is transacted at the time of the plan change.
4 What if the new plan doesn't include enough of item X?
When changing plans, Cheddar examines the tracked item configuration to determine if it's possible to change to the new plan. If the included quantity for any item does not accommodate the customer's current quantity and overage is not allowed, the plan change is rejected with a 401 Request Unauthorized error.
5 Overriding Default Behavior
We try to keep things as simple as possible while providing as much flexibility as we can. It's a delicate balance. To that end, if some of Cheddar's behavior doesn't work perfectly for your billing model, you can usually override that behavior and impose your will by using the tools in a different way.
5.1 Custom Prorating
Cheddar can be configured to do some basic prorating on plan changes for you. It's pretty straightforward and only applies to the flat base recurring charge on a plan. Cheddar never prorates tracked item charges or custom charges. There's just too much going on there to have default behavior that would fit a significant portion of merchants' desires. So, you can do it any way you like.
5.1.1 One-time Invoice
Prior to executing a plan change, a one-time invoice built up of custom charges (credits, too, if needed) according to the amount you wish to charge a customer at the time of the plan change is probably the simplest way.
If the one-time invoice transaction is successful, then simply make the plan change. If you have Cheddar's prorate option enabled on the plan (or it's a free to paid change), you might want to also override the on-change transaction using the changeBillDate option.
5.1.2 Manipulating the "On-change" Invoice
Another option is to adjust the subscription prior to plan change. You can add charges and credits to the current invoice in preparation for the plan change. If the plan change results in a transaction in real-time (prorated paid->paid or free->paid on signup) any charges or credits on the current invoice will be settled at plan change.
There's a small gotcha when using this method: If the plan change action fails for whatever reason (e.g., declined transaction), the subscription reverts back to the original plan and everything stays the same as it was before the plan change action was executed. So, any credits or charges you added to prepare for the change will remain. In short, if the plan change fails, you might consider removing the credits and charges you had previously added.
5.2 Changing the Bill Date
When executing simple plan changes (see examples 1.1.1 and 1.1.2 above), you can pass in the changeBillDate param to override the default behavior. If the plan change behavior is configured to bill the customer on their next invoice date, you can override it to invoice the customer immediately on plan change by setting changeBillDate=now.