Bills

Bills keeps what you buy: the suppliers, the bills they send, what each line was for, what is still owed and how late, and the money you claim back when goods arrive damaged. The sidebar calls it Bills; the module is purchasing.

In the sidebar under Money → Bills. Handles money: when an agent tries to change anything here, a person is asked to approve it first (Agents and approvals).

A bill starts as a draft, which the books do not see. Issuing it tells the books you owe it, and from then on its figures stop moving: a mistake is put right by voiding it, which reverses what it posted. Amounts are kept per currency and never added across currencies. Every field has an (i) that says what it is for, and the app's quick search opens a tab of this page directly.

What you see

The page has a check against the books at the top and four tabs.

• Checked against the books: what the hourly reconciliation found, such as a bill or payment the books hold differently or not at all. Not compared counts what has not reached the books yet, including drafts nobody has checked. Nothing is corrected automatically.
• Bills: What is owed, per currency and never summed across currencies (a bill half paid is half owed); Late, worst first; and every bill, newest first, with its number, supplier, where it came from, issue and due dates, state and total. New bill drafts one.
• Damages: claims against suppliers and the money coming back. The tab counts the claims still owed to you.
• Suppliers: who you buy from. New supplier adds one; Archive retires one. Open a supplier to see everything that names it. Possibly the same supplier lists records that may be one company.
• Connections (for people who may connect): suppliers' billing accounts read automatically. The tab counts failing connections.

Opening a bill shows its lines, what each was broken down into and allocated to, its payments, and the actions for its state: Break down, What was it for, Issue, Record payment, Void and Ruined. Ruined appears only once the bill is issued.

A bill drafted by Bills inbox from an email says Drafted from email, not yet checked by a person until somebody saves or issues it, with links to The email and The file it was read from.

Where bills come from

• Typed in with New bill.
• Read from an email by Bills inbox: clean invoices from approved senders become draft bills by themselves.
• A supplier's connected billing account (see Connections).
• Contabo: a monthly draft bill that divides each server's price between its projects.
• Books → Orders, when you add a cost against orders.
• Supplier orders, which can draft the bill for an order.

What you can do

Add a supplier

1. Open Suppliers and choose New supplier.
2. Give its name, the currency its bills default to, its payment terms and contact details.
3. Press Add. A supplier named by a bill is never deleted, only archived, so the books never point at a counterparty nobody can name.

Merge two suppliers that are one company

1. Open Suppliers. Possibly the same supplier lists pairs with the same name, or the same email domain and a near name. You can also propose a pair yourself.
2. Choose Merge to keep one: the other's bills and claims move to it and the other is archived. Choose Keep apart to dismiss the proposal.
3. A merge can be undone for 30 days: choose Undo, and exactly what it moved goes back. A merge is refused when both suppliers have a bill with the same number.

Record a bill

1. Open Bills and choose New bill.
2. Pick the supplier, then enter their number, the Issued on day and one line: what it was for, a description and the amount. The currency defaults to the supplier's. The due date follows from the supplier's terms; a supplier with no terms gives a bill with no date agreed.
3. Press Record. It is a draft: nothing reaches the books yet.

Say what a line was made of and what it was for

1. On the bill, choose Break down to split a line into its parts, such as goods, packing and carriage. The bill total does not move.
2. Choose What was it for to allocate a line to the things it belongs to: shop orders, servers in the Infrastructure map, projects, or a billing party in Invoices to pass the charge on. Split it equally, by what each was worth, or by how many items. What was it for shows only on a line that has not been broken down. Once a line has parts, the parts are what get allocated, and that is done by an agent or the API, not on screen.
3. Allocated costs carry the order's or target's own key into the books, so profit per order reads them.

Issue, pay or void a bill

1. Choose Issue. The books are told the business owes it, and the bill's figures stop moving.
2. Choose Record payment to record money paid against it, from a vault or an account. What is owed falls.
3. Choose Void to cancel a bill. Whatever it told the books is reversed.

Claim for damaged goods

1. On an issued bill, choose Ruined on the line that arrived damaged, short, wrong or late. Say what happened and how much you are asking back.
2. On the Damages tab, choose What it ruined to say which orders the loss spoiled, so they carry it.
3. When the supplier agrees, choose They agreed and enter the amount agreed. When the money arrives as a credit note, a refund or a replacement, choose Money came back.
4. If the supplier says no, choose They said no. If you stop pursuing the claim, choose Stop asking.

The loss is booked the day it is found. The claim itself books nothing, because nobody has agreed to anything yet. The recovery is booked when the supplier agrees, at the amount agreed, never the amount asked.

Connect a supplier's billing account

1. Open Connections and choose Connect.
2. Choose the provider (DigitalOcean billing is the one built in), the supplier, and paste a read-only token. The token is sealed when saved and never shown again.
3. Each invoice from the provider arrives once, as a draft bill. Issuing it is still yours to do.
4. Sync now reads the provider at once. There is no button to switch a connection off or on; an agent or the API does it.

Enter a cost from the orders it was for

From Books → Orders, tick orders and add a cost. That drafts a one-line bill, allocates it to those orders, issues it and, if you say so, records it as already paid from a vault.

Who can do what

