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 units and we will automatically bill them in arrears at the end of the billing cycle.

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 fixed-price fees
  • Send customer usage to Recurly and let Recurly handle all the billing calculations
  • 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

Create a Usage-Based Plan

To create a usage-based plan, you can create usage-based add-ons within your plan. Add-ons are now separated into Fixed-Price and Usage-Based.

  • Fixed-price add-ons charge a set amount up front each billing cycle.
  • Usage-based add-ons charge a variable amount at the end of each billing cycle dependent on usage measured over the past billing cycle.
New Plan Page - Add-On Choices

New Plan Page - Add-On Choices

You can create a plan with only usage-based add-ons, or any mix of usage-based and fixed-price 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

Pricing Model

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

Whether you want to define a price or percentage. Once you set a pricing 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.

Price

$0.50 USD, €0.45 EUR

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

Percentage

2.36%

The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places.

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.

Example Usage-Based Add-On on the New Plan Page

Example Usage-Based Add-On on the New Plan Page

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.
  • 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 our normal methods. All API and Recurly.js details are mentioned in Integration Updates at the bottom of this page. Here are details specific to usage-based plans for our other methods.

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 each usage-based add-on to the right of the add-on name in parenthesis.
  • Add-ons, fixed-price or usage-based, 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.
New Subscription with Usage-Based and Fixed Price Add-ons

New Subscription with Usage-Based and Fixed Price 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.
  • We have updated our New Subscription email template to mention usage-based pricing in the plan information section so that customers can be assured they did purchased usage-based add-ons, they just aren't billed for them initially. Please reset your 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 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 it's 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.

Manage Usage for Subscriptions

HOW TO LOG USAGE

All usage is logged through our Usage API. If you would like to be able to enter usage for a customer through the UI, please contact Recurly Support and we will add you to the feature request.

  • 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 hourly batches. 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. The closer to real-time you get with logging your usage, the cleaner your invoices will look.

EDIT USAGE

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

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 over corrections, but if you need to charge for a past cycle, usage corrections are what you will need to use.

  • 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.

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 an 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 an usage-based add-on: You will see the add-on on the change invoice with any unbilled usage.
  • Change an 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.
  • Price per unit usage-based add-ons allow you to refund all or a specific quantity (usage) amount.
  • 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.

Discounts on Usage-Based Add-ons

Discounts are applied to usage-based add-ons just like they are applied to fixed-price add-ons today, 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

We do not currently support the creation of coupons that discount a number of units on the invoice. Coupons can be a fixed amount or percentage off of the usage add-on subtotal. If you would like to create a coupon for a number of free units, please contact Recurly Support and we will add you to the feature request.

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

SUBSCRIPTIONS ADD-ONS

The Subscriptions Add-Ons export will now include these additional columns:

Column
Example
Description

account_code

239485723046981734

The account code of the customer whose subscription add-on this is

add_on_name

Video Streaming

The add-on name

add_on_type

fixed, usage

Whether the add-on is fixed-price or usage-based. If the add-on is usage-based, you will want to pull the Subscriptions Usage Records export to see the customer's usage.

subscription_currency

USD

The currency of the subscription, which is the currency of the subscription_add_on_unit_amount_in_cents

subscription_add_on_percentage

4.5

The percentage of the subscription add-on if the add-on is usage-based

measured_unit_internal_name

Bandwidth Units

The internal name of the associated measured unit, if the add-on is usage-based

measured_unit_display_name

GB

The display name of the associated measured unit, if the add-on is usage-based. Note this does not describe the subscription_add_on_quantity, which will always be 1 for usage-based add-ons. This display name describes the usage found in the Subscriptions Usage Records export.

SUBSCRIPTIONS USAGE RECORDS

You will see a new 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.

You can filter the export by:

Filter
Description

Plan

Export usage records for all plans with usage-based add-ons or filter down to a specific plan's usage-based add-ons

Usage-Based Add-On

If a specific plan is selected, you can export all the associated usage-based add-on usage records, or filter down to a specific usage-based add-on in the plan

Created

Pull the date range based on when the usage record was created in Recurly

Modified

Pull the date range based on when the usage record was updated in Recurly. This could be when the usage record was billed, or if you did an update through the API before it was billed.

Usage Timestamp

Pull the date range based on the usage record's usage_timestamp. Use this option if you want to know what was used in a period, regardless of whether or not it has been billed yet.

Recording Timestamp

Pull the date range based on when the usage record was recorded in your own system

Billed

Pull the date range based on when the usage record was billed

