Subscriptions
A subscription is a recurring billing agreement between your company and a customer.
Subscriptions tell Floatless what to bill, when to bill it, and how each billing cycle should advance.
Subscription structure
| Field | Purpose |
|---|---|
| Customer | The account responsible for payment. |
| Status | Whether the subscription should bill, pause, or stop. |
| Start date | When the subscription becomes eligible for billing. |
| Billing period | Monthly, annual, or another configured recurrence. |
| Next billing date | The next date a bill run should consider the subscription. |
| Line items | Products, quantities, prices, and usage settings. |
| Current period | The service window covered by the current billing cycle. |
Lifecycle
Draft or pending -> Active -> Renewing -> Past due -> Canceled or ended
| Status | Meaning | Billing behavior |
|---|---|---|
| Active | Subscription is live. | Included in bill runs when due. |
| Past due | Latest invoice or payment needs attention. | May continue billing depending on recovery settings. |
| Canceled | Customer or team stopped future billing. | No new recurring invoices after cancellation. |
| Ended | Subscription has reached its end date. | No future billing. |
Subscription line items
Subscriptions can include multiple line items:
- Licensed seats.
- Fixed platform fees.
- Metered usage.
- Add-ons.
- Support packages.
Each line should have a product, quantity, price, and usage type.
Licensed vs metered billing
| Type | How it bills | Example |
|---|---|---|
| Licensed | Bills a fixed quantity each period. | 20 seats at USD 25 per seat. |
| Metered | Bills usage recorded during the period. | 120,000 API calls at USD 0.01 per 1,000 calls. |
For metered items, usage must be recorded before the bill run executes. Late usage should be handled through your chosen adjustment policy.
Amendments and plan changes
When customers upgrade, downgrade, add seats, remove seats, or change plans, decide:
- Whether the change takes effect immediately or next period.
- Whether proration applies.
- Whether credits should be issued.
- Whether the customer should receive an updated invoice immediately.
- Whether downstream systems need webhook events.
Always preview billing impact before committing high-value subscription changes.
Cancellation
Cancellation policy should match your commercial terms:
| Policy | Behavior |
|---|---|
| Cancel immediately | Ends service and future billing now. |
| Cancel at period end | Keeps service active through the paid period. |
| Fixed-term end | Ends on a contracted end date. |
Troubleshooting
| Symptom | Check |
|---|---|
| Subscription missing from bill run | Status, start date, next billing date, and current period. |
| Wrong amount | Line item quantity, locked price, coupon, tax, and usage records. |
| Usage not billed | Confirm usage was recorded against the correct subscription item before the bill run. |
| Customer billed after cancellation | Confirm cancellation effective date and cancel_at_period_end behavior. |