Skip to main content

​
What is Proration?

Proration is the adjustment of charges based on the unused portion of the current billing period when a subscription is upgraded or downgraded.

​
Types of Proration

For both prorate and invoice proration types, the subscription plan always changes immediately, whether the change is an upgrade or a downgrade. The only difference between the two proration types is when the price difference is charged or credited.

​
Invoice Immediately (invoice)

The prorated price difference is charged or credited immediately when the subscription is upgraded or downgraded.

​
Next Invoice (prorate)

The prorated price difference is charged or credited on the next invoice on updgrading or downgrading a subscription.

​
How to change the default proration setting using dashboard

1

Go to Organization Settings

In the Polar dashboard sidebar, click on Settings. You can also go directly to:
https://polar.sh/dashboard/${org_slug}/settings
Scroll down to Subscriptions section.
2

Choose the Proration type

Choose the default proration behavior: Invoice Immediately or Next invoice.The default proration setting is changed successfully.

​
How to change the default proration setting using the OAT API

You can change the default proration behavior using the Update Organization API.

​
How to prorate when updating subscription via API

1

Create an organization Token

Create a new organization token by following our Organization Access Tokens guide.
2

Save your Access Token

After creating your access token, you will be able to view it. Please copy and save your access token.
3

Copy the Subscription ID

  • In the Polar dashboard sidebar, navigate to Sales > Subscriptions for your organization. You can also go directly to:
    https://polar.sh/dashboard/${org_slug}/sales/subscriptions
  • Click on the Subscription you want to upgrade/downgrade and copy its Subscription ID.
4

Copy the Product ID

  • In the Polar dashboard sidebar, navigate to Products > Catalogue for your organization. You can also go directly to:
    https://polar.sh/dashboard/${org_slug}/products
  • Retrieve the Product ID for the item you wish to upgrade the subscription to by clicking on the ⋮ (More options) menu next to chosen products and selecting Copy Product ID.
5

Call the Update Subscription API

Call the Update Subscription API as follows.Make sure to replace:
  • subscription_id with the ID of the subscription you want to update
  • product_id with the new product ID
  • type_of_proration with the desired proration type:
    • invoice: to charge/credit the prorated price difference immediately
    • prorate: to charge/credit the prorated price difference on next invoice
curl --request PATCH \
  --url https://api.polar.sh/v1/subscriptions/{<subscription_id>} \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN_HERE>' \
  --header 'Content-Type: application/json' \
  --data '{
    "product_id": "<product_id>",
    "proration_behavior": "type_of_proration"
  }'

​
Some examples for proration amount calculation

You can create a subscription with two plan options, one for $5 and other for $20 by following Create Product Variants.

​
Case 1: Upgrading the subscription

You can upgrade a subscription by following the steps outlined in Subscription Upgrades, which explains the process from both the merchant’s and the customer’s perspectives. Example 1: Proration type = invoice Assuming that the month when the subscription was purchased has 30 days. In case of 31 days, instead of 30th + 1 day, it would be 31st + 1 day = 32nd day. Example 2: Proration type = prorate Assuming that the month when the subscription was purchased has 30 days. In case of 31 days, instead of 30th + 1 day, it would be 31st + 1 day = 32nd day.
If the billing interval changes, i.e. daily to monthly or monthly to yearly or vice versa, the proration is always applied as invoice (even if set to prorate).

​
Case 2: Downgrading the subscription

You can downgrade a subscription by following the steps outlined in Subscription Downgrades, which explains the process from both the merchant’s and the customer’s perspectives. Example 1: Proration type = invoice Assuming that the month when the subscription was purchased has 30 days. In case of 31 days, instead of 30th + 1 day, it would be 31st + 1 day = 32nd day. Example 2: Proration type = prorate Assuming that the month when the subscription was purchased has 30 days. In case of 31 days, instead of 30th + 1 day, it would be 31st + 1 day = 32nd day.
If the billing interval changes, i.e. daily to monthly or monthly to yearly or vice versa, the proration is always applied as invoice (even if set to prorate).