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    

Billing Models

Recurly offers four core billing models that can be used in different plans or combined within a plan.

Fixed Recurring

The fixed recurring model bills a set amount upfront on a recurring basis.

EXAMPLES

  • Digital Content: Netflix charges $7.99/month
  • Box-of-the-Month: Birchbox charges $10/month or $110/year
  • Video Conferencing: GoToMeeting charges $39/month

HOW TO SETUP THIS MODEL

In its most simple version, this model is a plan with just a base recurring charge. If you are using our Hosted Payment Pages you will want to keep "Editable Quantity" not selected, so your subscribers do not have the ability to set a quantity at sign-up.

You may want to incorporate add-ons, which are additional recurring charges you can include in your plan as either required or optional fees to your subscribers. For example, you could include an optional add-on for "premium support" that bills each month in addition to your base charge.

Learn more about Plans & Add-ons.

Quantity-Based

Best for companies that want to have flexibility in their pricing based on the quantity a subscriber purchases.

TIERED PRICING

  • Charges for each unit based on the price of its corresponding tier.
  • For example, an office services company charges $1 for the first 100 documents and 50¢ each for all documents after the first 100.

VOLUME PRICING

  • Charges all units based on the price of the highest tier reached.
  • For example, a screen printing t-shirt company charges $10 for each t-shirt. If a customer buys more than 20, the cost of each t-shirt becomes $9.

STAIRSTEP PRICING

  • Charges a fixed price based on the highest tier reached.
  • For example, a SaaS company charges a fixed price based on the range of seats a customer buys: 1-10 are $50; 11-20 are $100; 21+ seats are $150. Regardless of whether a customer buys 25, 50, or 100 seats, they will pay $150.

HOW TO SETUP THIS MODEL

The quantity-based model can be setup using a plan with an add on. Set up tiers and prices at the plan level and provide a quantity for the subscription add on. Recurly will manage calculating the correct total based on the pricing model and quantity provided. If you are using our Hosted Payment Pages you will want to select the "Editable Quantity" checkbox, so your subscribers have the ability to set a quantity at sign-up.

Learn more about Plans & Add-ons.

Quantity-Based Pricing Early Access

Quantity-Based Pricing models are now GA for Items and Add-Ons charged at the beginning of the billing period.

Coming in early Q3 we will introduce the same functionality for Usage Add-Ons. Please reach out to [email protected] if you would like to be involved in our Early Access program.

Usage-Based

The usage-based model bills a variable amount at the end of the billing cycle. The variable amount is determined by usage measured over the billing cycle.

EXAMPLES

  • Phone Service: AT&T charges $30/month for 2GB and $15/additional 1 GB/month
  • Car Rental: Zipcar charges $7/month plus $7/hour of driving time

HOW TO SETUP THIS MODEL

The usage-based model is a usage-based add-on in a plan. You can define a "price per unit" or a "percentage of an amount". Once customers subscribe, usage is recorded through our API and rolled up into an invoice at each renewal.

Learn more about Usage-Based Billing.

One-Time

EXAMPLES

  • IoT: Nest charges $199 for a camera and $100/year for video history
  • Gym Membership: 24 Hour Fitness charges a $149.99 setup fee and $49.99/month membership
  • Web store: A jewelry-borrowing subscription service offers members the option to purchase a broader selection of jewelry from their web store.
  • SaaS: charge a flat fee for professional services or one-time events

HOW TO SET UP THIS MODEL

One-time charges can be incorporated in Recurly in two different ways.

Each plan can have one set-up fee. This is great for the 24 Hour Fitness example above or any traditional one-time service fee.

If you sell one-time items, we recommend using the Catalog feature to capture the details of what you sell. This will ensure that it is easy to record one-time purchases in the future. Using the catalog feature, you can set a default price and record commonly used attributes (SKU, accounting code, tax information) about the item to make it easy to sell the item via the Recurly API or the UI. For more information about the Catalog feature, please see here.

To use one-time purchases, in your checkout flow, create an adjustment on the account for the product through the Purchases endpoint, which can bill both recurring and one-time purchases together. See more here.

Hybrid

The Hybrid Billing Model enables combining the Recurring, Quantity-Based, Usage-Based and One-Time models to handle your business needs. Hybrid Checkout allows for subscriptions and custom charges (non-recurring product) to be purchased together in a single transaction. This will be supported only through our API using the purchase endpoint.

EXAMPLES

  • Physical Goods: BirchBox charges $30/month subscription and offers one-time products such as $25/makeup bag, $15/brush kit, etc.
  • Digital Goods: Streaming service charges $39.99/month and offers one-time products such as movies or TV show seasons.
  • SaaS: CRM softwares charges $50/month/user and charges for usage based on the number of leads generated or emails sent

HOW TO SETUP THIS MODEL

Hybrid checkout introduces the concept of a "purchase" which can include recurring and non-recurring product. It allows you to incorporate subscriptions with custom charges.

To use the hybrid model in your checkout flow you will need to use our API. In the request, you can submit a subscription with one or many adjustments on a new or existing account. The subscription and adjustment(s) will appear as line items on a single invoice, which are collected immediately. A purchase transaction is a single transaction to the gateway and if successful, will update or create an account in Recurly. If the transaction fails, the request will roll back.

If you are interested in a Hybrid Checkout, you can find more information in Purchases for an all in one endpoint.

Updated 4 days ago

Billing Models


Recurly offers four core billing models that can be used in different plans or combined within a plan.

Suggested Edits are limited on API Reference Pages

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