Read me first

If you have just been handed this project and have no idea what it is, start here. Everything below is in plain English. There is no code on this page, and where a word belongs to the trade it is explained the first time it appears.

Part of the worlds-biggest-software-project initiative.

---

1. Who this is for

Four kinds of people, sharing one system.

The person who decides prices. Usually in product or revenue operations. They decide what the company sells and what it costs, and until now they have had to ask an engineer every time they wanted to change it. This system is built so they do not have to.

The person who sends the bills. Finance. They check what is about to go out, send it, chase the ones that do not get paid, and answer for the numbers when somebody asks where they came from.

The engineer who connects it. They wire their company's product into this system so that every time a customer uses something, this system hears about it. They mostly want to be sure the numbers arriving are the numbers they sent.

The customer being billed. They sign in occasionally with a question: what did I use, what am I being charged, and how much credit do I have left.

If you are none of these — an owner, an investor, someone evaluating the project — sections 2, 3 and 4 are written for you and the rest can be skimmed.

---

2. What it does

Some companies charge a flat monthly fee. Others charge for what you actually use — per message sent, per gigabyte stored, per thousand words an AI model processes. This system is for the second kind, and for the many companies that do both at once.

It does four things:

1. Counts. The company's product tells this system, continuously, what each customer is doing. Ten thousand of those messages a second, if needed.
2. Prices. Somebody has set up what things cost. The system applies those prices to what was counted, and can tell you the answer at any moment — not just at the end of the month.
3. Bills. At the end of each period it produces an invoice, works out the tax, tries to collect the money, and chases the payment if it fails.
4. Explains. Every figure it produces can be opened up to show exactly how it was arrived at, and it keeps a permanent record of who changed what.

The fourth one is the point. Plenty of software can do the first three.

---

3. The domain

How software companies charge, and why it changed

For twenty years, business software was sold by the seat. A hundred employees, a hundred licences, a predictable bill every month. Simple to sell and simple to bill, which is why almost all billing software was built around it.

That model has been quietly falling apart. When a company sells access to a service rather than a desktop program, seats stop describing the value. A customer with five employees might hammer the service a million times a day; one with five hundred might barely touch it. Charging both the same is unfair to one of them, and leaves money on the table with the other.

So companies moved to charging for consumption. Roughly two thirds of software companies now bill on usage or on a mixture of usage and a base fee, up from under half five years ago. Artificial intelligence accelerated it: the cost of answering a question genuinely varies with the question, and nobody can sell that sensibly as a flat monthly fee.

Why that is hard to get right

Counting sounds easy. It is not, for four reasons that only appear at scale.

Things get counted twice. When a computer sends a message and does not hear back quickly, it assumes the message was lost and sends it again. Often the first one arrived. Get this wrong and you bill customers for things they did not do — and worst of all, you do it most when your systems are already struggling.

Money has to be exact. Not nearly right. If the lines on an invoice do not add up to the total, precisely, somebody will notice, and everything else you tell them becomes suspect.

Prices change, but old agreements should not. When a company changes its prices, existing customers were sold something specific and are entitled to keep it. A system that re-prices everybody the moment somebody edits a price is a system nobody will touch.

Accountants have rules. There are international standards governing when a company is allowed to count money as earned. Take a year's payment up front and you have not earned it yet — you have taken on an obligation. Getting this wrong is not a bug; it is a misstated set of accounts.

The words people use

The trade has some jargon. There is a glossary at the end of this document; you do not need it yet.

---

4. Where it fits

This system sits in the middle of a company's plumbing, and it never works alone.

On the way in is the company's own product — the thing customers actually use. It reports what each customer is doing, and that stream of reports is what everything here is built on. Nothing else needs to change about that product.

On the way out are three destinations. Money goes to a payment provider, which holds the customers' card details so this system never has to. Figures go to an accounting system, where the company keeps its official books. And notifications go back to the company's own systems, so they can react when a payment fails or a customer runs out of credit.

Alongside it are the people. The pricing team and the finance team work in it directly, through a web interface. The customers being billed get their own smaller, separate view showing only their own account.

The typical customer here is a software company somewhere between its first serious revenue and its first serious finance department — big enough that spreadsheets have become dangerous, not big enough to justify a six-figure enterprise billing platform and a year spent installing it.

---

5. First run

The quickest way to understand this system is to run it and look at it.

The project ships a preview — a single self-contained package that includes the software, its database, and a set of realistic example data already loaded. It needs nothing else installed and nothing configured. One command starts it; the exact command is in the preview folder's own instructions.

It takes about five seconds to start. Then open it in a browser.

The very first thing to do: find the list of invoices, open one, and click on a line that says how this was computed. You will see the arithmetic behind the charge — the quantity, the rate, which price band each part fell into, the tax rule applied, and the date that rule came into force.

That is the whole product in one click. If you understand why that matters, you understand why this exists.

After that, wander. The example data includes four customers, two company entities billing in different currencies, a customer on a free trial, and one who has not paid. Nothing you do to the preview matters — close it and everything resets.

