The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Usage-Based Billing

Transactional businesses can better align price with value by implementing a usage-based billing model. Send Recurly your customer usage and we will automatically bill them in arrears at the end of the billing cycle. Perfect for companies looking for a pay-as-you-go strategy or including a set quantity and charging for overage.

Feature Overview

  • Define usage-based products in your Recurly Admin Console as Usage-Based Add-ons
  • Create plans that are only usage-based or a mix of usage-based and additional add-ons
  • Send customer usage to Recurly via our APIs and let Recurly handle all the billing calculations*
  • Leverage Quantity-Based Pricing models to offer subscribers flexible pay-as-you-go offerings
  • Show customers their current unbilled usage or report on customer usage at the customer, add-on, plan, or measured unit level
  • Finance teams can report on revenue earned before it is billed by exporting usage data for the period they want to close

If you're a developer getting started with Usage Billing, see a full overview in our V3 Developer Guide

Create a Usage-Based Plan

To create a usage-based plan, you can create a new plan, or edit an existing plan. Add-ons are separated into Add Ons and Usage-Based Add Ons.

  • Add-ons are charged at the beginning of the billing cycle before the product or service has been provided.
  • Usage-based add-ons charge at the end of the billing cycle after the product or service has been provided. All usage is logged using the Usage API
New Plan Page - Add-On Choices

New Plan Page - Add-On Choices

You can create a plan with any mix of Usage Based Add-Ons, Item Add-Ons, and Add-Ons. Recurly always requires a plan fee, the "recurring charge", but you can always set that to 0 if you want a strictly usage plan.

USAGE-BASED ADD-ONS

Attribute
Example
Description

Add-On Name

Video Streaming

The name of your add-on, seen on the Hosted Payment Page and invoice line item

Add-On Code

video_streaming

The product code for your add-on, seen in exports and used in the API

Accounting Code

VS1000239

Optional accounting code to help your finance team account for the revenue in the right ledger

Tax Type / Tax Code

"Digital Product" or "D0000000"

Those collecting EU VAT or using the AvaTax integration can define their usage product for appropriate taxation

Charge Model

"Price per Unit" or "Percentage of an Amount"

Whether you want to define a price or percentage. Once you set a model, you cannot change it on the Edit Plan page. You will need to remove the add-on and add a new one.

Measured Unit

Bandwidth (GB)

The unit of measure. Provides a display for the Hosted Payment Page pricing and allows you to track the same unit type across multiple add-ons and plans.

Pricing Model (Tier Type)

Fixed, Tiered, Volume, Stairstep

The pricing model to use for charges. For more info, click here.

Referred to as Tier Type in developer docs and cannot be used when Charge Model is Percentage.

Price

$0.50 USD, €0.45 EUR

The price per unit charged. This can be up to 2 decimal places.

Tiers

An array of tiers and prices to be used in combination with the Tier Type

The tiers and currencies that are used to charge for the usage logged.

Percentage

2.36%

The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. Percentage does not support Tiers.

Make this add-on optional to the customer

Boolean checkbox

Whether the add-on is optional to the customer on the Hosted Payment Page. Usage-based add-ons default to required.

MEASURED UNITS

Measured units provide a description of the usage measured for a usage-based add-on and allow you to track and report on the same type of usage across multiple add-ons and plans.

  • You can create a measured unit when creating a usage-based add-on in a plan, or you can visit the "Measured Units" page under the Configuration section of your Admin Console. Measured Units can also be managed from the API.
  • Any edit to the measured unit will update your plan and any subscriptions immediately.
  • You can only delete a measured unit if it is not being used in a plan. Remove the measured unit from all plans before you delete it on the Measured Units page.
Create a Measured Unit when Creating an Add-on

Create a Measured Unit when Creating an Add-on

Create, View, Edit and Delete Measured Units from the Measured Units Page

Create, View, Edit and Delete Measured Units from the Measured Units Page

Create a Usage-Based Subscription

Methods

You can subscribe customers to your usage-based plans through the API, Hosted Payment Paged, or Admin Console. All API and Recurly.js details are mentioned in API Integrations lower on this page. Here are details specific to usage-based plans for the Hosted Pages and Admin Console.

