Set up metered billing for subscriptions

If you’re charging in arrears for a consumable service, you can implement a metered billing setup with a few additional updates to your Paddle integration. This can be implemented in a couple of ways.

Paddle Subscriptions are set to bill a fixed amount at a regular interval, however there are several ways that you as a Seller can modify the next billed amount, either by adding an amount to an existing subscription, or moving a subscription user to a different plan.

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.

Using Subscription Modifiers

Subscription Modifiers either add or subtract a fixed amount from the subscriber’s upcoming bill.

  • 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.
  • Create a new Subscription Modifier to add the value above to the upcoming bill. This can be added through the Create Subscription Modifier API:

curl -X POST -d 'vendor_id=123' \
             -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

Note: the modifer should not be set to recur. The currency of the modifier will be the same currency as used in the current subscription. You should add a description to the modifier to explain the reason for the charge.

  • The subscriber will be charged an additional amount at the start of their next bill.

Using the User Update API

By billing through a different subscription plan, you can bill a variable amount depending on service usage. For this approach, you’ll need to create two Subscription Plans in your dashboard: one for a base amount (or free if you have no base charge) and one for the metered amount.

  • 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.
  • Update the user’s subscription through the Subscription Update API, switching them to the Metered Billing plan and setting the recurring amount to the value above:

curl -X POST \
  -d 'vendor_id=123' \
  -d 'vendor_auth_code=456bd...' \
  -d 'subscription_id=12345' \
  -d 'plan_id=456' \
  -d 'recurring_price=24.60' \
  -d 'currency=USD' \
  -d 'prorate=false' \
  -d 'bill_immediately=false' \
https://vendors.paddle.com/api/2.0/subscription/users/update

Note: the recurring price set in the API call will override any price set for the subscription plan in the dashboard. If the metered billing is on top of a base subscription cost, you’ll need to sum the two values before making the API call.

  • The subscriber will be charged the specified amount at the start of their next bill.
  • After the subscriber is successfully billed, use the same API to move the user back to the original base plan.

curl -X POST \
  -d 'vendor_id=123' \
  -d 'vendor_auth_code=456bd...' \
  -d 'subscription_id=12345' \
  -d 'plan_id=123' \
  -d 'prorate=false' \
https://vendors.paddle.com/api/2.0/subscription/users/update

Sending Billing Notifications

As the billing amount changes in each billing period, we recommended that you enable pre-billing notifications when using Metered Billing.

In your dashboard Vendor Settings, select ‘Subscriptions’. From there you can enable up to two billing notifications before payment is taken. Ensure that the first notification is sent out after the pricing update is made.