> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gettrxn.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Billing cycles
> Control when recurring charges occur with billing cycle anchors.
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:
| Behavior | Description |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `create_prorations` (default) | Creates a prorated charge for the partial period when the subscription starts before the billing anchor |
| `always_invoice` | Always creates an immediate invoice regardless of timing |
| `none` | No proration. If a billing anchor is set, waits for the anchor date. If no anchor is set, charges immediately at full price |
## 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
```
Subscription created: January 15, 2024
Billing anchor: January 31, 2024
Proration behavior: create_prorations
Timeline:
- Jan 15: Prorated invoice for Jan 15-31 ($54.84 for a $100/month plan)
Calculated as: ($100 / 31 days) x 17 days = $54.84
- Jan 31: First full invoice for Feb 1-29 ($100)
- Feb 29: Invoice for March ($100)
- Mar 31: Invoice for April ($100)
```
Fair billing where customers only pay for what they use.
Consolidate all customer billing to the 1st of each month.
**Without billing anchors:**
```
Customer A joins March 15 -> Bills on the 15th of each month
Customer B joins March 22 -> Bills on the 22nd of each month
Customer C joins March 28 -> Bills on the 28th of each month
Result: Scattered billing throughout the month
```
**With billing anchors** (anchor = April 1, 2024):
```
Customer A (joins March 15):
- March 15: Prorated invoice for Mar 15-31 (17 days = $54.84 on $100/month plan)
- April 1: Full invoice for April ($100)
- May 1, June 1, etc.: Regular monthly billing ($100)
Customer B (joins March 22):
- March 22: Prorated invoice for Mar 22-31 (10 days = $32.26 on $100/month plan)
- April 1: Full invoice for April ($100)
- May 1, June 1, etc.: Regular monthly billing ($100)
Customer C (joins March 28):
- March 28: Prorated invoice for Mar 28-31 (4 days = $12.90 on $100/month plan)
- April 1: Full invoice for April ($100)
- May 1, June 1, etc.: Regular monthly billing ($100)
```
Enterprise contract requiring billing on the 15th of each month.
```
Subscription created: June 5, 2024
Billing anchor: June 15, 2024
Timeline:
- Jun 5: Prorated charge for Jun 5-15 ($36.67 for $100/month plan)
Calculated as: ($100 / 30 days) x 11 days = $36.67
- Jun 15: First full monthly charge ($100)
- Jul 15, Aug 15, etc.: Regular monthly billing ($100)
```
Online course or digital product with immediate full access.
```
Subscription created: March 20, 2024
Billing anchor: April 1, 2024
Proration behavior: always_invoice
Timeline:
- Mar 20: Immediate full invoice ($100) -- customer gets instant access
- Apr 1: Next regular invoice ($100)
- May 1, June 1, etc.: Regular monthly billing ($100)
```
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):
```
Subscription created: January 5, 2024
Billing anchor: January 31, 2024
Timeline:
- Jan 5: No immediate invoice (waits for anchor)
- Jan 31: First full monthly charge ($100)
- Feb 29, Mar 31, etc.: Regular monthly billing ($100)
```
**Without billing anchor** (immediate charge):
```
Subscription created: January 5, 2024
Billing anchor: not set
Timeline:
- Jan 5: Immediate full monthly charge ($100)
- Feb 5, Mar 5, etc.: Regular monthly billing ($100)
```
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.
```
Subscription created: March 1, 2024
Billing anchor: March 15, 2024 (14 days later)
Proration behavior: none
Timeline:
- Mar 1: No invoice (trial period starts)
- Mar 1-14: Free trial period, full access
- Mar 15: First full monthly charge ($100)
- Apr 15, May 15, etc.: Regular monthly billing ($100)
```
## 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**
```ruby theme={null}
def create_subscription_for_customer(customer, plan)
# Company policy: all subscriptions bill on the 1st
next_first = Date.today.beginning_of_month
next_first = next_first.next_month if Date.today.day > 1
Subscription.create!(
customer: customer,
billing_cycle_anchor: next_first,
proration_behavior: 'create_prorations',
# ... other subscription setup
)
end
```
**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`
## Related pages
Multi-phase subscriptions with flexible pricing and automatic transitions.
How invoices are automatically generated from subscriptions.