HOSTED PAYMENT PAGES

  • Usage-based add-ons will automatically show up on your Hosted Payment Page for the plan, but their cost will not be included in the Order Total because all usage fees are charged at the end of the billing cycle.
  • The price and measured unit display name are displayed for fixed price usage-based add-on to the right of the add-on name in parenthesis. Tiered, Volume, and Stairstep usage based add-ons will not have the prices displayed on hosted payment pages given pricing can vary based on the usage logged.
  • Add-ons selected as optional on the plan will have checkboxes on the Hosted Payment Page. Required add-ons will not have checkboxes and will show up above the optional add-ons.
Example Hosted Payment Page for a Usage-Based Plan

Example Hosted Payment Page for a Usage-Based Plan

ADMIN CONSOLE

  • Select your usage-based plan on the New Subscription page and you will see the associated usage-based add-ons appear.
  • Required add-ons will be included, checked, by default, but you can always uncheck them.
  • You can enter in a custom price or percentage any of the add-ons.
  • For Quantity-Based add-ons, both tiers and prices can be custom for the subscription by clicking Edit Tiers. The pricing model cannot be changed. Create a new add on on the plan if you want to use a different pricing model.
New Subscription with Usage-Based Add-Ons and Add-ons

New Subscription with Usage-Based Add-Ons and Add-ons

First Invoice

When a subscription starts, there are three possible first invoice experiences depending on the state of the subscription.

ACTIVE SUBSCRIPTION

If your plan does not include a trial and the subscription starts immediately, the customer will see an invoice that does not include their usage-based add-ons.

  • Because we bill usage in arrears, it would be inaccurate to show the usage-based add-ons on the invoice with dates in the past, before the subscription or usage-based add-on existed.
  • Usage-based add-ons will be included on all other invoices moving forward, even if usage is 0.
  • The New Subscription email template will mention usage-based pricing in the plan information section so that customers can be assured they did purchase usage-based add-ons, they just aren't billed for them initially. You can reset the New Subscription email template to get this update, or review our add-on email parameters to create your own display.
  • Additionally, our Hosted Account Management and API can be used to show customers their current plan, included add-ons, and current unbilled usage.
Example First Invoice without Usage-Based Add-ons

Example First Invoice without Usage-Based Add-ons

TRIAL SUBSCRIPTION

Subscriptions that start with a trial period always create a trial invoice at sign-up. Usage-based add-ons are included on trial invoices to market to your potential customer that they are trialing a usage-based product.

  • Usage-based add-on line items will show the trial period dates, which are forward looking.
  • Usage can be logged while in trial and displayed to your customer, but that usage will not be included on their first payment invoice at the end of the trial.
  • The first payment invoice after the trial will match the first invoice of the active subscription mentioned above.
Example Trial Invoice with Usage-Based Add-ons

Example Trial Invoice with Usage-Based Add-ons

FUTURE SUBSCRIPTION

If you are starting a subscription for a date in the future, you won't have an invoice until the subscription starts. In most cases the first invoice will match the active subscription example above and will not show usage-based add-ons.

If you need to transition a customer's billing from a different system into Recurly, and you want to include usage on the first invoice because it is not a first invoice to the customer, you can do so by creating a future subscription and logging usage between the creation date and the future start date.

  • Usage logged between subscription creation and start will appear on the invoice like a normal invoice for a new billing period.
  • The line item dates will reflect the creation to start, so if you want to align the dates with your other system, we suggest a lazy migration where at the next bill date in the other system, you create the future subscription in Recurly with a future start date of the next bill date. Then start logging usage to Recurly and stop logging usage to the other system. Set the subscription in the other system to expire at its bill date and not send a final bill.
  • We do not allow you to log usage for a date before the usage-based add-on existed on the subscription.
  • Future usage subscriptions should not include trials given the differences in how future and trial usage is billed.

Manage Usage for Subscriptions

HOW TO LOG USAGE

All usage is logged through our Usage API. Usage cannot be logged using the Admin Console.

  • Usage amounts cannot include any decimal places
  • For percentage of an amount usage-based add-ons, usage will be logged "in cents", which we will convert to a proper currency display depending on the currency of the subscription. For example, if send "500" for a subscription in USD, we will format that as $5.00 USD.
  • Usage amounts can be positive or negative. See our section on Usage Corrections below.
  • Each usage record has an optional custom field called "merchant_tag" where you can store the usage event's ID in your own system, or whatever you like. Storing your own ID will allow you to use our API to provide auditable statements to your customers through your own UI.