---

6. Setting up

Moving from looking at it to using it has four stages. Expect the first two to be quick and the third to involve the engineers.

Stage one — stand it up properly

The preview throws its data away. A real installation needs a proper database that keeps things. This can run on the company's own machines, if there are rules about where data may live, or it can be run for you. It is the same software either way.

Stage two — say who you are

A short setup step creates the company's billing identity: its legal name, the currency it bills in, and the time zone its months run to. That last one matters more than it sounds — it decides whether something that happened late on the 31st belongs to this month or the next.

You also load the tax rates for wherever you bill. The system will not guess these, deliberately. If you try to bill somewhere you have not set up a rate for, it stops and says so rather than quietly charging nothing.

Stage three — connect the product

This is the engineering part, and it is smaller than people expect. The company's product needs to send a short message every time a customer does something billable. There are two things to get right, and the guides cover both. It is usually a few days of work, not a project.

Before those messages arrive, somebody defines what is being counted: a name for each countable thing, and any extra labels the company wants to break it down by. Those labels have to be declared in advance — an unexpected one is refused rather than silently invented.

Stage four — set up what you sell

Now the pricing person takes over, and needs nobody's help. They create the products, the plans, the price bands, and put customers on them. Building a plan with a monthly fee, tiered usage charges and an optional add-on takes under a quarter of an hour.

Finally, hand out access. Each service that sends usage gets its own key, and each key is shown exactly once when it is created — write it down then, because it cannot be recovered afterwards.

---

7. Day to day

What routine use actually looks like, by person.

The pricing person — occasional, in bursts

They come in when something is being changed: a new plan, a new customer, a rate that needs adjusting.

The important habit is this. Editing a live plan never changes what existing customers pay. It creates a new version. Everybody already on the plan keeps what they were sold until somebody deliberately moves them. This means there is no such thing as a dangerous edit — the worst that can happen is an unused version cluttering the list.

Before a serious change, they can ask the system what a proposed price would have billed if it had been in force for the past year, using the company's own real usage. The valuable part is the per-customer breakdown: a change that looks like a modest increase overall is often an enormous jump for a handful of accounts, and those are the phone calls worth knowing about in advance.

The finance person — monthly, under pressure

Their month has a shape.

When a billing period closes, the system prepares each customer's invoice as a draft. Drafts are not sent to anybody. There is then a short window before they go out automatically, and that window is doing real work: usage sometimes arrives late, and while an invoice is still a draft a late arrival just gets folded in.

During the window, finance reviews the drafts. Anything the system thinks looks unusual is flagged before the invoice goes out, not after. Any figure can be opened to show its workings.

Then they finalise. After that the invoice can never be changed by anybody — it takes a number, and the numbers run in an unbroken sequence. If a mistake surfaces later, the fix is a separate correcting document that refers back to the original, and the original stays exactly as issued. This feels rigid for about a week and then becomes the reason anyone trusts the numbers.

Later, they read the reports. There is one habit to learn here. When asking for a figure from a period that has already closed, the system makes you say which version you want: the number as it was reported at the time, or the number as it stands now taking later corrections into account. Both are correct, and they answer different questions. It refuses to guess, which is mildly annoying once and saves an argument later.

The engineer — after the first month, almost never

Once usage is flowing, there is nothing to do. They come back when the company starts counting something new, which means declaring it before the messages start arriving.

The customer — rarely, with a question

Three pages: what they used, their invoices, and their credit balance. Any answer is within three clicks of signing in, and they never see anything belonging to anyone else.

---

8. Ongoing care

Things that need doing periodically, roughly in order of how often.

Every month, at close. Review the drafts before they finalise. This is the only routine task with a deadline attached, and the deadline is visible on each draft.

Every month, after close. Check that what was billed matches what reached the accounting system. There is a view for exactly this, and when the two agree it reports nothing outstanding. Investigate anything it lists.

Whenever a tax rate changes. Add the new rate with the date it takes effect. Do not edit the old one — the system keeps both, applies whichever was in force on the day, and that is what lets an old invoice still be explained correctly years later.

Whenever somebody joins or leaves. Access is managed outside this system, through the company's normal sign-in. Worth reviewing periodically, particularly the split between who may change prices and who may send invoices, which the system deliberately keeps as two different jobs.

Whenever a service key changes hands. Keys can be withdrawn instantly, and a withdrawn key stops working on its very next use. Withdraw the old before you worry about the new.

Backups, continuously. This is a financial record. The expectation is that nothing is ever lost, and the recovery process should be rehearsed rather than assumed. Somebody should have actually restored from a backup and timed it.

Storage, occasionally. The detailed record of individual usage is kept for a set period and then cleared out; the totals, the invoices and the revenue figures stay forever. Worth knowing that the retention period also decides how far back you can replay history when testing a price change.

---

9. Glossary

Only the words you will actually meet.

