Skip to main content

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.

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