WHEN TO LOG USAGE

We recommend setting up your integration to send Recurly usage in real-time, or aggregated into hourly or daily records based on what works best with your systems. The closer to real-time you get with logging your usage, the cleaner your invoices will look. We do not rate limit our Usage API endpoints in order to support real-time usage logging.

Each subscription bill date, immediate change, or expiration will generate an invoice and bill any unbilled usage. If you are logging usage later in the day for a past usage date in the billing cycle that was billed earlier that morning, the new usage will not be included in the bill date invoice. Instead we will pick up the unbilled usage on the next invoice.

EDIT USAGE

If you make a mistake, you can edit your customer's usage records if the usage has not yet been billed. Otherwise you need to consider issuing a refund, credit, or creating a Usage Correction. Once the usage is billed, you can only edit the merchant_tag field.

DELETE USAGE

You can delete a usage record if the usage has not yet been billed. Once the usage is billed, you can only issue a refund or create a Usage Correction.

USAGE CORRECTIONS

Usage corrections are just new usage records that are logged for a usage date in a past, already billed, billing cycle. These new unbilled usage records will get picked up by the next subscription invoice. We recommend issuing refunds or adding a one time charge over corrections.

  • Usage corrections appear on the invoice grouped by billing cycle. If you have multiple positive and negative corrections from the same past billing cycle, you will see the net sum on the invoice line item.
  • If the net sum of a correction line item is positive, it will be a charge. If the result is negative, we will treat the line item as a credit.
  • If you are programmatically logging usage at set times that are after some of your customer's subscription bill dates, you will consistently see usage corrections showing up on those invoices.
  • Usage corrections will not pick up any coupon discounts on an invoice, they are not discountable. See DISCOUNTS ON USAGE-BASED ADD-ONS to learn more.
  • Usage corrections will not be accepted if the Pricing Model/Tier Type is Tiered, Volume, or Stairstep. Use Line Item Refunds or create a new charge for corrections.

Change a Usage-Based Subscription

When you change a subscription with usage-based add-ons, we will always charge for any unbilled usage at the old state of the subscription. Note that usage-based add-ons never prorate. Only line items that represent fees paid up front will be prorated in an immediate change. Since usage-based add-ons charge at the end of the billing cycle, proration never applies.

  • Add a usage-based add-on: You will not see the new add-on on the change invoice. You will see it show up on the next bill date. Since usage-based add-ons never show on the first invoice where they exist for the subscription, and Recurly always creates an invoice for a subscription change, you could get in a scenario where the change invoice nets to 0 because the rest of the subscription didn't change.
  • Remove a usage-based add-on: You will see the add-on on the change invoice with any unbilled usage.
  • Change a usage-based add-on price or percentage: You will see the add-on on the change invoice with any unbilled usage charged at the old price or percentage. From that moment on, new usage will be recorded at the new price or percentage. You will see the price and percentage change on the following bill date.
  • Change plans that both have usage-base add-ons: If you are changing the subscription's plan and both the old and the new plan have usage-based add-ons, you will see the equivalent of removing the old usage-based add-on and adding the new usage-based add-on. This means the old plan's usage-based add-ons will show up on the invoice and bill for any unbilled usage. The new plan's usage-based add-ons will not show on the change invoice because no usage has been logged yet. The next bill date's invoice after the change invoice will start showing usage for the new plan's usage-based add-ons.

Cancel or Terminate a Usage-Based Subscription

Subscriptions with usage-based add-ons that expire will always issue a final invoice with only the usage-based add-ons. Even if usage is 0, we will send a final invoice.

If there is positive usage for the current cycle, you have the option to zero-out the usage. This is useful if you have an upset customer and you don't want to collect on their final usage. If you choose to not charge for current usage, we will create a negative usage record that zeros out the resulting line item on the invoice. We will also send you a new_usage_notification webhook so you can update your own usage records.

  • Note: If you have Usage Corrections at the time of terminating, we will not zero those out for you and they will be charged on the invoice.

