Subscriptions Overview - Fluxrate

A Subscription is the active billing relationship between a customer and a plan. When a subscription is active, Fluxrate tracks the billing period and automatically generates invoices when the period ends.

Creating a Subscription

curl -X POST https://api.fluxrate.co/api/v1/subscriptions \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=<token>" \
  -d '{
    "customer_id": "<customer_id>",
    "plan_id": "<plan_id>",
    "billing_interval": "month",
    "start_date": "2025-01-01T00:00:00Z"
  }'

Subscription Fields

Field	Required	Description
`customer_id`	✅	Customer to subscribe
`plan_id`	✅	Plan to subscribe to
`billing_interval`	✅	`day`, `week`, `month`, or `year`
`start_date`	✅	When the subscription begins
`trial_end_date`		Override the plan’s default trial end date

Subscription States

Created
  └─► TRIAL (if trial_days > 0)
        └─► ACTIVE
              ├─► PAST_DUE (unpaid invoice)
              │     └─► ACTIVE (payment received)
              └─► CANCELED
  └─► ACTIVE (no trial)
        └─► CANCELED

Status	Description
`TRIAL`	Free trial period; no invoices generated
`ACTIVE`	Normal billing; invoices generated each period
`PAST_DUE`	A bill wasn’t paid; access may be restricted
`PAUSED`	Billing temporarily stopped
`CANCELED`	Subscription ended; no future invoices

Billing Period

Each subscription has:

current_period_start — Start of the active billing window
current_period_end — When the next invoice will be generated

When the invoice worker runs and finds a subscription with current_period_end <= now, it:

Generates an invoice
Advances the period to the next interval

Viewing a Subscription

GET /api/v1/subscriptions/<subscription_id>

{
  "id": "...",
  "customer_id": "...",
  "plan_id": "...",
  "plan_name": "Pro",
  "status": "ACTIVE",
  "billing_interval": "month",
  "current_period_start": "2025-01-01T00:00:00Z",
  "current_period_end": "2025-02-01T00:00:00Z",
  "trial_end_date": null,
  "canceled_at": null,
  "created_at": "2025-01-01T00:00:00Z",
  "customer": { ... },
  "plan": { ... }
}

Listing Subscriptions

GET /api/v1/subscriptions?status=ACTIVE&customer_id=<id>&page=1

Filter by status and/or customer_id.