Upgrades, downgrades and prorating

Upgrading and downgrading subscriptions often involves complicated logics and maths to correctly prorate the cutomer’s subscription amount. ProcessOut can do it all for you

Understanding what prorating does

When a customer upgrades or downgrades its Subscription in the middle of it, it means that part of the subscription was used, and the other part wasn’t. In other terms, it means the customer has paid for something that’s not going to be used anymore. For this reason, merchants might want to charge the customer an additional amount of money for an upgrade, or give the customer credit for a downgrade.

Let’s see a quick example: The customer John has subscribed to a hosting company for his servers. This subscription costs him $10 per month. However, John wants to upgrade his subscription to get a better server and switches to the $20 plan at the day 15 (of 30) of the subscription.

This means that of the $10 that John paid for the initial plan, he used half of it (15 / 30), which represents $5. Because John switches over to a plan that costs $20 per month, the second half of the subscription will cost him $10 ($20 / 2). John is therefore in debt for $10 - $5 = $5, which he’ll be automatically charged for by ProcessOut when he switches over to the new plan.

The same applies for a downgrade. However, because the customer doesn’t have any debt anymore but is rather owed money by the merchant, ProcessOut will add this amount to the customer balance so that John gets charged less for his next payment.

Prorating is therefore used to preserve the subscription period but keep the amount owed by the customer or merchant up to date.

Upgrading or downgrading a customer

To upgrade or downgrade a Customer, all you’ll need to do is to update the subscription with the new plan ID.

Prorating may also be enabled or disabled when it best fits the merchant needs. It is disabled by default.

curl -X PUT https://api.processout.com/subscriptions/sub_7kAxfNML6jIc3bltGIt0uK2nKHDyzzq3 \
    -u test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x:key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8 \
    -d plan_id="gold-plan" \
    -d prorate=true
var ProcessOut = require("processout");
var client = new ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x",
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8");

client.newSubscription().find("sub_7kAxfNML6jIc3bltGIt0uK2nKHDyzzq3").then(
    function(subscription)
        subscription.save({
            plan_id: "gold-plan",
            prorate: true
        }).then(function(subscription) {
            // The subscription was successfully upgraded to the gold
            // plan and prorated

        }, function(err) {
            // The upgrade could not be done. Maybe the plan does not 
            // exist?

        });
    }, function(err) {
        // The subscription could not be found

    });
import processout
client = processout.ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8")

subscription = client.new_subscription().find("sub_7kAxfNML6jIc3bltGIt0uK2nKHDyzzq3")
subscription.save({
    "plan_id": "gold-plan",
    "prorate": true
})
require "processout"
client = ProcessOut::Client.new(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8")

subscription = client.subscription.find("sub_7kAxfNML6jIc3bltGIt0uK2nKHDyzzq3")
subscription.save(
    plan_id: "gold-plan",
    prorate: true
)
<?php
$client = new \ProcessOut\ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8");

$subscription = $this->newSubscription()->find("sub_7kAxfNML6jIc3bltGIt0uK2nKHDyzzq3");
$subscription->save(array(
    "plan_id": "gold-plan",
    "prorate": true
));
import "gopkg.in/processout.v4"
client := processout.New(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8")

sub, err := client.NewSubscription().Find("sub_7kAxfNML6jIc3bltGIt0uK2nKHDyzzq3")
if err != nil {
    panic(err)
}

_, err = sub.Save(&processout.SubscriptionSaveParameters{
    Subscription: &processout.Subscription{
        PlanID: processout.String("gold-plan"),
    },
    Prorate: true,
})
if err != nil {
    panic(err)
}