Word	What it means here
Usage event	One report that a customer did something billable. "Customer 4471 used 18,450 tokens at 2:03pm."
Metric	A category of countable thing. "Tokens processed." "Messages sent."
Rating	Working out what some usage costs.
Plan	What you charge. May combine a fixed fee and usage charges.
Price band (or tier)	A rate that applies to part of the usage. "First thousand at a penny, everything after at half a penny."
Subscription	A particular customer on a particular plan.
Draft invoice	A bill worked out but not yet issued. Still changeable.
Finalised invoice	A bill that has been issued. Permanently unchangeable.
Credit note	The separate document used to correct a finalised invoice.
Proration	Splitting a charge fairly when something changes mid-month.
Prepaid credits	Credit a customer bought in advance, used up as they go. Can expire.
Account credit	Money you owe a customer, taken off their next bill. Never expires. Not the same as prepaid credits.
Dunning	Politely chasing a payment that failed.
Revenue recognition	Deciding when money you have received counts as money you have earned.
Entitlement	Whether a customer is allowed to use a particular feature. Kept separate from billing.
Legal entity	One of the company's registered businesses. Each has its own currency and its own invoice numbering.

---

10. The other documents

Document	For	What it covers
production-setup.md	Whoever installs it	Preparing a real system for first use, and the safeguards around it
Getting started, in plain English	New users	The screens, task by task, in the same register as this page
Detailed user guide	Regular users	Every screen, every field, every rule
Installation	Engineers	Standing it up, from preview to production
Integration guide	Engineers	Connecting the company's product to it
Architecture	Engineers	How it is built and why
Operations runbook	Whoever runs it	What to watch, what to do when something breaks
The white papers	Evaluators	Longer arguments about the hard parts, one per topic
Frequently asked questions	Anyone deciding	Direct answers, including where the answer is "no"

---

11. Who can do what

Three kinds of access.

Administrator — can do everything, including changing prices.

Finance — can review, send and correct invoices, and read every report. Cannot change prices. That restriction is the entire reason the role exists: the person deciding what a customer owes should not also be the person deciding what things cost. Every attempt is refused and recorded.

Customer — sees their own account and nothing else.

There is no password to set up here. Sign-in comes from the company's existing system, and roles are assigned there. Services that send usage data use their own keys rather than pretending to be a person.

---

12. The example data

The preview arrives with a small, deliberately realistic set of information: four customers, two company entities billing in different currencies including one in Japanese yen, a subscription on a free trial, one that has not been paid, prepaid credit balances, several invoices with one already corrected by a credit note, and a hundred usage events already counted and priced.

It is there so every screen has something on it. None of it is real, and it is kept entirely separate from the process that sets up a genuine installation — the two share nothing, so example data cannot leak into a real system by accident.

To start fresh: stop the preview and start it again. It keeps nothing.

A real installation starts genuinely empty, on purpose. No example customers, no example plans. An empty catalogue is the correct beginning, and inventing something to make a screen look busy is exactly how fake data ends up in real accounts.

---

13. Things that confuse people once

A repeated message is not an error. If the company's product sends the same usage report twice, the system says "already have that one" and counts it once. That is a success.

Usage during a free trial is counted and priced, but not charged. Deliberately — it shows the customer what they would have paid, which is the most persuasive thing you can show them.

Usage while an account is paused is still recorded. It just does not appear on any bill. It happened; hiding it would be untrue.

Finance genuinely cannot change prices. Not an oversight.

No tax rate means an error, not zero tax. If you bill somewhere you have not configured, the system stops. "Nothing" and "we don't know" are different answers and it will not confuse them.

Prepaid credits and account credit are two different things. One is what the customer bought; the other is money you owe them. They behave differently and are shown separately, always.

Reports ask you which version of a figure you want. Not a bug. See section 7.

The system will not invent a tax rate, an entity name, or a currency. Anything with a legal or commercial consequence has to be stated by a person.

---

14. Honest limits

Worth knowing before anyone builds an expectation on it.

• It has no formal certifications. It produces the records, schedules and audit trails the accounting standards call for, but it has not been audited or certified against them, and no security certification forms part of this build.
• It calculates tax; it does not file it. Rates are ones you configure. Submitting returns is somebody else's job.
• It serves one organisation per installation. It can handle several registered businesses within that organisation, in several currencies, but it is not a system for running many separate companies from one copy.
• It does not handle card details. A payment provider does that, and the system only ever holds a reference.
• Its suggestions are only ever suggestions. Nothing the artificial intelligence proposes takes effect without a person approving it, and switching that capability off entirely leaves the billing working exactly as before.
• This is a core build. It works correctly and it is deliberately plain — no branding, no styling, nothing tailored to any particular company. That is where customisation starts.

---

15. Getting help

Come to wbsp.ai.

This project is one of many built by the community there. If you want this shaped into something specific to your business — your branding, your workflows, features that do not exist here yet — that is where the people who do that work are.

It is also worth a browse before you commit to anything. Somebody may already have built a version much closer to what you need than this one.

---

Nothing in this document is legal, tax or accounting advice.