Subscription Lifecycle

Period Management

When a subscription is created, Fluxrate sets:

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

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

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

Before the billing period ends, preview the current invoice:

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.

Force generate an invoice immediately (useful for testing):

POST /api/v1/subscriptions/<subscription_id>/generate-invoice

View usage accumulated in the current billing period:

GET /api/v1/subscriptions/<subscription_id>/usage

View all invoices for a subscription:

GET /api/v1/subscriptions/<subscription_id>/invoices