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    

Create Subscription

To subscribe your customer's to one of your plans, you can create a subscription on the customer's account. A customer can have multiple subscriptions to different plans or the same plan.

A subscription is a customer's version of your plan. A subscription will match the plan rules by default, but you can override the subscription's price, quantity, subscription term, or list of add-ons to create a custom subscription for the customer.

When you create a subscription it can start immediately, start with a trial, or have a scheduled future start date.

How to Create a Subscription

You can create a subscription via the Admin Console, Hosted Payment Pages or the API. Please see our getting started guide to see which integration method is best for your business.

Hosted Payment Pages

Recurly provides an out-of-the-box checkout page for each plan. Send customers to the Hosted Payment Page of the plan you want them to subscribe to. When they subscribe, Recurly will automatically create an account for the customer with the subscription and billing information on it. Hosted Payment Pages do not support manual collection. Learn more out Recurly's Hosted Payment Pages here.

Admin Console

In the Admin Console, create an account for the customer or find their existing account. Under the Account Actions dropdown at the top right, select Add Subscription. Select the plan you want to subscribe the customer to and configure the subscription options.

Subscription Options

Plan

The plan the customer is subscribing to.

Billing Period

The subscription's billing period will have the billing period length defined on the plan. You cannot set a custom billing period for a subscription, but you can set a custom number of billing cycles for the subscription term.

Currency

The currency of the subscription will default to the site's default currency. If you are on Recurly's Professional plan or higher, you have Multiple Currency support and can select a different currency for the subscription. You will not be able to change the currency of the subscription once it is created.

Price per Billing Period

The subscription's base price per billing period. The default price can be overridden here for the specific subscription.

Plan Quantity

Quantity defaults to 1. Set multiple quantities for the subscription if you have a per user / per license billing model.

Subscription Term

This is the initial term, or number of billing periods, that a customer is committed to when subscribing. The default subscription term can be overridden here for the specific subscription. See Subscriptions Terms for more info

End of Term Behavior

This determines whether a subscription should auto-renew for another term when initial term completes or if it should expire at the end of the initial term. The renewal term behavior will default to the plan, but can be overridden for the specific subscription. See Subscriptions Terms for more info

Renewal Subscription Term

If the subscription is configured to automatically renew for another term, then you have the option to configure a Renewal Subscription Term. This is the commitment following the initial subscription term. The renewal term defaults to the plan's term length but can be overridden for the specific subscription.See Subscriptions Terms for more info

Setup Fee

The subscription will charge a setup fee on the first invoice if there is a setup fee on the plan. You cannot add, remove or set a custom setup fee at the subscription level. If the subscription will start with a trial, the setup fee will be charged on the trial invoice.

Add-ons

Select which add-ons should be included in the subscription. Add-ons in the subscription can have a custom price and quantity.

Start Date

You can choose to have the subscription start immediately or on a future date. If selected, the subscription will be created now, but will not issue an invoice until the future start date. It is not currently possible to set a past date.

If the subscription has a future date and a trial, the trial will start on the future date you select.

First Bill Date

Some businesses want their customers's subscriptions to always renew on a specific day, like the 1st of the month. If the subscription is forced to renew on a specific day, the initial invoice needs to prorate to that day, since the subscription will bill for a full new billing period. If you would like the subscription to renew on a specific day and have the initial invoice prorate to that day, used the "first bill date" option when creating the subscription (API only).

Collection Method

If you are on Recurly's Professional plan or higher, you have the Manual Invoicing feature and will see a collection method option. Automatic collection will try to collect on the new invoice immediately by creating a transaction with the account's billing information. Manual collection will create the invoice, but will not create a transaction, allowing the customer to pay later.

PO Number

If the subscription's collection method is set to manual, you can set a PO Number for the subscription. This PO Number will show on all invoices for the subscription.

Terms

Subscriptions billed with automatic collection will have payment terms of "On-Receipt". If the subscription's collection method is set to manual, the subscription will default to the payment terms specified in the Admin Console on the Invoice Settings page. The payment terms can be customized for the specific subscription. Note that the payment terms will be the same for all of the subscription's invoices moving forward, unless you change the subscription to update the terms.

Customer Notes

A subscription's invoice will show Customer Notes if your Admin Console has a default message defined or if you set specific text for the subscription. If you set specific text for the subscription, the same note will show on all invoices for the subscription until you change the subscription to take it away or set a different message.

Terms and Conditions Notes

A subscription's invoice will show Terms and Conditions notes if your Admin Console has a default message defined or if you set specific text for the subscription. If you set specific text for the subscription, the same note will show on all invoices for the subscription until you change the subscription to take it away or set a different message.

VAT Reverse Charge Notes

A subscription's invoice will show VAT Reverse Charge Notes if you have European Union VAT enabled and the customer is a business customer exempt from taxes (reverse charge scenario). You can set specific text for the subscription if needed. If you set specific text for the subscription, the same note will show on all invoices for the subscription until you change the subscription to take it away or set a different message.

Free Trial

A subscription will automatically have the same free trial configured on the plan. If you want to give the customer a custom trial length, you can redeem a free trial coupon, or set a custom trial end date (API only). Trial length can be completely customized with some examples being monthly, weekly, or daily to support your business.

If the plan does not have a trial, you can still give the subscription a trial with either method, coupon or API trial end date. Note that an added trial will not have the Trial Ending email or the ability to have a cardless sign-up, since those options are configured at the plan level.

You can remove a default trial via the API by setting the trial end date to "timenow" when creating the subscription.

Coupons

You can redeem a coupon when creating a subscription as long as the subscription's plan is an eligible charge for the coupon.

Gift Cards

You can redeem a gift card when creating a subscription to help pay for the subscription and flag the subscription as starting with a gift card.

Revenue Recognition Schedules

Revenue Recognition schedules are defined at the plan level, but they can be overridden at the subscription level if needed. This option is available in the API only.

Shipping Address

Physical goods subscriptions or merchants needing to tax on a physical location can define a shipping address for the subscription when the subscription is created. This address will show as the "Ship To" on the invoice and will automatically be used as the taxable address if taxes are enabled. Learn More

Billing Information Requirement

By default, Recurly will require valid billing information in order for an automatic collection subscription to be created. Manual collection subscriptions can be created without billing information.

There are two ways to remove the billing information requirement when creating an automatic subscription, a cardless free trial or use of a gift card.

Creating more than one subscription on an account

An account may signup for multiple subscriptions, where each subscription is invoiced and billed separately. There are a couple of ways that Recurly supports multiple subscriptions.

  • You can use increase the number of subscriptions with the Quantity field for a plan.
  • You can create multiple subscriptions of the same plan for an account that has separate renewal periods.
  • You can also use the API's purchase endpoint to create multiple subscriptions in a purchase. The subscriptions can be the same or different plans. This will result in a single invoice and transaction that includes all subscriptions. See Multiple Subscriptions for more information.

To have the multiple instances of the same plan enabled for your site, please contact support@recurly.com. Please note that there is a 60 second delay when creating multiple of the same subscription per an account, unless you use the bulk flag via the create subscription API.

Create Subscription


To subscribe your customer's to one of your plans, you can create a subscription on the customer's account. A customer can have multiple subscriptions to different plans or the same plan.

Suggested Edits are limited on API Reference Pages

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