> ## 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.

# Subscriptions Overview

> Subscriptions link customers to plans and drive the billing lifecycle in 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

```bash theme={null}
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:

1. Generates an invoice
2. Advances the period to the next interval

## Viewing a Subscription

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

```json theme={null}
{
  "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

```bash theme={null}
GET /api/v1/subscriptions?status=ACTIVE&customer_id=<id>&page=1
```

Filter by `status` and/or `customer_id`.