Permission	Label	Lets you
purchasing:read	See suppliers, bills and what is owed	Open Bills, see suppliers, bills, claims, aging, findings, merge proposals and the books status. Agents need it for the read tools.
purchasing:write	Add suppliers and draft bills	Add, change, archive and merge suppliers, draft bills, break down and allocate lines, and enter costs from orders.
purchasing:issue	Issue a bill, which tells the books we owe it	Issue and void bills.
purchasing:pay	Record money paid against a bill	Record payments and settle claims.
purchasing:claim	Record a damage and claim the money back	Raise, allocate, accept, reject and withdraw claims.
purchasing:connect	Connect a supplier's billing account	Open Connections, connect, sync, switch off or archive a connection.

Roles and how permissions are granted are explained in People, roles and permissions.

What runs on its own

Job	When	What it does
connections-sync	Every hour at minute 29	Reads every supplier connection that is switched on. New bills land as drafts; nothing is issued, paid or posted.
ledger-catch-up	Every hour at minute 41	Sends the books every bill, payment and claim entry they have not taken yet.
reconcile	Every hour at minute 53	Compares each issued bill and payment with what the books hold, and records findings. A finding closes when the books agree again, and is kept.

Needs

Nothing else must be switched on. Bills posts to Books, pays from Vaults and Accounts, and offers charges to Invoices when those are on.

How bills reach the books

• Issuing a bill books the cost against what is owed to the supplier. Each line books to its part's account and carries the key of whatever it was allocated to.
• A payment books money out of the vault or account it came from against what is owed. A payment in another currency than the bill's balances in each currency.
• Paying from a vault books against that vault's account in the books, but does not record a movement in Vaults: the vault's balance there changes only by a movement recorded in Vaults.
• A damage books the loss; an agreed claim books the expected recovery; a settlement books the money that came back.
• The supplier decides whose books it goes to, through the links in Books, or the default entity.
• Lines allocated to a billing party are offered to Invoices to re-bill.

For agents

An agent can read what is owed, manage and merge suppliers, draft, allocate, issue, pay and void bills, handle damage claims, and run supplier connections.

This module handles money. When an agent calls a tool here that changes something, the call goes to a person for approval first, unless its policy denies it outright, and no per-tool rule can set it to allow. Reads follow the agent's policy as usual. A person working in the app, or an API key somebody set up, is not held by this rule: their permissions decide. Tools marked spends or destructive below can never be allowed without asking, and purchasing.decideMerge always asks a person.

Read only

• purchasing.overview: what is owed and what is being claimed, per currency.
• purchasing.aging: what is owed and how late, bucketed per currency.
• purchasing.ledgerStatus: whether bills and claims have reached the books.
• purchasing.findings: what the hourly reconciliation found.
• purchasing.suppliers: the suppliers, archived ones on request.
• purchasing.supplier: one supplier with its terms, currency and contacts.
• purchasing.bills: bills, by supplier, status or due date.
• purchasing.bill: one bill with its lines, allocations and payments.
• purchasing.claims: claims against suppliers.
• purchasing.claim: one claim with what it was for and what it ruined.
• purchasing.costTargets: the kinds of thing a cost can be allocated to here.
• purchasing.findTargets: search things of one kind to allocate a cost to.
• purchasing.mergeProposals: suppliers that may be one company, open and decided.
• purchasing.connections: suppliers' connected billing accounts and their health.
• purchasing.connectionRuns: a connection's sync runs.

Suppliers and bills (asks a person)

• purchasing.createSupplier: add a supplier with its default currency and terms.
• purchasing.updateSupplier: change a supplier.
• purchasing.archiveSupplier: archive a supplier.
• purchasing.proposeMerge: say two suppliers are one company. Moves nothing.
• purchasing.decideMerge: merge or dismiss a proposal. Always asks.
• purchasing.undoMerge: take a merge back within its 30 days.
• purchasing.draftBill: draft a bill a supplier sent.
• purchasing.breakDownLine: say what a line was made of.
• purchasing.allocateLine: say what a line was for.
• purchasing.issueBill: issue a drafted bill to the books. Spends.
• purchasing.voidBill: void a bill, reversing its entries. Destructive.
• purchasing.payBill: record money paid against a bill. Spends.
• purchasing.costOrders: enter a cost from the orders it was for, as a one-line bill. Spends.

Damages (asks a person)

• purchasing.raiseClaim: book a loss and what is being asked back. Spends.
• purchasing.allocateClaim: say which orders the loss spoiled.
• purchasing.acceptClaim: the supplier agreed; book the recovery. Spends.
• purchasing.rejectClaim: the supplier said no.
• purchasing.withdrawClaim: stop pursuing; reverse any recovery. Destructive.
• purchasing.settleClaim: the money arrived. Spends.

Connections (asks a person)

• purchasing.syncConnection: read a provider now; new bills land as drafts. Reaches outside.
• purchasing.updateConnection: switch a connection off or on, rename or archive it. A new sign-in is given by a person, never through a tool.

Over MCP the same tools are named purchasing__bills and so on (API keys and MCP access).

Related

• Money
• Books
• Bills inbox: invoices read from email.
• Invoices: re-billing charges to customers.
• Supplier orders
• Shops: orders that costs are allocated to.
• DigitalOcean