> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluxrate.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Lifecycle

> How subscriptions progress through billing periods, status transitions, and invoice generation.

## Period Management

When a subscription is created, Fluxrate sets:

* `current_period_start` = `start_date`
* `current_period_end` = `start_date + billing_interval`

The invoice worker runs **every hour**. When it finds subscriptions where `current_period_end <= now`, it:

1. Generates a DRAFT invoice for the period
2. Calculates all fixed charges + metered usage
3. Advances the period: `current_period_start = old end`, `current_period_end = old end + interval`
4. Updates `last_invoiced_date`

## Proration

When a subscription is created mid-month, the first invoice covers the partial period (prorated):

```
Plan: $30/month
Subscription start: Jan 15 (mid-month)
First period: Jan 15 → Feb 1

Prorated charge: $30 × (17 days / 31 days) = $16.45
```

## Previewing an Invoice

Before the billing period ends, preview the current invoice:

```bash theme={null}
POST /api/v1/subscriptions/<subscription_id>/preview-invoice
```

This returns a preview of what the invoice would look like if generated now, including all usage accumulated so far.

## Manual Invoice Generation

Force generate an invoice immediately (useful for testing):

```bash theme={null}
POST /api/v1/subscriptions/<subscription_id>/generate-invoice
```

## Subscription Usage

View usage accumulated in the current billing period:

```bash theme={null}
GET /api/v1/subscriptions/<subscription_id>/usage
```

## Subscription Invoices

View all invoices for a subscription:

```bash theme={null}
GET /api/v1/subscriptions/<subscription_id>/invoices
```