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    

Calendar Billing

Calendar billing consolidates your customers' subscription recurring charges into a single invoice

Background

Businesses that allow customers to purchase more than one subscription often want the ability for those recurring subscriptions to bill together as well. Based on your business model, there are different options to suit your needs.

The Aggregate Invoices feature of calendar billing aggregates all subscriptions on an account that share the same account bill date onto a single invoice. Merchants selling physical goods may prefer using Aggregate Invoices, since the feature does not force proration like the Aligning Renewals feature.

Aligning Renewals takes calendar billing a step further, by prorating purchased subscriptions with an immediate start date or subscriptions leaving trial to a single account bill date. By doing so, at the time of the account bill date, the subscriptions are aligned and renew together on a single invoice. This is a more common need for digital goods and services companies.

Aggregate Invoices

Aggregate Invoices consolidates subscriptions that share the same subscription bill date onto the same single invoice. If you have customers that are commonly invoiced on the same day for their subscriptions and/or you allow for multiple subscriptions to be purchased together, this is a great way to streamline your invoicing.

Eligible Subscriptions

In order for subscriptions to renew on the same renewal invoice, they must have the following characteristics:

  • Share the same bill date: down to the second (dd:hh:mm:ss). Multiple Subscriptions that are purchased together is the optimal way to achieve this.
  • One payment method: Since the invoice consolidates all charges into a single transaction, the invoice must be paid by a single payment method (e.g paid in full by credit card)
  • One collection method: Subscriptions in an aggregate invoice must all share the same collection method (either all manual or automatic). Subscriptions that do not share the same collection method will invoice separately.
  • Specific billing cadence: Only supported for monthly (must be at least 30 days), quarterly, or annual subscription billing cycles

Subscriptions Activating

Subscriptions that are purchased within 24 hours of the renewal date of an aggregate invoice will invoice separately.

Future start date subscriptions that are activating on the same day as an aggregate renewal invoice will activate at the same time as the other subscriptions, in order to bill together. However, if the shipping address differs from the other subscription, it will invoice separately.

Editing Account Bill Date

Once the Aggregate Invoice feature is enabled, Recurly will attempt to aggregate all subscriptions that share the same bill date (current_period_ends_at) onto a single invoice. It is not possible to manually override your site default so that within a group of aggregated subscriptions, one subscription can renew individually. However, if you manually edit a subscription's bill date to a date that is different than that of the account bill date, this subscription will invoice separately from the others. Additionally, if you want all the account's subscriptions to bill on a different date, you can adjust the bill date of all subscriptions to a new bill date (dd:hh:mm:ss). Both can be achieved via the API using the postpone feature. However, it is important to note that any future subscriptions purchased will not automatically bill to the same date unless the new subscription's bill date is manually updated to match the existing subscriptions' bill date.

Expiring or Canceled Subscriptions

If there are subscriptions in their last billing cycle or subscriptions that are canceled before the bill date of aggregated subscriptions on an account, these subscriptions will not be included in the renewal invoice.

Promotional Subscriptions Renewing or Expiring

Promotional subscriptions such as subscriptions purchased with a gift card or cardless free trials will expire if there is no payment method or sufficient credit/coupons to cover the full cost of all promotional subscriptions at the time of an aggregated invoice.

In the case where there are promotional subscriptions and non-promotional subscriptions set to bill together, if there is no payment method or it has been added or was removed, the subscriptions started with a gift card will expire and the cardless trial subscription will go into dunning.

Enabling Aggregate Invoices

Contact [email protected] to confirm eligibility to enable this feature on your site.

Immediately after the feature is enabled, any subscriptions that share a renewal date will be renewed on a single invoice.

Alignment

Similar to Aggregate Invoices, Alignment is a feature of calendar billing that consolidates all subscriptions onto a single invoice. The key difference is that this feature will align a subscription's bill date if it is purchased or coming out of trial on a day that does not match the account's bill date. By aligning the bill date of the subscription, a one-off prorated invoice is generated. This allows the new subscription to bill on the same invoice as the existing subscriptions at the next bill date.

Enabling Alignment

Contact [email protected] to confirm eligibility to enable this feature on your site.

Immediately after the feature is enabled, subscriptions that are purchased will align to a bill date or set the account bill date for the account if it is a new account.

Bill Date

