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. This model does not have a concept of quantity.

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 fixed-price 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 fixed-price add-on for "premium support" that bills each month in addition to your base charge.

Learn more about Plans & Add-ons.

Seat-Based

The seat-based model bills a price per quantity upfront on a recurring basis. This model best represents billing per user/seat for time based access.

EXAMPLES

  • CRM: ZOHO charges $20/user/month
  • Customer Support: UserVoice charges $45/agent/month

HOW TO SETUP THIS MODEL

The seat-based model is a plan with a base recurring charge and the ability for the customer to select a quantity. 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.

If you have a per seat/user charge separate from a base recurring charge, you can use fixed-price add-ons with editable quantities.

Learn more about Plans & Add-ons.

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

HOW TO SETUP THIS MODEL

One-time charges can be incorporated in plans 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 have one-time physical products, like the Nest example above, you can either use the plan set-up fee, or create adjustments that get bundled with the subscription sign-up. To use adjustments, in your checkout flow, create an adjustment on the account for the physical product right before you allow the subscription sign-up to go through. This will allow the adjustment to be included on the same invoice as the subscription.

Learn more about Adjustments.

If you are interested in one-time purchases, separate from a subscription, use our Transactions API for an all in one endpoint.

Hybrid

The new Hybrid Billing Model combines Fixed Recurring with One-Time. Hybrid Checkout allows for a single subscription and a custom charge (non-recurring product) to be purchased together in a single transaction. This will be supported only through our API.

EXAMPLES

  • Physical Goods: BirchBox charges $30/month subscription and offers one-time products such as $25/makeup bag, $15/brush kit, etc.
  • Digital Goods: Hulu charges $39.99/month and offers one-time products such as movies or TV show seasons.

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 a subscription 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.

Billing Models

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