Bill accounts and send invoices
As a Workforce Intelligence operator, turn on operator mode, create free accounts and free periods, choose how each account is billed (free, invoiced or card), write a billing note, set up new sign-ups, track monthly invoices through sent and paid, and export them as a CSV.
Each Workforce Intelligence account is billed in one of three ways. You choose, per account, from the operator section. Every action that changes something needs operator mode, which you turn on once with the operator code and which lasts 30 minutes (see Turn on operator mode). No code is asked on each form.
You are an operator when your confirmed portal email is on the operator domain list. Operator pages do not exist for anyone else. When no operator code is configured, the pages say the actions are unavailable; reports and lists still work.
Turn on operator mode#
Every operator page shows a banner at the top. While operator mode is off it says Operator mode is off and has an Operator code field and an Unlock operator mode button. Enter the code once and select the button. The banner then says Operator mode is on for N more minutes, and every change on every operator page works with no further code. While operator mode is off the edit controls are not shown: each place that would hold a form says "To make changes, turn on operator mode in the banner above." instead, and the forms appear once operator mode is on. Reports, lists and CSV exports are visible either way.
- It lasts a fixed 30 minutes from the moment you unlock. Using it does not extend it. When the time ends, unlock again.
- It belongs to the browser session you unlocked. It ends when you select Exit operator mode, sign out, use Sign out everywhere, or the session expires. Another browser or session of yours is not unlocked.
- If operator mode ends while a page is open and you submit a change, nothing is changed. The page says so and links back to the operator page; unlock, then repeat the change.
- The code is limited by unlock attempts, not by changes: 5 attempts per 15 minutes per operator, and every attempt counts, right or wrong. After the fifth you see Too many code attempts and are refused, even with the correct code, until the oldest attempt is 15 minutes old.
- The code is never stored or recorded. Unlocking and exiting are recorded in the audit trail (see What is recorded).
Find your way around#
The operator section has a left navigation, which sits above the page on a phone: Dashboard (this month's billed, cost and margin, account counts, upstream health, the Awaiting setup, Invoices to send and Card accounts not charged cards, and the last ten operator actions), Customers (Accounts with All, Paying, Free, Not paying and Markup override filters, Free accounts and Invoices), Reports (Margin report) and Platform (Upstream keys and models).
Every account is in exactly one of three groups: Paying (invoiced or card), Free and Not paying (no billing arrangement). The Dashboard Accounts card shows a count for each, plus All accounts and Markup override, and each count opens the Accounts list with that filter on. On the list, the Billing column shows a pill for each account: Card, Invoice, Free or Not set up. An account whose billing mode is not set counts as Free when it has ever had a free period, as Card when a card is on file, and as Not paying otherwise.
The three billing modes#
| Mode | What happens |
|---|---|
| Free | The account follows its free period: usage in the period is not billed and no card is needed. |
| Invoiced | At month close the account gets an invoice record for what it used. You send the invoice from your own accounting and record here whether it was sent, paid or voided. Nothing is charged by card. |
| Card | The account adds a card and is charged each month through Stripe. This needs card billing to be turned on (see Card billing). |
A free period and a billing mode are separate. An invoiced account can have a free period: the free usage is subtracted from each invoice.
An account that never had a mode chosen reads as follows, and nothing is changed in storage until you save a mode:
- Free when the account has ever had a free period, whether active, scheduled or ended. If the account also has a card on file, free wins: the free period governs while it lasts and the card stays on file. After the period ends without a card, the account is asked to add one (or, when card billing is off, to contact us) until you choose a mode.
- Card when it has a payment method on file. A Stripe customer without a card (for example, someone who left the card page without finishing) does not count.
- Not set up otherwise.
An account page shows the stored choice as Billing: Free, Invoiced, Card or Not set up, with "assumed, not set" after a value read from the rules above.
Set a billing mode and note#
- Open the account from Accounts.
- In Change how this account is billed, choose the Billing mode: Not set, Free, Invoiced or Card.
- Optionally write a Note (optional, up to 500 characters). The note is for operators only: the customer never sees it, it is not part of the invoice list or its CSV, and it is cut to 500 characters with line breaks and control characters turned into spaces.
- Select Save billing.
Saving the values the account already has changes nothing and writes no audit entry. Card is offered only while card billing is on, or when the account is already set to it (the option then reads Card (card billing is off)).
Free accounts and free periods#
A free account uses Workforce Intelligence without a card or a bill for the dates you set. Its owner still signs in to the account portal, sees what they spend, and has a monthly limit that only you can change while the free period is active (the owner sees it read only). Any account can be free for a period.
- Create a free account. Open Free accounts, enter the owner's email address (required), optionally
set Free from (blank starts now) and Free through (blank means no end; the end date is the last
free day), and select Create account. The account is reserved for that email. The link to the owner is
made when they confirm the email from the message we send them, and the audit trail records
account.claimed. If that email already has an account, use Make this account free on it instead. - Make an existing account free. Open it from Accounts (a Free badge marks accounts with a free period). In Make this account free (Change the free period when one is set), fill in Free from and Free through, both optional, and select Save free period. A start date in the past is refused.
- End the free period. Select End free period under End the free period and confirm. Usage already recorded stays free. Usage from then on is billed under the account's billing mode: an invoiced account gets an invoice, and a card account needs a card. When card billing is off, choose Invoiced for the account before the period ends if it should keep working.
- Free accounts list. Shows each free period as Active, Scheduled or Ended, with dates, usage this month against its limit, active keys and markup. On a free account's page you can change the monthly limit and create, rotate or revoke keys, while the account is free right now.
At month close an account's invoice covers only what was billed minus the free part. A fully free month produces no invoice and needs no payment customer, and the owner sees No charge. The Margin report counts free usage as its own cohort on the Free usage cost line (cost, accounts and calls); an account free for half a month appears in both.
New sign-ups wait for you#
Anyone can create an account. A new account has no billing arrangement, so:
- the owner can sign in. With card billing off, Overview and Billing tell them the account is waiting
for billing to be set up and to contact sales for invoiced billing. With card billing on, they offer
Add a card and a line about being invoiced by contacting sales. The sales address is the
sales_emailvalue in the legal entity file (entity.json), the same address the public landing page shows; - requests from their installation are refused (error
billing_not_set_up, HTTP 402) with a message that names the sales address and, with card billing on, mentions adding a card; - keys and the spend limit stay unavailable until billing is set up;
- the account appears on the operator Dashboard under Awaiting setup, and it counts as Not paying on the Dashboard Accounts card and in the Not paying filter of Accounts. You are not emailed.
With card billing on, a person may set up their own card: when it is saved, the account is stored as Card
and the account history records billing.mode_self_service. A mode you chose is never changed by this.
Select Set up billing on a row to open the account's billing form, choose the mode and save. Requests work from then on: a free account follows the free-period rules, an invoiced account needs no card, and a card account needs a card on file.
Invoices#
At month close (02:00 UTC on the 1st, for the previous month) each invoiced account gets one invoice record. It covers what the account used minus the free part, plus any amount carried from earlier months, in whole cents. A month under the minimum charge is carried to the next month instead, and a month with nothing to charge produces no record to send. Running month close again never creates a second record.
Each record has:
- a Number such as
INV-202611-0001(the month, then a counter for that month); - an Amount, a Due date 30 days after month close, and a Status.
The number is a reference in Workforce Intelligence's portal. Your accounting is the legal record of the invoice, and customers are told the same.
Nothing here takes payment, sends a message or pauses an account. An unpaid invoice past its due date shows a Past due label for you to see, and the account keeps working.
Statuses#
| Status | Meaning | You can move it to |
|---|---|---|
| Open (listed as To send) | Created, not yet sent. | Sent, Paid, Void |
| Sent | You sent it from your accounting. | Paid, Void |
| Paid | You received payment. Final. | None |
| Void | Cancelled. Final. | None |
Marking an invoice with the status it already has changes nothing. A move not in the table is refused with a message.
Work the list#
- On the Dashboard, Invoices to send lists open invoices. Send each from your accounting.
- On a row, choose Mark sent, Mark paid or Void in Change status and select Save.
- Open Invoices in the left navigation (under Customers), or All invoices on the dashboard, to see every invoice. The filter buttons are All, To send, Sent, Paid and Void.
Customers see their own invoices on Billing and Usage as Invoiced, the amount, number, due date and status (Open, Sent, Paid or Void).
Export a CSV#
Select Export all invoices (CSV) on Invoices, or Export (CSV) on the dashboard. The file
invoices.csv has one row per invoice with the columns number, account_id, owner_email, month,
amount_usd, due_date and status. Billing notes are never in it. Cells that could be read as
spreadsheet formulas are escaped. Adding ?month=202611 to the export address limits it to one month.
Each export is recorded in the audit trail before the file is returned. If that record cannot be written, you get no file.
Changing an account's billing mode mid-month#
Switching an account's mode charges nothing at that moment, and nothing is charged per request in any mode. Usage adds up in the account's month counter whatever the mode is. What decides how a month is billed is the account's billing mode at the time month close runs for that month, not the mode it had when the usage happened:
- Card: the whole closed month becomes a Stripe invoice, charged to the card on file.
- Invoiced: the whole closed month becomes one numbered invoice record for you to send. No request is made to Stripe.
So the effect of a switch is easy to predict:
- Card to invoiced on the 15th: the entire month, including the first half, becomes one invoice record.
- Invoiced to card on the 15th: the entire month is charged to the card. If the account has no Stripe customer (it never added a card), month close refuses that account and does not consume the month, so it can be billed once a customer exists. The run reports the failure.
- Months already invoiced are never changed by a later switch.
- Last month's close runs at 02:00 UTC on the 1st. If you change a mode on the 2nd, before that close has run (for example because the job failed and is being re-run), the new mode decides how last month is billed. To keep last month under the old mode, switch after the close job has run, or accept the new mode applying to it.
An account suspended after a card invoice was marked uncollectible stays suspended when you switch it to invoiced. Workforce Intelligence lifts that suspension only when the Stripe invoice that caused it is paid. The operator pages show a Suspended label on the account, but there is no operator control to suspend or reactivate an account.
Card billing#
Card billing is on only when central has a live Stripe key and its webhook secret. Without them:
- the account portal still works; customers see no card form, Add a card or card status, and an account with no billing is told to contact sales for invoiced billing;
- Card cannot be chosen for another account;
- month close still runs and finishes normally. Card accounts are skipped with a warning and nothing is charged. The dashboard card Card accounts not charged lists them, with a Change billing button to move them to invoiced;
- free and invoiced accounts are unaffected.
When a live key is added later, card billing turns on and existing accounts keep their modes.
What is recorded#
Each action is recorded, success or failure, without the code. The billing note is stored with the audit entry for the change and nowhere else; logs and account history record only whether a note exists and how long it is.
| Action | When |
|---|---|
operator_mode.unlock |
You unlock operator mode (a wrong code is recorded as a failure). |
operator_mode.exit |
You select Exit operator mode while it is on. |
free_account.create |
You create a free account. |
account.set_free_period |
You make an account free or change its period. |
account.clear_free_period |
You end a free period. |
account.claimed |
An owner confirms the email of a reserved account and is linked to it. |
account.set_billing_mode |
You change an account's billing mode or note. |
invoice.set_status |
You change an invoice's status. |
invoice.export |
You export the invoice CSV. |
account.clear_undeliverable |
You clear an undeliverable address (see Undeliverable email addresses). |