Included Columns:

Column
Example
Description

usage_id

400527199884543703

The unique id of the usage record

account_code

239485723046981734

The account code of the customer whose usage record this is

subscription_id

3598f5c395fc7e2f4a4eaa4888b9784b

The subscription id for the usage-based add-on this usage record is for

plan_code

mega_video

The plan code of the associated subscription

add_on_code

video_streaming

The add-on code of the usage record's subscription add-on

subscription_currency

USD

The currency of the subscription, which is also the currency of the unit_amount_in_cents for the add-on

usage_type

price, percentage

Whether the usage-based add-on has a pricing model of "price per unit" or "percentage of an amount"

unit_amount_in_cents

60

If the usage-based add-on has a usage_type of "price", it will have a unit_amount_in_cents, which is the price per each usage amount. In the example, 60 is equivalent to $0.60 USD.

usage_percentage

4.5

If the usage-based add-on has a usage_type of "percentage", it will have a usage_percentage, which is the percentage of the monetary amount charged.

measured_unit_internal_name

Bandwith Streaming

The internal name of the associated measured unit

measured_unit_display_name

GB

The display name of the associated measured unit. This describes the amount column value.

amount

5

The units used. If the usage_type is percentage, this amount is stored as the monetary amount in cents. For example, $5.00 USD would be stored as "500".

merchant_tag

"Rate Lookup ID: 45768456845683435"

The merchant tag for the usage record, which is a custom field where you can store whatever you like.

usage_timestamp

2016-04-18 17:00:08 UTC

The usage timestamp, which is when the units were used. This maps to the line item date range on the invoice when the usage is billed and is important for revenue recognition.

recording_timestamp

2016-04-18 17:00:08 UTC

The recording timestamp, which is when the usage was recorded in your own system. This field will default to match the usage timestamp if a different timestamp is not specified.

created_at

2016-04-18 17:00:08 UTC

When the usage record was created in Recurly

modified_at

2016-04-18 17:00:08 UTC

When the usage record was updated in Recurly. This could be when the usage record was billed or if an update was made before the usage record was billed.

billed_at

2016-04-18 17:00:08 UTC

When the usage record was billed on an invoice.

Email Template Updates

We have updated these email templates to better support usage-based add-ons:

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

We updated the invoices in the body to have it's own quantity (Qty) column, and updated 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.

