Upgrade¶
What is an upgrade?¶
When a customer moves to a more expensive set of packaging this can be referred to as an “upgrade”. This is a common contract lifecycle event that often results in a contract ending a new one beginning. Let’s go through an example where a customer on the standard Wikipedia pricebook will upgrade to an enterpise plan:
As of 5/15/2024, “EmpressHarmonic” currently is using the “Standard” plan and is thinking about moving to the “Enterprise” plan in the future.
customers.id |
customers.name |
contracts.durable_id |
contracts.started_at |
contracts.ended_at |
contracts.pricebook_id |
|---|---|---|---|---|---|
20450 |
EmpressHarmonic |
EmpressHarmonic_contract |
2024-02-29 14:36:13 |
2025-02-01 00:00:00 |
a |
products.id |
products.name |
list_prices.id |
list_prices.price |
pricebooks.durable_id |
pricebooks.name |
invoice_delivery |
invoice_schedule |
list_prices.created_at |
|---|---|---|---|---|---|---|---|---|
1 |
Updates |
1 |
0.10 |
a |
Standard |
ARREARS |
1 |
2023-11-01 |
2 |
Creates |
2 |
0.05 |
a |
Standard |
ARREARS |
1 |
2023-11-01 |
3 |
Platform fee |
3 |
1000.00 |
a |
Standard |
ADVANCED |
12 |
2023-11-01 |
products.id |
products.name |
list_prices.id |
list_prices.price |
pricebooks.durable_id |
pricebooks.name |
invoice_delivery |
invoice_schedule |
list_prices.created_at |
|---|---|---|---|---|---|---|---|---|
1 |
Updates |
4 |
0.05 |
b |
Enterprise |
ARREARS |
1 |
2023-11-01 |
2 |
Creates |
5 |
0.04 |
b |
Enterprise |
ARREARS |
1 |
2023-11-01 |
4 |
Enterprise platform fee |
6 |
5000.00 |
b |
Enterprise |
ADVANCED |
12 |
2023-11-01 |
How to model an upgrade¶
There are two major determinants of how to model an upgrade:
Invoice delivery
Date of upgrade
Based on the invoice delivery the customer has paid for the product in advance or will do so once the period is complete. In the case where a customer has paid upfront, an upgrade can become more complex. In the example above, “EmpressHarmonic” has already paid an annual platform fee for the standard plan. They would like to upgrade to the Enterprise plan which has an annual platfrom fee which is five times the price. Since the date of the upgrade is in the middle of current contract we need to make sure “EmpressHarmonic” isn’t double charged.
One way to deal with this is to refund the customer. Often this “refund” occurs as a part of the upgrade itself. In this case, moving from the Standard plan to an Enterprise plan requires the customer pays a larger platform fee. By including the refund within the upgrade invoice returning funds can be avoided. We can accomplish this by adding an ad hoc product to the contract. Specifically this product should be the same as the one decommissioned by the upgrade. This will appease the customer since they aren’t being double charged, and is an accurate record of the actual revenue accrued by each product.
customers.id |
customers.name |
contracts.durable_id |
contracts.started_at |
contracts.ended_at |
contracts.pricebook_id |
contracts.version |
|---|---|---|---|---|---|---|
20450 |
EmpressHarmonic |
EmpressHarmonic_contract |
2024-02-29 14:36:13 |
2025-02-01 00:00:00 |
a |
0 |
20450 |
EmpressHarmonic |
EmpressHarmonic_contract |
2024-02-29 14:36:14 |
2024-05-15 00:00:00 |
a |
1 |
20450 |
EmpressHarmonic |
upgrade_contract |
2024-05-15 00:00:00 |
2025-01-01 00:00:00 |
b |
0 |
It can be seen in the rows above that there are two versions of the EmpressHarmonic_contract. The first version is the original contract, the second version has a backdated end date to the middle of the current period: 5/15/2024. Since the end date is within the current billing period of May 2024 we do not need to void or adjust any past arrears invoices. As mentioned prior we need to handle invoices that were issued in advance, specifically the “Platform fee”.
products.id |
products.name |
prices.contract_price_uid |
prices.list_price_uid |
prices.price |
prices.prorate |
contracts.customer_id |
contracts.durable_id |
contracts.pricebook_id |
prices.started_at |
prices.ended_at |
|---|---|---|---|---|---|---|---|---|---|---|
1 |
Updates |
4 |
0.05 |
true |
EmpressHarmonic |
upgrade_contract |
b |
2024-05-15 |
2025-01-01 |
|
2 |
Creates |
5 |
0.04 |
true |
EmpressHarmonic |
upgrade_contract |
b |
2024-05-15 |
2025-01-01 |
|
3 |
Platform fee |
4 |
-1000.00 |
true |
EmpressHarmonic |
upgrade_contract |
b |
2024-05-15 |
2025-01-01 |
|
4 |
Enterprise platform fee |
6 |
5000.00 |
true |
EmpressHarmonic |
upgrade_contract |
b |
2024-05-15 |
2025-01-01 |
The newly created upgrade_contract has inherited the enterprise packaging, included in pricebook b, and has included an ad hoc contract price, prices.contract_price_uid = 4, to account for the refund. One thing to note is that the price is negative and the proration flag is set to true. The negative price enables the refund to occur and the proration flag ensures that only the unused portion of the period is actually returned once rated. Another important point is that the ad hoc price specifically uses the original product that is being decommissioned to avoid overrepresenting the amount of revenue being gained and lost.
Once the original contract is updated and the upgraded contract is created the modeling is complete. With this the correct invoices should be automatically generated.
Results of the upgrade¶
The changes result in two additional invoices being generated. One invoice in arrears and the other in advanced.
products.id |
products.name |
line_items.price |
line_items.quantity |
line_items.amount |
invoices.total |
invoices.invoice_delivery |
invoices.status |
invoices.contract_id |
invoices.started_at |
invoices.ended_at |
|---|---|---|---|---|---|---|---|---|---|---|
1 |
Updates |
0.05 |
11140.0 |
557.0 |
557.0 |
ARREARS |
DRAFT |
upgrade_contract |
2024-05-15 00:00:00 |
2024-06-01 00:00:00 |
2 |
Creates |
0.04 |
0.0 |
0.0 |
557.0 |
ARREARS |
DRAFT |
upgrade_contract |
2024-05-15 00:00:00 |
2024-06-01 00:00:00 |
products.id |
products.name |
line_items.price |
line_items.quantity |
line_items.amount |
invoices.total |
invoices.invoice_delivery |
invoices.status |
invoices.contract_id |
invoices.started_at |
invoices.ended_at |
|---|---|---|---|---|---|---|---|---|---|---|
3 |
Platform fee |
-1000.00 |
1.0 |
-632.88 |
2531.5 |
ADVANCED |
FINALIZED |
upgrade_contract |
2024-05-15 00:00:00 |
2025-01-01 00:00:00 |
4 |
Enterprise platform fee |
5000.00 |
1.0 |
3164.38 |
2531.5 |
ADVANCED |
FINALIZED |
upgrade_contract |
2024-05-15 00:00:00 |
2025-01-01 00:00:00 |
The resulting invoices and line items from the new upgrade_contract only represent one half of the month of May. This is true for both the ADVANCED and ARREARS invoices but each invoice delivery type requires a different process to calculate the resulting line item. Both of the ADVANCED line items require proration. Since we are performing the upgrade in the middle of the contracted period, with only around 7 months left, the typical annualized platform fee price no longer makes sense. Thus the “Enterprise platform fee” should only be charged for the smaller period, hence the proration. The rough math to get the prorated amount is the amount of days between the start and end date divided by the amount of days the price is associated with. In this case 5/15/2024 to 1/1/2025 is 231 days and the annualized platform fee is over 365 days. This gets us a proration factor of 231 / 365 = 0.63 which we multiply by the price to get the prorated value, 0.63 * 5000 = 3164.38, which can be seen on the line item as the amount. The same adjustment is made to the refund product since this is the ‘amount’ that should be returned.
The new ARREARS invoice doesn’t require a special adjustment, but the invoice tied to the previous contract, durable_id='EmpressHarmonic_contract', must be cut short to represent the backdating. This results in two invoices during the month of May, one for the prior contract and the other for the upgraded contract.
invoices.contract_id |
products.id |
products.name |
line_items.price |
line_items.quantity |
line_items.amount |
invoices.total |
invoices.invoice_delivery |
invoices.status |
invoices.started_at |
invoices.ended_at |
|---|---|---|---|---|---|---|---|---|---|---|
EmpressHarmonic_contract |
1 |
Updates |
0.10 |
4725.0 |
472.5 |
472.5 |
ARREARS |
FINALIZED |
2024-05-01 00:00:00 |
2024-05-15 00:00:00 |
EmpressHarmonic_contract |
2 |
Creates |
0.05 |
0.0 |
0.0 |
472.5 |
ARREARS |
FINALIZED |
2024-05-01 00:00:00 |
2024-05-15 00:00:00 |
upgrade_contract |
1 |
Updates |
0.05 |
11140.0 |
557.0 |
557.0 |
ARREARS |
DRAFT |
2024-05-15 00:00:00 |
2024-06-01 00:00:00 |
upgrade_contract |
2 |
Creates |
0.04 |
0.0 |
0.0 |
557.0 |
ARREARS |
DRAFT |
2024-05-15 00:00:00 |
2024-06-01 00:00:00 |
Going forward no new modeling changes need to occur. Fortunately, the timing of this upgrade was beneficial to the customer “EmpressHamonic”. They literally doubled their usage in the back half of May and accomplished a savings of $560 in roughly two weeks. Going forward this upgrade could easily pay for the more expensive platform fee and deliver an even larger savings on top of that. This type of outcome highlights why customers care about upgrades and why they want them immediately. Fortunately, this type of situation is a win-win since customer happiness and increased spend are typically topline metrics for a go-to-market team.