Skip to main content

​
The subscription billing renewal date

A subscription’s billing period depends on two factors:
  • The recurring interval of its subscription, such as monthly, yearly, weekly, and so on.
  • The billing cycle anchor is the reference point that aligns future billing period dates. It sets the day of week for week intervals, the day of month for month and year intervals and the month of year for year intervals. The default value is either the subscription creation date or the trial end date (if you’re using a trial period). You can also explicitly set this value at the time you create the subscription.
Billing cycle anchors are UNIX timestamps in seconds from the current epoch.

​
What is Billing Cycle Anchor?

The billing cycle anchor (also called billing cycle anchor date) is a fixed reference point that determines when future billing cycles start. Think of it as an “anchor” that locks your subscription to specific dates, ensuring consistent billing dates across all renewal cycles. Key Concept: The anchor date determines the due day (the day when invoices are generated and payments are due) for all future billing cycles. This date remains consistent throughout the subscription’s lifetime unless explicitly changed.

​
How Billing Cycle Anchor Works

​
Default Behavior

When you create a subscription, UniBee automatically sets the billing cycle anchor based on:
  1. Subscription creation date - If no trial period is set, the anchor is the date when the subscription is created
  2. Trial end date - If a trial period exists, the anchor is set to the trial end date (when the trial period expires)
Example:
  • Subscription created on January 15, 2025 with no trial
  • Billing cycle anchor: January 15, 2025
  • Future billing dates: February 15, March 15, April 15, and so on

​
Explicit Setting

You can also explicitly set the billing cycle anchor when creating a subscription through the API. This is useful for:
  • Unifying billing dates - Align all subscriptions to bill on the same day (e.g., all subscriptions bill on the 1st of each month)
  • Delayed start - Start billing on a specific future date
  • Migration - Maintain billing dates when migrating subscriptions from other systems

​
Detailed Examples by Interval Type

​
Monthly Subscriptions

For monthly subscriptions, the billing cycle anchor sets the day of the month when future invoices are generated.

​
Example 1: Standard Day of Month

Scenario:
  • Monthly subscription created on January 5, 2025
  • Billing cycle anchor: January 5, 2025
Billing Schedule:
  • Period 1: January 5 - February 4, 2025 (due: January 5)
  • Period 2: February 5 - March 4, 2025 (due: February 5)
  • Period 3: March 5 - April 4, 2025 (due: March 5)
  • And so on…
Key Point: The subscription always bills on the 5th day of each month, regardless of how many days are in the previous month.

​
Example 2: End of Month Anchor

Scenario:
  • Monthly subscription with anchor date of January 31, 2025
  • Billing cycle anchor: January 31, 2025
Billing Schedule:
  • Period 1: January 31 - February 27, 2025 (due: January 31)
  • Period 2: February 28 - March 30, 2025 (due: February 28 - last day of February)
  • Period 3: March 31 - April 29, 2025 (due: March 31)
  • Period 4: April 30 - May 30, 2025 (due: April 30 - last day of April)
Key Point: When the anchor is set to the 31st (or 29th/30th), the system automatically adjusts to the last valid day of the month for months with fewer days.

​
Example 3: Unified Billing Date

Scenario: You want all subscriptions to bill on the 1st of each month for easier accounting. Solution: Set billingCycleAnchor to the 1st of the next month when creating subscriptions.
  • Subscription created on January 15, 2025
  • Set anchor to February 1, 2025
  • Billing Schedule:
    • First period: January 15 - January 31, 2025 (prorated for partial period)
    • Period 1: February 1 - February 28, 2025 (due: February 1)
    • Period 2: March 1 - March 31, 2025 (due: March 1)
    • All future periods: 1st of each month

​
Weekly Subscriptions

For weekly subscriptions, the billing cycle anchor sets the day of the week when future invoices are generated.

​
Example: Weekly Subscription

Scenario:
  • Weekly subscription created on Friday, June 3, 2025
  • Billing cycle anchor: Friday, June 3, 2025
Billing Schedule:
  • Period 1: June 3 - June 9, 2025 (due: Friday, June 3)
  • Period 2: June 10 - June 16, 2025 (due: Friday, June 10)
  • Period 3: June 17 - June 23, 2025 (due: Friday, June 17)
  • Period 4: June 24 - June 30, 2025 (due: Friday, June 24)
Key Point: The subscription always bills on Friday, maintaining the same day of the week for all future cycles.

​
Yearly Subscriptions

For yearly subscriptions, the billing cycle anchor sets both the month and day when future invoices are generated.

​
Example: Annual Subscription

Scenario:
  • Annual subscription created on March 15, 2025
  • Billing cycle anchor: March 15, 2025
Billing Schedule:
  • Period 1: March 15, 2025 - March 14, 2026 (due: March 15, 2025)
  • Period 2: March 15, 2026 - March 14, 2027 (due: March 15, 2026)
  • Period 3: March 15, 2027 - March 14, 2028 (due: March 15, 2027)
Key Point: The subscription always bills on March 15th of each year, regardless of leap years or month lengths.

​
Examples with Trial Periods

When a subscription includes a trial period, the billing cycle anchor is automatically set to the trial end date.

​
Example: Subscription with Trial

Scenario:
  • Subscription created on January 1, 2025
  • Trial period: 14 days (trial ends on January 15, 2025)
  • Billing cycle anchor: January 15, 2025 (trial end date)
Timeline:
  • Trial period: January 1 - January 14, 2025 (no charge)
  • Period 1: January 15 - February 14, 2025 (due: January 15)
  • Period 2: February 15 - March 14, 2025 (due: February 15)
Key Point: The billing cycle anchor shifts from the creation date to the trial end date, ensuring billing starts when the trial expires.

​
Use Cases

​
1. Unified Billing Date for All Customers

Business Need: All customers should be billed on the 1st of each month for simplified accounting. Solution: When creating subscriptions, set billingCycleAnchor to the 1st of the next month, regardless of when the subscription is created.

​
2. Maintaining Legacy Billing Dates

Business Need: Migrating subscriptions from another system while preserving existing billing dates. Solution: Import subscriptions with their original billingCycleAnchor dates to maintain the same due dates.

​
3. Delayed Billing Start

Business Need: Create a subscription today but start billing in 30 days. Solution: Set billingCycleAnchor to a future date (e.g., 30 days from now) to delay the first billing cycle.

​
Important Notes

  • Full billing periods start on the first full invoice date, which is often the same as the billing cycle anchor and is always interval-aligned with it.
  • The billing cycle anchor remains fixed throughout the subscription’s lifetime unless explicitly changed through subscription updates.
  • When you change a subscription plan (upgrade/downgrade), the billing cycle anchor typically remains unchanged, ensuring billing dates stay consistent.