Invoices

Invoices makes, numbers and keeps the invoices and credit notes your businesses issue: from shop orders, typed by hand, arriving from outside systems, or re-billing supplier charges to a customer. Issued documents are never edited, only corrected or cancelled with a credit note, and their money reaches the books.

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

Every field on the page has an (i) that says what it is for. Invoices and billing parties also turn up in the app's quick search, which shows only what you may open.

Ideas you meet here

• Issuer: the business an invoice is issued by, with its own numbering (prefixes and number width), its jurisdiction and, for non-shop invoices, the entity in Books it posts to. Shops are linked to an issuer, which decides who invoices their orders.
• Billing party: who an invoice not made from a shop order is addressed to, such as "Acme Ltd". A draft copies the party's details as they are when it is made; changing the party later does not change drafts or invoices already made.
• Sources: Shop order (from a saved version of a shop order), Manual, External (from a connected system) and Re-billed usage (supplier charges passed on).
• Draft: an unnumbered invoice that can still change. Every change is kept as a revision.
• Jurisdiction: where a document is issued under. It comes from the draft's override, then the issuer's override, then the shop's base country. It is never guessed: with none, issuing is refused.
• Currency: any currency code the books know, including codes longer than three letters such as USDT.

What you see

• What invoicing can do right now: whether shop order versions are available, whether exchange rates exist for exports, whether invoices reach the books, and how many postings are waiting, refused, or refused because a month is locked.
• Reconciliation: what the hourly check found, such as an issued invoice the books hold differently or not at all, or a supplier charge not re-billed. Before anything has been issued it says "Nothing to check yet: no issued invoices."
• Invoices: every invoice with its number, status, issue date, source, order, customer and total in its own currency. Filter by source. People who may issue see Cancel… on issued invoices not made from shop orders.
• New invoice, Re-bill usage and Re-bill account, for people who may draft or manage.
• External sources, for people who may manage.
• Export, for people who may export.
• Issuers: each issuer, its numbering, its re-bill account and the shops it invoices for.

What you can do

Make an invoice by hand

1. In New invoice, pick the issuer and the billing party. Add party creates a new one and picks it for this draft.
2. Give the currency and, unless the issuer sets one, the jurisdiction (a country code).
3. Add lines with a kind, description, quantity and amount. Amounts are typed as text in the invoice's currency.
4. Choose Make draft. Nothing is numbered yet.

Make an invoice from a shop order

A draft is generated from one saved version of a shop order, in the order's own currency, through the API or an agent. No number is taken and nothing is posted. If the order changes later, the draft can be stood on the newer version; edits already made are kept in its revisions to re-apply.

Issue a draft

Issuing takes the next number in the issuer's series, freezes the jurisdiction and seller, renders the PDF, and posts to the books. It cannot be undone. Issuing is done through the API or by an agent with invoicing:issue, and every agent call to issue waits for a person.

Correct, cancel or credit an issued invoice

• Correct: prepare a replacement draft, then issue the correction. That issues a credit note cancelling the original in full and the replacement in its place, both numbered. An invoice can be corrected once.
• Cancel: for an issued invoice not made from a shop order, choose Cancel…, give a reason and choose Issue the credit note. It issues a cancellation credit note and reverses its entry. Shop-order invoices are corrected instead.
• Refund credit note: records a refund the shop already gave, as a numbered credit note. It posts nothing, because the books already have the refund from the order. Refunds reaching the invoice's total close it.

Re-bill supplier charges

1. Supplier charges allocated to a billing party in Bills wait to be passed on.
2. In Re-bill usage, pick the issuer and party and choose Show what is waiting.
3. Choose Make re-bill draft. There is one line per charge at its cost; change a price to add a margin. Charges in two currencies are never converted together: choose one.
4. Before any re-bill can be issued, set the issuer's Re-bill account: an income account books re-billed usage as revenue, or the expense account the cost sits in books it as a recharge of that cost.

Take invoices from an outside system

1. In External sources, add a source for an issuer: a JSON feed read every hour with its own sign-in, or a system that pushes documents.
2. Each new or changed document at the source is kept as a version and drafted. Nothing is issued until a person issues it.
3. Sync now reads a feed at once. A source can be switched off and on.

Export

In Export, choose a date range and download Invoices CSV, Totals per currency, Order versions CSV or PDFs (ZIP). Every amount stays in its document's own currency; you can add a converted column that names the rate used. Customer details are included only if you may see them.

Who sees what

You see an invoice if you may see the shop it came from. Customer details on shop-order documents need maxwoo:pii from Shops; customer details on other documents need invoicing:pii. Without them, names and addresses are masked. See Sharing and visibility.

Who can do what

