Metered Billing for Subscriptions

If you’re charging in arrears for a consumable service, you can implement a metered billing setup for subscriptions with Paddle in a couple of ways.

To implement metered billing, you will need to calculate the amount due on your own platform. For customer transparency, you should calculate the value of the service consumed a few days ahead of the billing date and distribute a billing notification so that your subscribers are aware of the upcoming charge.

Paddle Subscriptions are set to bill a fixed amount at a regular interval, however there are a couple of ways that you as a Seller can charge in arrears: either by adding an amount to an existing subscription, or by making a one-time charge with the required amount.

You can use either of the following approaches for metered billing:

Using the Charges API

The Charges API allows you to make an immediate charge on top of an existing subscription. To use this approach:

  1. At a fixed time before the next billing date, calculate the value of the consumed service. You can retrieve the next billing date via the List Users API.
  2. On the billing date, call the Charges API with amount that you would like to charge.

The buyer will be charged the amount right away. This is not a recurring charge so you will need to perform the same steps for the next billing cycle.

curl -X POST -d 'vendor_id=1234567' \
             -d 'vendor_auth_code=1a54229abfcfa...' \
             -d 'subscription_id=12345' \
             -d 'amount=10.00' \
             -d 'charge_name=Plan Add-on Charge' \
https://vendors.paddle.com/api/2.0/subscription/{subscription_id}/charge

When a subscription has been successfully charged, this will trigger a Subscription Payment Succeeded alert.

Using Subscription Price Modifiers

Subscription Price Modifiers either add (or subtract) a fixed amount from the subscriber’s upcoming bill. To use this approach:

  1. At a fixed time before the next billing date, calculate the value of the consumed service. You can retrieve the next billing date via the List Users API.
  2. Create a new Price Modifier to add the value above to the upcoming bill. This can be added through the Create Modifier API.
  3. The subscriber will be charged an additional amount at the start of their next bill.

The currency of the modifier will be the same currency as used in the current subscription. We recommend that you add a clear description for the modifier to explain the reason for the charge.

curl -X POST -d 'vendor_id=1234567' \
             -d 'vendor_auth_code=1a54229abfcfa...' \
             -d 'subscription_id=12345' \
             -d 'modifier_recurring=false' \
             -d 'modifier_amount=10.00' \
             -d 'modifier_description=Example%20Description' \
https://vendors.paddle.com/api/2.0/subscription/modifiers/create

The modifier should not be set to recur if it is a one-time bill.

When a modifier is successfully added using the Create Modifier API, a modifier_id is returned from it. You should store this ID in case you wish to remove the modifier from the subscription at some point in the future. Alternatively, you can also retrieve the modifier ID by passing in the subscription_id to the List Modifiers API.

If you wish to remove a modifier, you can do so through the Delete Modifier API.

Sending Billing Notifications

As the billing amount changes in each billing period, we recommended that you enable pre-billing notifications when using subscription price modifiers for metered billing.

In your dashboard, go to the Recover Settings page. Under the ‘Pre-billing Notifications’ section, you can enable up to two billing notification emails to be sent to customers before payment is taken. Ensure that the first notification is sent out after the pricing update is made.