Alignment introduces the concept of an account bill date. The bill date is a date (dd:hh:mm:ss) that gets set on an account which determines the date when subscriptions on an account bill together. If there are existing subscriptions on an account when the feature flag is enabled, the oldest subscription's bill date will be set as the account's bill date. What this means is, subsequent subscription purchases will align to that bill date. For new customers that purchase subscriptions after the feature flag is enabled, their account bill date will be set by their first non-trial invoice.

Once an account has a bill date, any future subscriptions that are purchased or immediate subscription upgrades or downgrades will prorate in order to align to the account's bill date.

Assigning a Bill Date

The account bill date is the date that an account's subscription(s) are billed. This date (dd:hh:mm:ss) is calculated by an account's first non-trial invoice. A non-trial invoice is considered the first bill date of a subscription. For example, if I sign up for a subscription for the first time on January 20th, my account's bill date will always be the 20th of the month moving forward. A $0 invoice is still considered a non-trial invoice. Additionally, if the customer has a gift card or promotional credit to cover the full cost of the non-trial invoice, this non-trial invoice date will still count as the account's bill date.

Last day of the month

For subscriptions that are assigned a bill date on the last day of the month, if the day does not exist for the next bill date, we will use the last day of the month (e.g January 31st, next bill date will be February 28th).

For subscriptions that are purchased on the last day of the month, and the bill date on the account is the first day of the month, the invoice amount will be smaller than usual. For example, a bill date of the 1st and a subscription purchased on the 30th will result in a prorated invoice for the 30th-1st.

Editing a Bill Date

You cannot change the Bill Date on an account. However, if you want to modify the bill date of a particular subscription or group of subscriptions, you can use the Postpone feature to manually change the bill dates of those subscriptions on the account. This is only possible via the API, as the Admin UI does not allow you to specify a renewal date up to the second. Once all the subscriptions share the same bill date (dd:hh:mm:ss), they will bill on the same invoice. However, once you edit a subscription's bill date, it will not re-align to the account's Bill Date and will renew separately.

Clearing a Bill Date

An account will always have a permanent bill date. It is not possible via the API or Admin UI to manually clear a bill date.

Aligning Logic

This section addresses subscription alignment scenarios based on whether there is an established bill date on an account and/or if subscriptions purchased are in trial. When a new subscription is purchased on an account that has a bill date, we first identify its normal billing cycle start and end dates and then pull in its bill date to match the account's bill date. We will never prorate a new subscription's billing cycle for a longer period than its original billing cycle.

Non-Trial Subscriptions

When a non-trial subscription is purchased, its bill date will either prorate to the account's bill date or, if there is no bill date, the non-trial subscription's bill date will be set as the account's bill date.

Monthly and Monthly Subscription Example

Existing customer is subscribed to monthly Silver subscription ($5) which bills on the first of every month. The customer purchases a monthly Gold subscription ($10) on the 15th of March.

  • The account bill date is the first of the month, set by Silver's bill date
  • Gold subscription's normal billing cycle would be March 15th - April 15th
  • Gold subscription's bill date of April 15th is pulled in to April 1st to align with the account's bill date
  • A prorated invoice of $5 for Gold is created for the billing period of March 15th - April 1st
  • The next month's invoice on April 1st will include both Silver and Gold ($5+$10=$15)

Monthly and Annual Subscription Example

Existing customer is subscribed to monthly Silver subscription which bills on the 15th of every month. The customer purchases an annual subscription to Gold plan on January 10th, 2017.

  • The account bill date is set as the 15th of each month by the Silver subscription
  • Gold annual subscription's normal billing cycle would be January 10th, 2017 - January 10th, 2018
  • Gold annual subscription's bill date of January 10th, 2018 is pulled in to December 15th, 2017 to align with the account's bill date
  • The Gold annual subscription will prorate for the period of January 10th, 2017 - December 15th, 2017
  • The next invoice that will include both subscriptions will be on December 15th, 2017

Annual and Annual Subscription Example

Existing customer subscribed to annual Gold subscription on January 10th, 2017 with a bill date of the 10th.

  • If the customer purchases a second annual subscription before February 10th 2017, it will end up on the same invoice as the existing subscription on January 10th, 2018
  • If the customer purchases a second subscription after February 10th, despite the subscription being aligned to the correct day of the month, the new annual subscription will not be on the same invoice and will renew 1 year after its start date