When refunding in a terminate action, we filter out usage-based fees from the previous invoice in the refund total, as those reflect the previous billing cycle, not money paid for the current billing cycle where products or services may not have been received.

Refund a Usage-Based Invoice

To refund a usage-based add-on, go through our normal refund flows, but we recommend using our Line Item Refunds instead of our Open (Specific) Amount Refunds.

  • When doing a line item refund, we will create a negative usage record for the usage-based add-on for the usage amount you are refunding. This usage record will get marked as billed immediately in the refund and we will issue a new_usage_notification webhook to let you know what usage record was created in case you want to update your own records. The new usage record will have a usage_timestamp of the last second of the refunded line items date range.
  • Fixed price per unit usage-based add-ons allow you to refund all or a specific quantity (usage) amount.
  • Quantity-Based usage-based add-ons can only be refunded using Line Item Refunds. Open amount refunds are not allowed.
  • Percentage of an amount usage-based add-ons can only be fully refunded. If you want to do a partial refund, we recommend using our Usage Corrections, or doing an Open Amount Refund and accounting for the usage record change on your own.
  • If Recurly creates usage on your behalf in a refund , you will receive a new_usage_notification.

Discounts on Usage-Based Add-ons

Discounts are applied to usage-based add-ons the same way as add-ons, except any usage correction line items will not be discountable.

EXAMPLE

Given

  • "All Plans" coupon redemption for 10% off currently active on the account
  • Customer is currently subscribed to a plan that is $5.00/month and $0.02/email/month
  • Merchant logged a usage correction to charge the customer for 3 emails that were incorrectly left out of last month's invoice
  • Customer used 15 emails this month

The next invoice would show

  • Charge for $5.00 with a 10% discount
  • Charge for 15 emails at $0.02/email with a 10% discount
  • Charge for 3 emails at $0.02/email (no discount)

We do not discount usage correction line items because they represent a period in the past that may or may not have had an active discount at that time, so we do not want to assume they receive the current period's discount. We always recommend refunding a usage line item if you need to credit usage before you consider logging a usage correction through the API. Refunds will properly include any discounts included at the time the usage billing cycle was invoiced. Unfortunately, if you need to charge a usage correction from a past billing cycle, this can only be done through the API and will not pick up any discounts on invoice that bills the correction.

LIMITED TIME DURATION

Since usage-based add-ons are billed in arrears, it is important to understand that limited time duration coupons will not discount the usage-based add-on fees from the final period of the coupon redemption duration.

EXAMPLE 1 - One Month Coupon

Given

  • Coupon has a duration of 1 month and is for 10% off of all plans
  • Plan is $5.00/month and $0.02/email/month
  • Customer subscribes and redeems the coupon at the time of sign-up

The invoice discounts will follow as

  • First invoice will discount the plan fee only, since usage add-ons are not billed on the first invoice
  • The coupon redemption will expire right before the first bill date.
  • The invoice will not discount the plan fee or usage add-on, since the coupon redemption has expired

EXAMPLE 1 - Two Month Coupon

Given

  • Coupon has a duration of 2 months and is for 10% off of all plans
  • Plan is $5.00/month and $0.02/email/month
  • Customer subscribes and redeems the coupon at the time of sign-up

The invoice discounts will follow as

  • First invoice will discount the plan fee only, since usage add-ons are not billed on the first invoice
  • The second invoice, which is the first bill date, will discount the plan fee and the usage add-on fee
  • The coupon redemption will expire right before the third invoice, which is the second bill date
  • The third invoice will not discount the plan fee or usage add-on, since the coupon redemption has expired

COUPONS FOR FREE UNITS

If you want to have an included quantity where the first X units are free, use a Tiered pricing model and set the first tier to a $0 per unit. Then create another tier with the charge for each additional unit. If you still want to use coupons, coupons can be a fixed amount or percentage off of the usage add-on subtotal.

API Integrations

Usage API and Client Libraries

In our API, all functionality for the Usage feature and Quantity-based pricing is on version 2019-10-10 and above. Here is a link to the docs and a link to our Developer Guide.

  • Ruby Client version is 3.10.0
  • Node Client version is 3.11.0
  • Python Client version is 3.9.0
  • Dotnet Client version is 3.11.0
  • Go Client version is 3.5.0
  • Java Client version is 3.10.0
  • PHP Client version is 3.5.0

