Core concepts

A few ideas run through the whole product: who owns what, how a document moves from draft to paid, why sent documents never change in place, and how the same action works in the web app, the API, the MCP server and the AI agent. Reading this page once makes every other page easier.

The hierarchy

Account   (Free or Team; members with roles; billing)
  └── Business   (1 to many: the entity that issues documents)
        └── Client   (receives documents; never has a password)

Account

An account is your workspace. It holds your businesses, your members and your billing, and it is on one plan: Free or Team. When you sign up, a new account on the Free plan is created with you as its Owner.

One login can belong to many accounts. You can own your own account and be a member of someone else's at the same time, each with its own role. The account and business switcher at the top of the app lists everything you can reach. Permissions, plan limits, billing, branding and the audit log always follow the account you are looking at, never the person.

Business

A business is the person or company whose name is on the invoice. Each business has its own profile and logo, its own gap-free numbering, tax rates, payment methods and templates. You can have as many businesses as you like on every plan, which suits people who run more than one company or trade under more than one name. See Businesses.

Client

A client is who you bill. Clients belong to a business and can have several contacts. Clients never have a password: they open documents from a secure link, and from January 2027 they can open a magic-link client portal with all their documents for that business. See Clients and contacts.

Members

People who work in an account are members. Each member has a role and, below Owner, a business scope (all businesses or a list). On Free an account has the Owner plus one free view-only Accountant. Team adds more members and editable roles. See Members and invitations.

Documents

Everything you send is a document. They share one line model, one money engine and one set of rules.

Each type has its own gap-free number sequence per business, for example INV-2027-0001 and CN-2027-0001. A number is given on first send and never reused or skipped. See Document numbering.

Statuses

A document's status tells you what needs doing. The main ones:

See Document statuses for what moves a document from one status to another.

Drafts and sent documents

A draft is private and flexible. It has no number, you can change anything, and you can delete it.

When you send a document for the first time, three things happen: it gets its number, a snapshot of exactly what you sent is stored, and its status becomes sent. From then on the document is a record your client has seen, so it is protected:

• A sent document is never edited in place. A change creates a new revision with its own snapshot, and the earlier versions stay readable. What your client received is always on record. See Revisions.
• A sent document is never deleted. A sent invoice you no longer want is voided with a reason: it keeps its number and shows a VOID stamp. An invoice that already has payments cannot be voided; you issue a credit note instead. See Void and delete and Credit notes.

Paid means paid

An invoice is marked paid only from a trusted event:

• a verified payment confirmation from the payment provider (for example Stripe);
• a reconciliation run that checks the provider directly;
• a person in your account recording the payment, which is written to the audit trail.

A client being sent back to the pay page after checkout is never enough on its own, and neither is a client clicking "I have paid" for a bank transfer. This is why you can trust the word "paid". See How payments work.

Capabilities and surfaces

Every action in the product, such as "create an invoice" or "void a document", is defined once as a capability: its inputs and outputs, the permission it needs, whether it is read-only or destructive, and a preview of what it would do.

From that one definition come:

• the web app screens;
• the REST API route under https://api.freeinvoiceautomation.com/v1;
• the MCP tool your AI assistant calls (for the actions on the MCP tool list);
• the CLI command (from late January 2027);
• the tools the in-app AI agent uses;
• the actions the Shopify app and WordPress plugin call.

So no feature exists only in the web UI, and every surface follows the same rules and permissions. If you can do it in the app, you can do it through the API.

Drafts first, confirmation for anything risky

Integrations, MCP clients and the AI agent create drafts. Sending needs a person to confirm, unless you deliberately created an API key or automation in auto_send mode. Destructive or money-moving actions, such as voiding an invoice or issuing a credit note, always need confirmation: a dialog in the app, or "confirm": true in the API and MCP. Without it you get a preview and the error confirmation_required. See Drafts and confirmations.

Permissions

Each capability needs one permission key named module.action, for example documents.send, documents.void or payments.record. A role is a list of keys.

• Every account has an Owner, who holds every key and cannot be edited or removed.
• Preset roles Admin, Editor, Viewer and Accountant come with sensible defaults. On Team you can edit them or create custom roles.
• Nobody can give a permission they do not hold themselves.
• API keys and MCP tokens carry scopes from the same list, and at each call they can do only what both their scopes and their creator's current permissions allow.

The same check runs in the app, API, MCP, CLI and AI agent, and the app hides what your role cannot do. See Roles and permissions and Permission keys.

Money as minor units

Money is always stored and sent as a whole number of minor units plus a currency. Minor units are the smallest unit of the currency, such as cents for USD.

{ "total_minor": "120000", "currency": "USD" }

This means 1,200.00 USD. In the API the number is a string, so no language or tool can turn it into a rounded floating-point value; floating-point amounts are rejected. All calculations (line totals, taxes, discounts, exchange rates) happen in one engine, so totals match to the cent everywhere: in the generator, the app, the PDF and the API. When an invoice is in a different currency from the business's base currency, the exchange rate is frozen on the document. See Money and currencies and Currencies and exchange rates.

Links your clients open

Pay pages, estimate pages and portal links use secure tokens: random, stored only in hashed form, made for one purpose, expiring and revocable. Voiding an invoice cancels its pay link. Pay, portal, pay-me and verification pages carry no ads and no analytics. See Share links.

Related