The Data Model
Meters
A Meter is the lowest-level primitive. It defines:- What to measure (e.g., API calls, storage bytes, active users)
- How to aggregate raw events (SUM, MAX, UNIQUE_COUNT, LAST)
- Which property of the event payload to read
meter_token.
| Aggregation Type | Description | Use Case |
|---|---|---|
SUM | Adds all values in the period | API calls, data transferred |
MAX | Takes the highest value seen | Peak concurrent seats |
UNIQUE_COUNT | Counts distinct property values | Monthly active users |
LAST | Takes the most recent value | Current storage used |
Features
A Feature is an entitlement that wraps a meter (or not) and can be attached to plans. Features define what a plan unlocks for a customer.Feature Types
Meter Feature
Tracks quantitative usage. Backed by a meter. Can have usage limits and reset periods.
Switch Feature
A boolean on/off flag. Use for capabilities that are simply enabled or disabled.
Custom Feature
A text or numeric entitlement value. Use for custom limits like “max 5 workspaces”.
Plans
A Plan is a billing product. It defines the pricing structure a customer subscribes to. Plans have:- A type:
FIXED,USAGE, orHYBRID - A billing interval:
day,week,month, oryear - A currency
- Features — what capabilities are included
- Charges — how much to bill (fixed fees and/or usage-based prices)
Plan Types
| Type | What It Means |
|---|---|
FIXED | Customer pays a flat amount every billing period |
USAGE | Customer pays based entirely on metered consumption |
HYBRID | Customer pays a base fee + additional usage charges |
Charges
A Charge (also called a Price) is attached to a plan and defines the actual billing amount.- Fixed charge: A flat amount billed each period (e.g., $99/month)
- Usage charge: A per-unit price linked to a meter (e.g., $0.001 per API call)
- Tiered pricing: Different per-unit prices at different volume levels
Customers
A Customer represents one of your end users or accounts. Each customer has:- A unique
external_idthat matches your own system’s identifier - Billing address (important for tax calculation)
- Associated subscriptions and invoices
Subscriptions
A Subscription links a customer to a plan. It represents the ongoing billing relationship.Subscription States
| Status | Description |
|---|---|
TRIAL | Customer is in a free trial period |
ACTIVE | Normal billing is occurring |
PAST_DUE | Invoice payment overdue |
PAUSED | Subscription temporarily halted |
CANCELED | Subscription ended |
current_period_start and current_period_end — the active billing window.
Usage Events
A Usage Event is a raw measurement sent from your backend. Each event records:- Which meter it belongs to (
meter_token) - Which customer performed the action (
customer_external_id) - A quantity (or property value, depending on aggregation type)
- An optional timestamp and idempotency key
Invoices
An Invoice is generated automatically at the end of each billing period. The lifecycle:- DRAFT — Created by the background worker, not yet sent (1-hour review window)
- OPEN — Finalized and emailed to the customer
- PAID — Payment received
- VOID — Cancelled permanently
- UNCOLLECTIBLE — Written off as bad debt
Putting It Together
A typical Fluxrate implementation looks like:- Create a meter →
api_calls(SUM aggregation) - Create a feature → Meter feature wrapping
api_calls - Create a plan → “Pro” plan at 0.001 per API call
- Create a customer →
customer_external_id: "user_123" - Subscribe → Customer to the “Pro” plan
- Track usage → POST events as customer uses your API
- Invoice → Auto-generated at month end with exact usage billed
Next: Quickstart →
Follow the step-by-step guide to get your first integration running.