Skip to main content
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

FieldRequiredDescription
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_dateOverride 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
StatusDescription
TRIALFree trial period; no invoices generated
ACTIVENormal billing; invoices generated each period
PAST_DUEA bill wasn’t paid; access may be restricted
PAUSEDBilling temporarily stopped
CANCELEDSubscription 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:
  1. Generates an invoice
  2. 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.