Run billing for a client

Price a client's time for one closed period with the five-step run wizard, fix blockers, review billing descriptions and bank totals, commit, and void a run when needed.

Written for
admin
Roles
owner, admin
Requires
Owner or Admin; Browser session with a recent re-authentication; A closed period
Feature
billing

A billing run prices one client's time for one closed period: "One client, one closed period, in sequence. A run prices time, applies banks, and produces the client timesheet." It reads the rate card, policies, and banks at that moment, writes the outcome of every entry, posts the bank ledger, and renders the documents. Committing is audited and can only be undone by voiding the whole run.

Before you start

  • You need the Owner or Admin role, in the browser. API keys and the create_billing_run MCP tool always refuse.
  • The period must be closed. "Only closed periods can be run, and a client's periods must be run in order."
  • You will re-authenticate and type the period start date before committing.
  • Check the client's Settings tab: Default currency, Timesheet layout, and Rounding (minutes) are read by the run.

Run the wizard

Open Billing → Billing runs and select New run.

Step 1: Client and period

Choose the Client and the Period. Only closed periods are listed. If the client has an earlier closed period without a non-voided run, step 2 warns: "This client has an earlier closed period without a run. Run that one first; bank balances depend on the order."

Step 2: Entries and blockers

The run selects every billable entry billed to this client with a work date up to the period end, in a closed period, that no live run has priced. That includes leftovers from earlier periods, such as deliverables that have closed since. Entries on tickets billed When the ticket closes are only selected once the ticket is in a closed state.

Blockers are listed per ticket, and the run refuses to commit while any remains ("Fix the blockers before running."):

Blocker Fix
No consultant category on the entry Set the entry's category (Owner or Admin), or the person's default for future entries.
No rate on the card for this category and date Add a rate on the client's rate card valid from on or before the work date.
No billing description on the ticket Write one in step 3 or on the ticket.
The policy names a bank that does not belong to this client or project Change the policy or the bank's scope.

Otherwise: "Nothing blocks this run." The step also shows Cutoff {date} (the period end) and rounding {n} min, and the priced lines: Work date, Id, Category, Billing description, minutes (billed, with the raw minutes in brackets when rounding changed them), Outcome, and Amount. Corrections are marked "(correction)".

Step 3: Billing descriptions

One field per ticket in the run. "The client sees this text, never the ticket title or the entry notes. A missing description blocks the run." Edit and Save; this writes the ticket's Billing description and is why the run requires it: it is the only text about the work the client will read.

Step 4: Banks and totals

The bank block shows, per bank: Opening, Credit, Carried in, Borrowed, Consumed, Overage, Closing. Under it: "Charged {hours} ({amount}) · bank {hours} · free {hours}", and, when relevant, "Work in progress, not yet billed: {hours}" for open When the ticket closes tickets. An empty run reads "Nothing to bill in this period. A run with nothing to bill still posts bank rollover."

Step 5: Re-authenticate and commit

Select Re-authenticate if asked ("Confirm your identity to commit a billing run."). Then, under Commit this run, type the period start date and select Commit run. The run page opens.

What the run does

  • Rounds each ordinary entry up to the client's Rounding (minutes) (0, 6, 15, or 30; 0 means no rounding). A correction is rounded cumulatively against its original's net, so a −5 minute correction on an entry rounded to 15 may change nothing.
  • Resolves the rate (project override, then client card, latest Valid from on or before the work date) and the policy (ticket, project, client, workspace default, then Paid). A correction reuses the rate and policy its original was billed with.
  • Draws banks, then prices the remainder as charged or free. Amounts are computed in the client's currency and exclude VAT.
  • Posts the bank rollover and consumption rows, records one outcome per priced part of each entry, and queues the documents.
  • Marks the entries as billed. From now on they are frozen until the run is voided.

Run states

State Meaning
Committed Priced and posted; documents are being rendered.
Documents ready Timesheets are available for download.
Delivered Every document has been delivered to its billing recipients.
Voided Undone; see below.

The run page shows Priced entries, the Bank block, the Documents with their delivery states, and Void run on the client's latest run.

Void a run

Only the client's latest non-voided run can be voided: "Void the client's latest run first; bank balances depend on order." Select Void run, re-authenticate, type the period start date, and confirm. "Every ledger row this run posted is reversed, its allocations become history, and its documents stop working. Email already accepted by a recipient cannot be recalled."

After a void the entries are unbilled again, the documents refuse download ("This document was voided."), queued rendering and delivery are cancelled, and deliveries that were in flight are flagged: "Delivery was in flight when the run was voided and needs reconciliation: {emails}". Run the period again to replace it.

Rules

  • One non-voided run per client and period; a second attempt is refused ("A run for this period exists.").
  • Each wizard visit carries an idempotency key. Re-sending the same commit returns the same run; the same key with different input is refused ("This idempotency key was used for different input."). A replacement after a void needs a fresh key, which a new wizard visit provides.
  • There is no separate cutoff date: the run prices everything up to the period end. Corrections bill in the period they are made.

Common problems

"A run requires a closed period. Close it first." Close the period under Billing → Periods.

"Run the client's earlier closed periods first." Run the earlier period first; the order matters because bank balances depend on it.

"This client has no closed period left to run." Every closed period already has a run for this client.

"Fix the blockers before running." Return to step 2 and resolve each listed blocker.

"Confirm your identity to continue." The re-authentication expired; repeat step 5.

The run stays on Committed. Documents render in the background right after the commit; the page refreshes itself until they are ready.

  • Close a period Close a month or week so its time entries are frozen for billing, using the four-step wizard with its advisory checklist, first-period boundary, re-authentication, and typed confirmation.
  • How billing works The path from a logged time entry to a client timesheet, in order, and who configures each step.
  • Consultant categories and rate cards Define the categories that carry hourly rates, assign a default category per person with project overrides, and maintain each client's rate card with effective dates and project-specific rates.
  • Billing policies Set per ticket kind whether work is paid, free, or drawn from a time bank, at the workspace, client, project, or ticket level, and understand which rule wins.
  • Time banks Set up recurring or prepaid pools of hours per client, understand every bank setting and ledger row, post adjustments, and see who can read balances.
  • Client timesheets (documents) What the timesheet documents a billing run produces contain, who can download them, how they are delivered to billing recipients, and how to fetch them through the API or MCP.
  • Billing fields on a ticket What the Billing client, Policy, Mode, Billing description, and Estimate fields on a ticket mean, who may set them, and what changes when the billing client or kind changes.
  • Session-only operations A catalogue of every SAQ API operation that exists only for the browser session, so integrators know the full surface and why API tokens are refused on it.