Handling changes

Updating amounts

As Product Plans and their associated product plan charges are templates for a subscription, updating the amount of a subscription is done on the associated subscription charge. A subscription charge binds the connection between a subscription and the product plan charge, inherited from the product plan upon creating the subscription. See the conceptual model.

A subscription can hold one or many subscription charges based on the design of the given product plan.

You can update the amount of a subscription and it's associated subscription charges by using the Upodi application. You can also use the API endpoints to Update Subscription Charge.

Using the API

curl --request PUT \
     --url https://api-front.upodi.io/SubscriptionCharges/{SubscriptionChargeID} \
     --header 'Authorization: Bearer {ApiKey}' \
     --header 'X-version: {version}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data @- <<EOF
{
  "Prorate": {
    "Action": 2,
    "PricingStrategy": 0
  },
  "Quantity": 5,
  "PreviewMode": false,
  "Description": "You purchased more, you've got to pay"
}
EOF
var changeRequest = new UpdateSubscriptionChargeRequest()
            {
                Quantity = 5,
                Description = "You purchased more, you've got to pay",
                Prorate = new ProrateOptions()
                {
                    Action = ProrationAction.ProrateImmediately,
                    PricingStrategy = ProrationPricingStrategyEnum.RemaningPeriodProration
                }
            };
            var change = await upodi.SubscriptionCharges.UpdateAsync(subscriptionChargeID, changeRequest);

Prorate additions and upgrades

Proration is when a customer has to be billed while only receiving parts of the service. This usually happens when a customer upgrades their subscription to a more expensive plan and therefore receives an extra service only for the remaining part of the billing cycle. Another common case is where the customer mid-term upgrades their subscription and buys even more of your services either by increasing quantity of existing products or adding a new product to the subscription.

In all cases we will ensure the customer does not pay twice for already invoiced quantities. Read more about billing cycles in Subscription charges.

Proration Price Options

When such a change happens you have the option to choose how the price change should be calculated but also how it should be handled afterwards.

Remaining Period Price

This is the typical choice for most businesses as it allows you to receive the calculated price difference that takes the already paid amounts into consideration.

Remaining Period Price Example:

  • Charge with a price of €50 per unit. The customer currently buys 30 pc. billed monthly from the 1st of the month.

On the 12th of March the charge gets updated with the new amount 50. Net new is 20. Since the upgrade to amount was on the 12th of March, an invoice line will be generated only charging the new net of 20 for the remaining 19 days in the billing cycle of 31 days (20 * €50 (31-12 / 31 = 61,3%) = €613.).

The invoice line would be 20 pc. priced €613 for period 12th of March to 31st of March.

Full Price

Regardless of the fact that it's a mid-term purchase bill the product for it's full price. The resulting invoice line will still have the correct period for the purchase.

Full Price Example:

Consider the same setup from above. The calculation would be (20 * €50 = €1000).

The invoice line would be 20 pc. priced €1000 for period 12th of March to 31st of March.

No Proration

You can also choose to not bill the change and just have it bill them on the next renewal. In the examples above there would be no invoice line generated at the time of the change.

Proration Invoice Action

When the invoice contents have been chosen above you also have the option to choose how the invoice should be handled. This means you have different options depending on whether you want the invoice to automatically be booked right now, at a later point or rather want the invoice to be created and allow you to further inspect its contents.

Immediately

The price change and any associated costs are immediately sent as an invoice to the customer. This always comes with the option to choose booking specifics as well.

As Amendment

In some scenarios you might want to have the prorated invoice lines to automatically be included in the next-coming billing of the subscription. This can be if you typically experience many small upgrades throughout the term of the subscription and rather than sending small individual invoices each time you just want to collect them for the next renewal amended to the normal invoice the customer receives.

As Draft

You always have the option to create the change as a draft. Drafts can be inspected, edited and booked manually. Be aware that drafts will never be automatically booked and needs manual attention.


What’s Next

See Types of charges to learn more about the different types of Product Plan Charges you can create on your Product Plan.