Billing cycle
DEFINITION
A billing cycle is the recurring period between charges on a subscription, such as monthly, quarterly, or annually, with its length set by the plan's billing interval. It repeats automatically until the subscription is canceled, paused, or its term ends.
TABLE OF CONTENTS
RELATED TERMS
A billing cycle is the recurring period between charges on a subscription, such as monthly, quarterly, or annually. Its length comes from the plan's billing interval, and it repeats automatically until the subscription is canceled, paused, or its term ends.
A billing cycle is not the same as a billing term. The cycle is a single recurring period, while the term is the full commitment a customer has agreed to, which can span multiple cycles. Recurly's subscription API tracks the two separately: current_period_started_at and current_period_ends_at mark the active billing cycle, while current_term_started_at and current_term_ends_at mark the broader term. Because these are distinct, queryable fields rather than a single renewal date, operators get a precise, programmatic view of where a subscription sits in its lifecycle.
A term's length is expressed in cycles through total_billing_cycles, and remaining_billing_cycles counts down as each period completes. When a term finishes, renewal_billing_cycles determines how many cycles the next term will run, defaulting to the plan's own cycle count if nothing else is set. Whether that renewal happens automatically depends on the subscription's auto_renew setting.
Why it matters
The billing cycle is the clock that drives most other subscription mechanics. It determines when a customer's card is charged, when an invoice is generated, and when dunning begins if a payment fails. Get the cycle wrong, whether it is misaligned to a customer's expectations, mismatched to a fiscal calendar, or inconsistently prorated, and the effects show up downstream in cash flow timing (Billings), predictable revenue tracking (MRR), and support tickets from confused customers.
Pricing can also change partway through a subscription's life, as with ramped or tiered pricing, and the billing cycle number itself becomes a reference point. A pricing schedule can be set to start at a specific cycle and run for a defined number of cycles, so getting the cycle count right is a prerequisite for that pricing logic working as intended.
How to use
Set the plan's billing interval (for example, monthly or annually) so it defines the default length of each billing cycle for subscriptions on that plan.
Decide the term length in cycles, using total_billing_cycles, if the subscription should run for a fixed number of periods rather than indefinitely.
Set renewal_billing_cycles if the term length after renewal should differ from the original term.
Use next_bill_date when a subscription's billing needs to align to a specific day of the month rather than the default start date. Recurly prorates the initial invoice between activation and that date.
Reference starting_billing_cycle on a ramp interval when a pricing schedule should change at a specific point in the subscription's life rather than from day one.
Monitor current_period_started_at, current_period_ends_at, and remaining_billing_cycles to track where a subscription sits within its current cycle and term.
Benefits and examples
A monthly SaaS plan renews on the same calendar date each month, adjusted for shorter months (for example, Jan 31 becomes Feb 28 or 29). Each current_period_ends_at closes out one billing cycle and opens the next.
An annual plan with a two-year contract might set total_billing_cycles to 2, so the term completes after two yearly charges unless it is renewed.
A subscription box that ramps pricing after an introductory period can use ramp_intervals[].starting_billing_cycle to raise the price starting at, say, the fourth cycle, without a manual plan change.
A merchant that wants invoices to always land on the first of the month can set next_bill_date accordingly, with Recurly prorating the first invoice to bridge the gap.
Recurly differentiators
Recurly's Subscription Management API exposes billing cycle and term as distinct, queryable fields rather than folding them into a single renewal date. current_period_started_at, current_period_ends_at, current_term_started_at, current_term_ends_at, total_billing_cycles, remaining_billing_cycles, and renewal_billing_cycles are all available on the subscription object, which gives operators a precise, programmatic view of where a subscription sits in its lifecycle.
Ramp pricing intervals also key directly off billing cycle number (starting_billing_cycle, remaining_billing_cycles on the interval), so cycle-based pricing changes are handled natively rather than through custom scripting.
Frequently asked questions
What is the difference between a billing cycle and a billing term? A billing cycle is one recurring charge period, such as one month. A billing term is the full length of the customer's commitment, which can be made up of one or more billing cycles.
Can a billing cycle be changed after a subscription starts? Yes. In Recurly, a subscription's next billing period start date can be set explicitly, which realigns the cycle. The initial invoice after that change is prorated to cover the partial period.
Does the billing cycle affect when dunning starts? Yes. Dunning begins from a failed payment tied to a specific billing cycle's charge, so the cycle length and timing set the clock for retry and communication schedules.
What happens when a subscription's remaining billing cycles reach zero? If auto_renew is true, the subscription starts a new term and uses renewal_billing_cycles to set its length. If auto_renew is false, the subscription expires at the end of the term.