For sites using our older v2 API, functionality for creating Usage Add Ons is on version 2.2 and Quantity Based Pricing is version 2.26 and above.

However, we recommend always updating to the latest version of the API so that you have the most up-to-date functionality.

USAGE-BASED ADD-ONS IN PLANS

You can use the Plan Add-On API resource to create usage-based add-ons. Read our API documentation on <a href=https://developers.recurly.com/api/v2019-10-10/index.html#operation/create_plan_add_on" target="_blank">Plan Add-Ons.

USAGE-BASED ADD-ONS IN SUBSCRIPTIONS

You can use the Subscription Add-On API resource to create usage-based add-ons in a subscription. Read our API documentation on Subscription Add-Ons.

  • Set custom prices for your subscription add-ons by using the normal amount attribute for "price per unit" add-ons and the new usage_percentage attribute for "percentage of an amount" add-ons.
  • Usage-based add-ons can only have a quantity of 1. The custom purchases 1 quantity of the product, but is billed by measuring the units of usage, which can vary.

RECURLY.JS

Recurly.js version 4.0.5 pricing supports usage-based billing. Use Recurly.js to display the add-on price or percentage. Since usage-based fees are not billed up front and cannot be estimated for a next bill date, these add-on prices will not be included in the "_now" or "_next" pricing amounts.

WEBHOOKS

Our webhooks will include additional attributes about usage-based add-ons. This may break your integration, so be sure to update it accordingly. The webhooks include:

  • new_subscription_notification
  • renewed_subscription_notification
  • updated_subscription_notification
  • canceled_subscription_notification
  • reactivated_account
  • expired_subscription_notification

Reports and Exports

REPORTS

  • Your transactions report will reflect your usage-based add-on revenue, just like any other plan or add-on.
  • Your MRR report will not include usage-based add-on revenue as variable fees are traditionally not included in MRR.
  • There are not additional reports specific to usage-based add-ons at this time.

EXPORTS

For easy analysis, you can pull information about usage add-ons and usage records from our Exports.

Subscriptions Add Ons Export is version 2
Subscriptions Usage Export is version 2

You will see an export called "Subscriptions Usage Records" that will export the individual usage records logged for your customer's usage-based subscription add-ons. This export is useful for your finance team trying to report on revenue earned before it is billed, as well as your product and marketing teams who may want to analyze customer usage.

For revenue recognition, be aware that the pricing information in this export is the customer's price and does not reflect any discounts factored in at the invoice level. Please review the Invoices - Line Items export for any discounts.

QUANTITY-BASED PRICING AND EXPORTS

The exports will include the tier_type but will not include detailed tiers pricing information. Merchants can use the invoice line items for aggregate totals of the logged usage. If you need access to specific tiers for a plan, subscription, or usage record we recommend using the API responses.

Email Template Updates

These email templates have full support for usage-based add-ons:

  • New Subscription
  • New Invoice
  • Invoice Past Due
  • Subscription Change
  • Subscription Canceled
  • Payment Confirmation
  • Payment Declined

The invoices in the body has it's own quantity (Qty) column, the subscription pricing displays to reflect additional usage-based add-on fees. If you have customized these templates, you can reset them to see the changes, or update your customized version to include our new add-on email parameters. For quantity-based pricing models, we do not recommend displaying an add_on_price, we recommend displaying the total price for the line item on the New Invoice.

{#subscription_add_ons}}
  {{#add_on_usage_based?}}
    add_on_name: {{{add_on_name}}}<br />
    add_on_price: {{{add_on_price}}}<br />
    add_on_measured_unit_display_name: {{{add_on_measured_unit_display_name}}}<br />
 {{/add_on_usage_based?}}
{{/subscription_add_ons}}

Updated 13 days ago

Usage-Based Billing


Transactional businesses can better align price with value by implementing a usage-based billing model. Send Recurly your customer usage and we will automatically bill them in arrears at the end of the billing cycle. Perfect for companies looking for a pay-as-you-go strategy or including a set quantity and charging for overage.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.