Bill Runs
The bill run is your monthly (or weekly, or quarterly) money moment: it finds every subscription due to be billed, generates the invoices, and advances billing cycles. Floatless wraps the whole thing in a preview → fix exceptions → commit workflow so you never commit money moves blind.
In the console this lives at Billing → Bill Runs — the page is titled the Billing Workbench.
When should I read this?
- It is the start of a billing period and you are about to invoice all recurring customers.
- Last month's bill run had exceptions and you want to clear them this time.
- You want an audit trail of who ran billing and what was produced.
Use cases
| Scenario | What you do |
|---|---|
| First of the month, all monthly plans renew | Preview with As-of date = today, review the ready list, commit. |
| You want to see the next two quarters of renewals | Preview with Billing cycles = 2 (read-only planning, no invoices). |
| One customer has a bad payment method and you don't want to hold the whole run | Let it land in Exceptions, commit the ready ones, fix the customer, run a fresh preview. |
Preview before execution
Preview is read-only. Nothing is invoiced, collected, or advanced.
Choose one end condition:
| Preview mode | Use when |
|---|---|
| As-of date | You want every billing period due on or before a specific date. |
| Billing cycles | You want a fixed number of future cycles (1–24) per subscription, without picking a calendar date. |
The modes are mutually exclusive. Click Preview bill run and the workbench evaluates every subscription.
What preview checks
- Subscription status and next billing date.
- Billing period and current cycle number.
- Product prices and quantities (locked subscription prices, not catalog prices).
- Metered usage recorded for usage-based lines.
- Customer tax settings and tax-exempt flags.
- Existing invoices for the same subscription period (no duplicates).
Reading the preview results
The summary cards show Evaluated, Ready, Blocked, and the Estimated total. Results are sorted into four tabs:
| Tab | Meaning |
|---|---|
| Ready to invoice | Clean subscriptions — these will get invoices. |
| Exceptions | Data problems that need a human (see below). |
| Skipped | Not eligible this run (paused, not yet due, already billed). |
| All | Everything, with search. |
Expand a row to see the exact invoice lines: description, usage type, usage events, quantity, unit price, and line total. Anything you can dispute, you can see here — before it becomes an invoice.
Resolve exceptions
Exceptions carry a severity badge (Error / Warning), a link to the subscription, the details behind the failure, and a recommended action: review the source record, resolve the data issue, then run a new preview before committing invoices. You can dismiss exceptions you have triaged.
Typical causes: a customer without a billable address, a price that no longer resolves, a usage anomaly, or a duplicate period.
Execute the run
Click Commit ready invoices (only available after a preview with ready items). The confirmation shows how many invoices will be created and how many subscriptions will stay blocked. Committed subscriptions get posted invoices with auto-pay enabled — payment collection starts immediately for customers with saved payment methods.
Run outcomes:
| Outcome | Meaning |
|---|---|
| Completed | Every evaluated subscription was billed. |
| Completed with exceptions | Ready invoices were created; blocked subscriptions remain in the queue. |
| Failed | The run stopped; nothing was partially committed. |
Bill run history
The right-hand panel keeps the last 20 runs, marked Preview or Commit. Click any entry to reopen its results — this is your audit trail for "what did we bill in June and who approved it".
Common review checks
- The customer count matches the expected billing cohort.
- No paused, canceled, or future-start subscriptions appear.
- Service periods and cycle numbers are correct.
- Taxes, coupons, and credits show on the invoice lines.
- Usage lines include only the intended window.
Troubleshooting
| Symptom | Check |
|---|---|
| Subscription missing from preview | Status, start date, next billing date, and billing period. |
| Invoice amount is wrong | Product price, quantity, coupon, customer tax status, and usage records. |
| Too many future invoices in preview | Use either as-of date or billing cycles — not both. |
| Execution created no invoices | The preview must have shown ready items; blocked items never invoice. |