Permission	Label	Lets you
invoicing:read	See invoices and credit notes (customer details also need maxwoo:pii)	Open Invoices, the status, findings, issuers, parties, revisions and postings. Agents need it for the read tools.
invoicing:pii	See customers on invoices not made from shop orders	See names and contact details of billing parties.
invoicing:draft	Make and change draft invoices	Make manual and re-bill drafts, generate drafts from orders, edit, rebase, set a draft's jurisdiction, discard, prepare corrections, and add or change billing parties.
invoicing:issue	Issue invoices, corrections and credit notes	Issue, issue corrections, issue refund credit notes, cancel, and retry postings.
invoicing:export	Export invoices and orders as CSV and PDF	Use Export and the export tools.
invoicing:manage	Set up issuers, their numbering, stores and jurisdiction	Create and change issuers, link shops, set jurisdiction and the re-bill account, archive parties, and manage external sources.

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

What runs on its own

Job	When	What it does
sources-sync	Every hour at minute 17	Reads every external feed that is switched on, saves new or changed documents as versions and drafts them. Nothing is issued.
ledger-catch-up	Every hour at minute 23	Sends the books every posting they have not taken yet, for example because no books were installed, a month was locked or a rate was missing. A document's date is never moved to make it post. Postings the books keep refusing are parked and show on the books' Waiting on the books list.
reconcile	Every hour at minute 47	Compares what was issued with what the books hold, and every supplier charge passed on with its re-bill, and records findings. Nothing is corrected automatically; a finding closes when what it names no longer holds, and is kept.

Needs

Nothing else must be switched on. To be useful it works with Books (where invoices post), Shops (shop orders and customers), Bills (charges to re-bill) and Accounts (exchange rates for converted exports).

How invoices reach the books

• A shop-order invoice posts only where it departs from the order it was made from. Shops already books the sale from the order itself, so an invoice that says the same posts nothing.
• A manual, external or re-billed invoice posts in full, to its issuer's entity, against a receivable kept apart from the shops'.
• Corrections and cancellations post the difference or reverse the entry. Refund credit notes post nothing.
• Re-bill drafts read supplier charges offered by Bills. Shop-order drafts read order versions from Shops.

For agents

An agent can read invoices and their state, draft and edit, issue, correct and cancel, export, and set up issuers, parties and sources.

This module handles money. When an agent calls a tool here that changes something, the call goes to a person for approval first, whatever the agent's policy says, 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.

Read only

• invoicing.status: whether invoices can be generated and reach the books, and what is waiting or refused.
• invoicing.invoices: invoices, newest first, 50 at a time.
• invoicing.invoice: one invoice with its lines, totals, jurisdiction and posting state.
• invoicing.revisions: a draft's history of changes.
• invoicing.creditNotes: credit notes, newest first.
• invoicing.creditNote: one credit note and where its money sits in the books.
• invoicing.postings: what was sent to the books, and what the books said.
• invoicing.findings: what the hourly reconciliation found.
• invoicing.issuers: issuers, their numbering and their shops.
• invoicing.parties: billing parties.
• invoicing.rebillable: supplier charges waiting to be re-billed to a party.
• invoicing.sources: the external source connections.
• invoicing.sourceRuns: a source's sync runs.
• invoicing.exportInvoicesCsv: issued invoices and credit notes for a date range, as CSV.
• invoicing.exportOrdersCsv: saved order versions for a date range, as CSV.

Draft (asks a person)

• invoicing.draftManual: a draft typed by hand for a billing party.
• invoicing.generateDraft: a draft from one saved order version.
• invoicing.draftRebill: a re-bill draft, one line per charge at its cost.
• invoicing.editDraft: change a draft's lines, customer or notes.
• invoicing.rebaseDraft: stand a draft on a newer version of what it was made from.
• invoicing.setDraftJurisdiction: override a draft's jurisdiction, with a reason.
• invoicing.discardDraft: discard a draft; nothing is deleted.
• invoicing.prepareCorrection: a replacement draft for an issued invoice.

Issue and credit (asks a person)

• invoicing.issueInvoice: number, freeze and post a draft. Spends.
• invoicing.issueCorrection: issue a full credit note and its replacement. Spends.
• invoicing.issueRefundCreditNote: record a refund already given, as a credit note. Destructive.
• invoicing.cancel: cancel a non-shop invoice with a cancellation credit note. Spends.
• invoicing.retryPostings: send postings the books have not taken. Spends.

Issuers, parties and sources (asks a person)

• invoicing.createIssuer: add an issuing business with its numbering.
• invoicing.updateIssuer: change an issuer; numbering is fixed once it has issued anything.
• invoicing.linkStore: say which issuer invoices a shop's orders.
• invoicing.unlinkStore: stop invoicing a shop under an issuer. Destructive.
• invoicing.setIssuerJurisdiction: override an issuer's jurisdiction, with a reason.
• invoicing.setRebillAccount: choose the account an issuer's re-bills credit.
• invoicing.createParty: add a billing party.
• invoicing.updateParty: change a party's details.
• invoicing.archiveParty: archive a party. Destructive.
• invoicing.syncSource: read a JSON feed now. Reaches outside.
• invoicing.updateSource: switch a source 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 invoicing__invoices and so on (API keys and MCP access).

Related

• Money
• Books
• Bills: supplier charges to re-bill.
• Shops: orders and customer details.
• Sharing and visibility