Annual Subscription Alignment

When a customer is currently subscribed to an annual subscription and purchases another annual subscription, the new subscription will only be aligned to the existing subscription if it is purchased within one month of the start date for the first annual subscription. To enable a subscription to align after the one month window, you can use the postpone feature.

Upgrades and Downgrades

Sometimes, customers' subscription plans are upgraded or downgraded. If an immediate subscription change includes a change of billing period, the subscription will need to be aligned since it resets to the current date. So long as this feature is enabled, any immediate subscription change will consider the account's bill date so that the subscription maintains alignment.

Monthly Upgrade to Annual Example

Existing customer is subscribed to monthly Bronze and Silver plans with a bill date of the 1st of the month. The customer upgrades their Silver monthly plan to the annual Gold plan on Jan 15th, 2017.

  • Gold annual subscription's normal billing cycle would be January 15th, 2017 - January 15th, 2018
  • Gold annual subscription's bill date of January 15th, 2018 is pulled in to January 1st, 2018 to align with the bill date of the 1st
  • A prorated invoice for Gold is created for the billing period of January 15th, 2017 - January 1st, 2018
  • The next invoice that will include both subscriptions will be on January 1st, 2018

Other (non-plan) immediate subscription changes will not require proration or adjustment to the subscription since it will keep the current billing period and maintain subscription alignment.

Expiring or Canceled Subscriptions

If there are subscriptions in their last billing cycle or subscriptions that are canceled before the bill date on an account, these subscriptions will not be included in the next invoice. This is the same logic that applies to the Aggregate Invoice feature.

Promotional Subscriptions Renewing or Expiring

Promotional subscriptions such as subscriptions purchased with a gift card or cardless free trials will expire if there is no payment method or sufficient credit/coupons to cover the full cost of all promotional subscriptions.

In the case where there are promotional subscriptions and non-promotional subscriptions set to bill together, if there is no payment method or it has been added and was removed, the subscriptions started with a gift card will expire and the cardless trial subscription will go into dunning.

This is the same logic that applies to the Aggregate Invoice feature.

Trial Subscriptions

There are a few important things to remember about trial subscriptions:

  • If an account does not have a bill date (brand new customer) and they purchase a trial subscription, we will not set the account's bill date until the trial ends (when the first non-trial invoice occurs)
  • If an account does not have a bill date (brand new customer) and they purchase trial subscriptions with varying lengths, whichever trial subscription that ends first will become the account bill date (e.g a 7-day trial subscription will have its first non-trial invoice before a 30-day trial subscription)

Trial Subscription without Bill Date

If a customer does not have an account bill date, it means that the customer either has a subscription(s) that is currently in trial or they are a brand new subscriber.

Example

New customer purchases a 7-day trial subscription on January 15th.

  • Trial ends on January 22nd and the subscription activates into its regular billing cycle
  • The account's bill date is set to January 22nd
  • Any subsequent non-trial subscription purchases or activations will align to this date

Trial Subscription with Bill Date

If a customer already has an account bill date and purchases a new trial subscription, when the subscription finishes its trial, we will align the bill date to match the account bill date. This will result in a one-off prorated invoice. At the next bill date, the subscriptions will bill together.

Example

Existing customer has an account bill date of the 10th. The customer purchases a subscription to monthly Gold plan with a 7-day trial on February 15th.

  • When the trial subscription ends on February 22nd, the first non-trial invoice occurs
  • Gold subscription's normal billing cycle is February 22nd - March 22nd
  • Gold subscription's bill date of March 22nd is pulled in to March 10th, to align with the bill date
  • A prorated invoice for Gold is created for the billing period of February 22nd - March 10th
  • The next month's invoice on March 10th will include both subscriptions

Emails

If you have automatic email templates enabled on your site or plans, the following email templates will support renewal-related emails. These emails will be sent, one email per subscription, if the template is enabled at the site level and if at least one of the subscription plans has the automatic email enabled.

  • Renewal Reminder
  • Payment Confirmation
  • Invoice Past Due

If you are interested in any of these features included in Calendar Billing, please contact Support at [email protected]

Updated about a month ago

Calendar Billing


Calendar billing consolidates your customers' subscription recurring charges into a single invoice

Suggested Edits are limited on API Reference Pages

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