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    

Multiple Subscriptions

Recurly supports a few ways that a customer can sign up for multiple subscriptions.

API

You can create multiple subscriptions on an existing or new account using the purchases endpoint.

Purchases endpoint

Using the purchase endpoint , you can create a purchase that can include more than one subscription. The purchase can include many subscriptions and also can include one-time charges as part of the Hybrid billing model. All subscriptions and charges in the purchase are summed into a single invoice total, that is billed together as one transaction. A purchase can be charged to an existing or new account.

Key points

  • subscriptions must share the same payment method (e.g credit card or ACH), you cannot specify per subscription. Only one payment method can be used in a purchase
  • all subscriptions must share the same collection method (e.g all automatic collection method or all manual collection method)

Purchase Invoice

A successful purchase that includes more than 1 subscription will receive a single invoice that includes all the subscriptions and/or one time charges. Each charge will have its own line item that includes the relevant date, quantity, price, and subtotal. A multiple subscription invoice will result in a single transaction to your payment gateway.

Above is an example of a purchase that included two subscriptions and two custom charges.

Above is an example of a purchase that included two subscriptions and two custom charges.

Emails

The following email templates also support multiple subscription purchases:

When creating multiple subscriptions in purchase, a single New Subscription email will be sent that will contain all subscriptions purchased.

To update your email templates to support multiple subscription purchases, see Subscription fields.

Webhooks

If the multiple subscriptions feature is turned on your site, the following webhooks will include a subscriptions xml tag with a list of subscriptions.

  • new_invoice
  • closed_invoice
  • successful payment
  • failed_payment
  • past_due_invoice
  • new_dunning_event
  • successful_refund

This is new behavior based on if the feature is enabled. If multiple subscriptions is not enabled on your site, we will maintain the original subscription xml tag.

Exports

If the multiple subscriptions feature is turned on your site, any export that has a subscription_id will now also render a new comma separated list of subscription_ids .

Coupon Redemption In Multiple Subscription Purchase

To learn more about how coupon(s) will apply in a multiple subscription purchase, visit Multiple Coupons in a Multiple Subscription Purchase for more information.

Consolidated Subscription Bill Dates

Subscriptions that are purchased together will naturally bill on separate invoices. If you are interested in subscriptions billing on a single invoice, you may want to use our Calendar Billing feature.

Custom Notes

Recurly has a feature that allows you to customize your invoices with default terms and notes for your customers.

There are 3 different types of notes: Terms & Conditions, Customer Notes, VAT Reverse charges notes. (see this page )

If you are using custom notes and multiple subscriptions, the invoice will include a single set of each note type (Terms, Terms & Conditions, Customer note) that will always use your site level default notes. If you would like to customize the notes for the purchase invoice, you must specify those custom notes in the purchase API request. You cannot specify different custom notes for each subscription on the invoice.

For VAT Reverse Charge Notes to appear on an invoice, the following must be true:

  • If your Recurly site has EU VAT enabled or you are using your own Avalara AvaTax account
  • AND your customer is in the EU and has a VAT number
  • AND your customer is in a different country than your company

If true, the purchase invoice will default to displaying the VAT Reverse Charge Notes text specified on the Tax Settings page in the Recurly admin, unless custom VAT notes were specified for the purchase invoice.

Admin UI or Subscriptions endpoint

If you want to add more than one subscription to a new or existing account, one option is to do this through the Admin UI. Using the Admin UI, you can increase the number of subscriptions with the Quantity field for a plan. Each subscription is invoiced and billed separately upon successful payment.

Using create subscription endpoint, you can also individually add subscriptions to a new or existing account at a time. Just like adding subscriptions via the Admin UI, the subscriptions will be invoiced and billed separately upon successful payment.

If you are using Recurly New Subscription or New Invoice email, an email will be sent for each individual subscription.

Multiple Subscriptions


Recurly supports a few ways that a customer can sign up for multiple subscriptions.

Suggested Edits are limited on API Reference Pages

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