> ## Documentation Index
> Fetch the complete documentation index at: https://docs.1club.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bill runs

> Sweep a period of pending transactions into invoices in one batch.

A bill run takes every billable transaction in a period and groups it into invoices. That's the whole job. Bill runs do **not** charge anybody, send anything, or retry failed payments - they generate invoice documents and stop.

If you've been told "the bill run will collect money," that's wrong. Collection happens separately, through the [Payments](/billing/payments) flow or by sending an invoice payment link.

## What counts as billable

A transaction is included in a bill run when all of the following are true:

* It belongs to the organization running the bill run.
* Its date falls inside the period you select.
* `isInvoiced` is `false` (it hasn't been swept into an invoice yet).
* Its `paymentStatus` is not `void`.
* Its `transactionType` is one of the allowed types (booking, membership, signup fee, product sale, external program entry).

Already-paid transactions are still billable as long as they aren't on an invoice yet. The bill run produces a receivable record for them, just one that opens as **paid**.

## One invoice per contact, or one for everyone

Your organization's **billing preference** (set under **Settings > Billing**) decides how the bill run groups transactions:

* `separate` (default): one invoice per contact, containing all of that contact's transactions in the period.
* `single`: one combined invoice covering every billable transaction in the period, addressed to the first contact in the set.

For most gyms `separate` is what you want. `single` is for B2B billing where a corporate account is paying for many people in one document.

Every created invoice gets:

* A generated **invoice number** following your invoice template.
* An **invoice date** set to the moment the run executed (in the organization's timezone).
* A **due date** 30 days after the invoice date.
* Line items pointing back to the original transactions.
* A status derived from those transactions (`paid`, `partially_paid`, `pending`, or `overdue` based on the due date).

After invoices are written, each included transaction is marked `isInvoiced = true` so it won't be picked up again.

## Running a bill run manually

1. Go to **Billing > Bill runs** and click the **Bill run** action.
2. Give the run a name (defaults to `<month> <year> Bill Run`).
3. Pick a **Period start** and **Period end**. Defaults to the current month.
4. Optionally narrow the set with filters: transaction types, specific contacts, specific plans, an amount range.
5. Click **Preview** to see exactly which transactions will be invoiced. The preview shows transaction count, contact count, total amount, and a per-type breakdown.
6. Click **Confirm** to generate the invoices.

The **Auto-charge invoices** toggle on the form is a UI placeholder; the field is accepted by the API but is not wired to anything in the current backend. Leave it off. Use the [Transactions](/billing/transactions) batch-charge or invoice **Charge** actions to collect on what the run produces.

When the run finishes you land on the bill run details page with the list of invoices it created. From there you can click into any invoice to send a payment link or record payment.

## Scheduled bill runs

To run on a recurring schedule, use **Settings > Billing > Automated bill runs**.

Each schedule has:

* A **name** and **description**.
* A **frequency** (daily, weekly, monthly) and **time of day** that compile to a cron expression.
* Optional **filters** identical to the manual form.

When a schedule fires, it calls the same `executeBillRun` service the manual flow uses, with a default period (current month) and the saved filters. You can also trigger a saved schedule on demand from the **Run now** action; that confirmation dialog spells out which contacts and transaction types will be hit before it runs.

A scheduled run executes silently in the background; it does not email members or notify admins on completion. To see results, open the **Bill runs** list (the new run will appear there with its created invoices).

## Deleting a bill run

Deleting a bill run from the details page clears the `billRunId` on every invoice in it, then removes the bill run record. The invoices and their line items are kept. The original transactions stay marked `isInvoiced = true`. If you want those transactions to become billable again you have to delete the invoices too.

## Known limits

* No automatic retry. If you mean to run weekly and miss a week, schedule a one-off catch-up run.
* No row-level dry run beyond the preview. Once you click **Confirm**, the invoices are written.
* The `autoCharge` field on the create-bill-run API doesn't trigger any charge. Treat bill runs as invoice generation only.

## Related

* [Invoices](/billing/invoices)
* [Transactions](/billing/transactions)
* [Payments](/billing/payments)
* [Billing overview](/billing/overview)