{#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}}

Integration Updates

VERSIONING

New attributes and resources for this feature are versioned on 2.2. Please use the header X-Api-Version: 2.2

CLIENT LIBRARIES

If you use one of the Recurly client libraries, you will need to update your version. Let us know which one you are using so we can make sure we are prioritizing the right ones.

RECURLY.JS

Recurly.js version 4.0.5 pricing now 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.

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 Plan Add-Ons.

New Attributes
Value
Description

add_on_type

fixed, usage

Whether the add-on is Fixed-Price, or Usage-Based. Will show for all add-ons. Cannot be updated.

measured_unit_id

String

The id of the measured unit on your site associated with the add-on. Returns as a measured unit url resource. Only allowed and shown for usage-based add-ons.

optional

Boolean

Defaults to true. Whether the add-on is optional for the customer to include in their purchase on the hosted payment page. Will show for all add-ons.

usage_type

price, percentage

If add_on_type = usage, you must set a usage_type, which can be "price" or "percentage". If price, the price is defined in unit_amount_in_cents. If percentage, the percentage is defined in usage_percentage. Only shown for usage-based add-ons. Cannot be updated.

usage_percentage

String

If add_on_type = usage and usage_type = percentage, you must set a usage_percentage. Must be between 0.0000 and 100.0000. Only shown for usage-based 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 unit_amount_in_cents 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.
  • Successful responses will include new attributes and resources. See example below.
<?xml version="1.0" encoding="UTF-8"?>
<subscription href="https://yoursubdomain.recurly.com/v2/subscriptions/35c97fdbfc5b37bb852b5b4abe8f77f2">
    <account href="https://yoursubdomain.recurly.com/v2/accounts/95387347"/>
    <invoice href="https://yoursubdomain.recurly.com/v2/invoices/29272"/>
    <plan href="https://yoursubdomain.recurly.com/v2/plans/mega_video_solution">
        <plan_code>mega_video_solution</plan_code>
        <name>Mega Video Solution</name> 
    </plan>
    <uuid>35c97fdbfc5b37bb852b5b4abe8f77f2</uuid>
    <state>active</state>
    <unit_amount_in_cents type="integer">9999</unit_amount_in_cents>
    <currency>USD</currency>
    <quantity type="integer">1</quantity>
    <activated_at type="datetime">2016-04-28T02:31:06Z</activated_at>
    <canceled_at nil="nil"></canceled_at>
    <expires_at nil="nil"></expires_at>
    <total_billing_cycles nil="nil"></total_billing_cycles>
    <remaining_billing_cycles nil="nil"></remaining_billing_cycles>
    <current_period_started_at type="datetime">2016-04-28T02:31:06Z</current_period_started_at>
    <current_period_ends_at type="datetime">2016-05-28T02:31:06Z</current_period_ends_at>
    <trial_started_at nil="nil"></trial_started_at>
    <trial_ends_at nil="nil"></trial_ends_at>
    <terms_and_conditions nil="nil"></terms_and_conditions>
    <customer_notes nil="nil"></customer_notes>
    <po_number nil="nil"></po_number>
    <net_terms type="integer">0</net_terms>
    <collection_method>automatic</collection_method>
    <subscription_add_ons type="array">
        <subscription_add_on>
            <add_on_type>usage</add_on_type>
            <measured_unit href="https://yoursubdomain.recurly.com/v2/measured_units/393517158711166026"/>
            <usage href="https://yoursubdomain.recurly.com/v2/subscriptions/35c97fdbfc5b37bb852b5b4abe8f77f2/add_ons/sales/usage"/>
            <unit_amount_in_cents nil="nil"></unit_amount_in_cents>
            <add_on_code>sales</add_on_code>
            <quantity type="integer">1</quantity>
            <usage_type>percentage</usage_type>
            <usage_percentage type="float">4.5</usage_percentage>
        </subscription_add_on>
        <subscription_add_on>
            <add_on_type>usage</add_on_type>
            <measured_unit href="https://yoursubdomain.recurly.com/v2/measured_units/278"/>
            <usage href="https://yoursubdomain.recurly.com/v2/subscriptions/35c97fdbfc5b37bb852b5b4abe8f77f2/add_ons/storage/usage"/>
            <add_on_code>storage</add_on_code>
            <unit_amount_in_cents type="integer">50</unit_amount_in_cents>
            <quantity type="integer">1</quantity>
            <usage_type>price</usage_type>
            <usage_percentage nil="nil"></usage_percentage>
        </subscription_add_on>
        <subscription_add_on>
            <add_on_type>usage</add_on_type>
            <measured_unit href="https://yoursubdomain.recurly.com/v2/measured_units/7817"/>
            <usage href="https://yoursubdomain.recurly.com/v2/subscriptions/35c97fdbfc5b37bb852b5b4abe8f77f2/add_ons/streaming/usage"/>
            <add_on_code>streaming</add_on_code>
            <unit_amount_in_cents type="integer">30</unit_amount_in_cents>
            <quantity type="integer">1</quantity>
            <usage_type>price</usage_type>
            <usage_percentage nil="nil"></usage_percentage>
        </subscription_add_on>
        <subscription_add_on>
            <add_on_type>fixed</add_on_type>
            <add_on_code>support</add_on_code>
            <unit_amount_in_cents type="integer">15000</unit_amount_in_cents>
            <quantity type="integer">1</quantity>
        </subscription_add_on>
    </subscription_add_ons>
    <a name="cancel" href="https://yoursubdomain.recurly.com/v2/subscriptions/35c97fdbfc5b37bb852b5b4abe8f77f2/cancel" method="put"/>
    <a name="terminate" href="https://yoursubdomain.recurly.com/v2/subscriptions/35c97fdbfc5b37bb852b5b4abe8f77f2/terminate" method="put"/>
    <a name="postpone" href="https://yoursubdomain.recurly.com/v2/subscriptions/35c97fdbfc5b37bb852b5b4abe8f77f2/postpone" method="put"/>
    <a name="notes" href="https://yoursubdomain.recurly.com/v2/subscriptions/35c97fdbfc5b37bb852b5b4abe8f77f2/notes" method="put"/>
</subscription>

TERMINATE SUBSCRIPTIONS WITH USAGE-BASED ADD-ONS

Customers will automatically get a final invoice for usage-based add-ons, even is usage is 0. When terminating a subscription early, If there is unbilled current billing cycle usage, you have the option to zero-out the usage to create 0 usage on the final invoice.

This is just a new "charge" boolean on the Terminate Subscription API call that is true by default and false to zero-out unbilled usage. Use this in the endpoint url like you do for refunds.

LOG USAGE

Once a customer subscribes, you can log usage to their add-on through the API. Read our API documentation on Subscription Usage Records.

  • Log usage in real-time and leverage Recurly as your source of usage truth for billing. These endpoints are not rate limited.
  • Query on customer usage to show customers their current unbilled usage, a specific date range or a full history.
  • Set custom data on your usage records with the merchant_tag attribute to use Recurly for a customer facing auditable display.
  • Mistakes happen, see our options for updates, deleting, and creating new records that counteract billed ones.

WEBHOOKS / PUSH NOTIFICATIONS

May Require Integration Update

Due to new attributes in our subscription webhooks, creating subscription add-ons on your site with the usage-based billing feature enabled may break your existing integration. Review the examples below to see the new schema.

Our subscription webhooks will now 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
<?xml version="1.0" encoding="UTF-8"?>
<new_subscription_notification>
  <account>
    <account_code>923845792374</account_code>
    <username></username>
    <email></email>
    <first_name></first_name>
    <last_name></last_name>
    <company_name></company_name>
  </account>
  <subscription>
    <plan>
      <plan_code>gold</plan_code>
      <name>Gold</name>
    </plan>
    <uuid>35cda8d4ae0a214f69779e4ddbbc2ebd</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">800</total_amount_in_cents>
    <subscription_add_ons type="array">
      <subscription_add_on>
        <add_on_code>premium_support</add_on_code>
        <name>Premium Support</name>
        <quantity type="integer">1</quantity>
        <unit_amount_in_cents type="integer">15000</unit_amount_in_cents>
        <add_on_type>fixed</add_on_type>
        <usage_percentage nil="true"></usage_percentage>
        <measured_unit_id nil="true"></measured_unit_id>
      </subscription_add_on>
      <subscription_add_on>
        <add_on_code>email_blasts</add_on_code>
        <name>Email Blasts</name>
        <quantity type="integer">1</quantity>
        <unit_amount_in_cents type="integer">50</unit_amount_in_cents>
        <add_on_type>usage</add_on_type>
        <usage_percentage nil="true"></usage_percentage>
        <measured_unit_id type="integer">394681687402874853</measured_unit_id>
      </subscription_add_on>
      <subscription_add_on>
        <add_on_code>donations</add_on_code>
        <name>Donations</name>
        <quantity type="integer">1</quantity>
        <unit_amount_in_cents nil="true"></unit_amount_in_cents>
        <add_on_type>usage</add_on_type>
        <usage_percentage>0.6</usage_percentage>
        <measured_unit_id type="integer">394681920153192422</measured_unit_id>
      </subscription_add_on>
    </subscription_add_ons>
    <activated_at type="datetime">2016-04-28T21:54:20Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2016-04-28T21:54:20Z</current_period_started_at>
    <current_period_ends_at type="datetime">2016-05-28T21:54:20Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
  </subscription>
</new_subscription_notification>

If we create usage on your behalf in a refund or terminate scenario, you will receive a new_usage_notification.

<?xml version="1.0" encoding="UTF-8"?>
<new_usage_notification>
  <account>
    <account_code>923845792374</account_code>
    <username></username>
    <email></email>
    <first_name></first_name>
    <last_name></last_name>
    <company_name></company_name>
  </account>
  <usage>
    <id type="integer">394729929104688227</id>
    <subscription_id>35cda8d4ae0a214f69779e4ddbbc2ebd</subscription_id>
    <add_on_code>video_storage</add_on_code>
    <measured_unit_id type="integer">394681920153192422</measured_unit_id>
    <amount type="integer">-40</amount>
    <merchant_tag nil="true"></merchant_tag>
    <recording_timestamp type="datetime">2016-04-28T21:57:53+00:00</recording_timestamp>
    <usage_timestamp type="datetime">2016-04-28T21:57:53+00:00</usage_timestamp>
    <created_at type="datetime">2016-04-28T21:57:54+00:00</created_at>
    <modified_at type="datetime" nil="true"></modified_at>
    <billed_at type="datetime">2016-04-28T21:57:54+00:00</billed_at>
    <usage_type>PRICE</usage_type>
    <unit_amount_in_cents nil="true">50</unit_amount_in_cents>
    <usage_percentage type="float"></usage_percentage>
  </usage>
</new_usage_notification>

Usage-Based Billing


Transactional businesses can better align price with value by implementing a usage-based billing model. Send Recurly your customer usage units and we will automatically bill them in arrears at the end of the billing cycle.

Suggested Edits are limited on API Reference Pages

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