Skip to main content
Billing cycle anchors provide precise control over when recurring charges are billed, enabling businesses to align billing with customer preferences, business processes, or contractual requirements.

​
What is a billing cycle anchor?

A billing cycle anchor is a specific datetime that determines when recurring billing periods start and end. Instead of billing based on the subscription creation date, the anchor ensures consistent, predictable billing on specific days.

​
Why billing anchors matter

Without billing anchors, subscriptions created on different days bill on different days:
  • Administrative overhead — processing payments scattered throughout the month
  • Customer confusion — unpredictable billing dates make budgeting difficult
  • Contractual requirements — some agreements require billing on specific dates
  • Proration complexity — mid-cycle upgrades and downgrades become harder without clear period boundaries

​
Proration behaviors

Subscriptions support three proration behaviors to handle the period between creation and the billing anchor:

​
Proration calculations

The system calculates prorated amounts with appropriate precision for each interval:
  • Daily — prorated by hours (for exact time-based billing)
  • Weekly — prorated by days
  • Monthly — prorated by days, accounting for varying month lengths
  • Yearly — prorated by days, handling leap years

​
Month-end anchor handling

Special logic handles billing anchors set to days 29-31:
  • Month-end normalization — a billing anchor on the 31st bills on the last day of shorter months (e.g., Feb 28/29, Apr 30)
  • Leap year support — February 29 anchors correctly handle non-leap years
  • Consistent behavior — ensures predictable billing even with varying month lengths

​
Time preservation

For subscriptions with daily intervals, the exact time of the billing anchor is preserved, enabling precise hourly billing for services that require it.

​
Scenarios

Fair billing where customers only pay for what they use.
Consolidate all customer billing to the 1st of each month.Without billing anchors:
With billing anchors (anchor = April 1, 2024):
Enterprise contract requiring billing on the 15th of each month.
Online course or digital product with immediate full access.
The customer pays full price on both signup and at the anchor date. This is intentional for immediate-access products.
Gym membership at full price regardless of join date.With billing anchor (waits for anchor):
Without billing anchor (immediate charge):
With the none behavior:
  • If billing_cycle_anchor is set, the system waits for the anchor date
  • If billing_cycle_anchor is not set, the system charges immediately at full price
14-day free trial, then monthly billing.

​
Implementation details

The billing anchor functionality is implemented through:
  • Database field — billing_cycle_anchor (datetime) on subscriptions
  • Calculation method — calculate_next_billing_date_from_anchor handles date logic including month-end normalization
  • Invoice generation — GenerateInvoicesJob respects anchors and prevents duplicates
  • Initial invoices — generate_initial_invoice creates prorated or full charges based on the proration behavior

​
Implementing consolidated billing

To achieve company-wide billing on specific days:
For SaaS platforms, create_prorations is the most common choice. It ensures fair billing while aligning all customers to the same billing date.
Option 1: Manual setting Staff explicitly set billing_cycle_anchor when creating subscriptions. Option 2: Business logic layer
Option 3: Account-level default Add a default_billing_day field to the Account model to automatically set anchors for all new subscriptions.

​
Best practices

  1. Set anchors thoughtfully — consider your business operations and customer expectations
  2. Communicate clearly — inform customers about proration and billing dates
  3. Test edge cases — verify behavior around month-ends and leap years
  4. Choose the right proration behavior:
    • SaaS platforms often use create_prorations
    • Membership sites might prefer none for simplicity
    • Immediate access services benefit from always_invoice

Subscriptions

Multi-phase subscriptions with flexible pricing and automatic transitions.

Invoice generation

How invoices are automatically generated from subscriptions.