Hey! These docs are for version 1.0, which is no longer officially supported. Click here for the latest version, 2.0!

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 to update a given, or all of the associated charges of a subscription.

Using the API

curl -X PUT 
-H 'Content-type: application/json'
-H "Authorization: Bearer Zjc0YjNjMTMtNWIwNi00MGMxLTljMjctMzhiM2EzZmE5NGRk;" 
-d '{ "quantity" : 10, "all" : true }'

https://api.upodi.io/v2/subscriptions/99171702-75b6-4fc0-8311-15ad3fe5948d/setamount/
Guid subscriptionId = Guid.Parse("1dda50ed-514b-48f1-a041-ff305b2a9c77");

// setup client
UpodiService upodi = new UpodiService("aab31984-0256-4d10-afe2-c6a4f35bcf40");
// update all
upodi.Subscriptions.SetAmount(subscriptionId, 10, all: true);

Prorate additions and upgrades

Proration is when a customer has to be billed while only receiving part 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.

Proration is configured on the product plan. If the product plan is not configured to handle changes, which is default - no change will be applied upon switching or setting the amount. Using the API you can omit proration if you can to exclude proration of a given switch plan or update.

Amendments

Proration are normally conducted immediate upon changing the amount of the subscription either via API or via the web application. In some scenarios you might want to allow the prorated invoice to be included in future billings. Setting a product plan to allow proration as amendments, will issue the calculated change on hold, and append this change to any coming billing run. If you wish to pause any billing, setting the customer auto bill to false, will pause any billing and only create draft invoices.

Example:

Subscription has 2 charges starting in January:
C1 = Onetime fee at startup of DKK 300. Subscription amount = 1
C2 = Per unit fee charged monthly of DKK 50. Subscription amount = 50

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

On the 1st of April the subscription charge will charge amount 70.

🚧

For the 'prorate additions and upgrades' to work your subscription charge has to be a recurring charge and not a flat fee.
A subscription charge will only prorate if there is already at least one active billing subscription charge.

Questions?

We're always happy to help with code or other questions you might have! Search our documentation or contact helpdesk. You can also chat live with us using the Intercom icon.