# invoicing (Agent Skill)

> VAT invoicing in a Next.js app: gapless numbers per series and year, invoices from a sale or standalone, correcting invoices, a register, an A4 PDF, and an optional bridge to KSeF.

Page: https://timerise.ai/skills/invoicing

Agent Skill `invoicing`: https://github.com/timerise-ai/invoicing. Category: Payments & compliance. Runs on Next.js; backend: Postgres or in-memory behind a store seam; e-invoicing behind a port.

Latest release: v0.1.2 (2026-10-07).

Install: npx skills add timerise-ai/invoicing. Timerise builds it on a brief; the price comes from the brief.

A booking, rental or membership system that takes money has to hand the buyer a VAT invoice. Staff issue it from a sale or on its own, correct it when something was wrong, and download or e-mail it as a PDF.

The tax rules make three things hard. Numbers must run without gaps for each series and year, even when two people issue invoices at the same moment. An issued invoice must never change, so every mistake is fixed with a correcting invoice that cancels the original to the last digit. And the PDF must show every name and amount in full, however long.

This skill gives a coding agent the invoicing module the way we build it: the database stamps the number inside the write that creates the invoice, each invoice keeps its own copy of the seller and the buyer, nothing edits it after issue, and the PDF comes from a writer with no dependencies. In Poland it can also send each invoice to KSeF through our `ksef` skill.

Build a VAT invoicing module in a Next.js App Router app: gapless numbered invoices issued standalone or from a sale, correcting invoices with signed deltas, a register, and an A4 PDF rendered by a dependency-free writer, with an optional bridge that sends each document to KSeF through the ksef skill. Use when: (1) an app must issue invoices, credit notes or correcting invoices and print or e-mail them as PDF, (2) invoice numbers must be continuous per series and year under concurrent issuers, (3) an existing invoices module needs auditing: gaps in numbering, documents that change after issue, a PDF that cuts long names, (4) invoices must also go to KSeF as FA(3) with the KOD I code on the PDF, (5) the user mentions: invoice, faktura, faktura VAT, faktura korygujaca, correction invoice, credit note, invoice PDF, invoice number, gapless numbering, numeracja faktur, VAT summary, net and gross, NIP, invoice register, sales register, issue invoice from order, FA(3), KSeF, KOD I, QR on invoice. Carries numbering stamped inside the insert, one-transaction issue and correction, seller and buyer snapshots, database immutability triggers, symmetric rounding, a PDF writer with Polish diacritics and no font files, and the suites that hold them. Next.js App Router; the store, the auth guard, the seller profile and the e-invoicing port are seams, with Postgres and in-memory stores shipped. Not a payment processor, not subscription billing, not accounting or tax advice, and not the KSeF transport itself.

This skill is written by the engineer who has shipped this module, an invoicing section in a multi-tenant business application on Postgres. The templates hold these properties: a number is consumed only by a document that exists, a document and its lines are one write, an issued document cannot be updated or deleted, a correction's negated line cancels the original to the last digit, no text on the PDF is cut, and the verification code is never overprinted. Each is verified by the suites in `references/testing.md` and `references/testing-service.md` or by the database checks. The record of what the audit changed, what was kept and what is new is in [references/provenance.md](references/provenance.md).

What it builds:
- Gapless numbering per series and year stamped inside the insert
- Invoices issued standalone or from a sale
- Correcting invoices with signed deltas
- Seller and buyer snapshots
- Immutability after issue
- A register
- An A4 PDF from a dependency-free writer
- An optional bridge to KSeF through the ksef skill

When to use:
- A Next.js App Router app that sells something and must hand the buyer a VAT invoice: issued by staff in an admin area, standalone or from a sale, order or booking the app already holds; corrected when wrong; downloaded or e-mailed as PDF; and, in Poland, sent to KSeF.

Non-negotiables:
- Assign the number inside the insert. Never compute it in application code or a separate round trip: the counter must roll back with the document it numbered. The database checks refuse an insert and find the next document holding the number it would have had; twenty parallel issues produce twenty consecutive numbers.
- Write a document and its lines in one transaction , and a correction with the link on its original. A numbered document with no lines cannot be removed. `invoicing_create` is one call, and four parallel corrections of one document produce exactly one.
- Never update or delete an issued document. Both parties are snapshots, a mistake is fixed by a correction, and database triggers enforce it against any client. The checks try to edit a total, edit a line, delete a document and undo a payment.
- Take the tenant and the permissions from the server-side actor on every call. No route, action or store method accepts a tenant id from input. The service suite shows a second tenant nothing and lets it correct nothing.
- Compute every amount and every correction delta on the server , from the stored lines. The client sends lines and a corrected state, never totals or deltas. The model suite holds the arithmetic, including a negated line that cancels its original for fractional quantities.
- Let nothing fail the request once the document exists. A hand-off or audit failure is recorded and reported; an error would send the operator back to issue a second invoice. Two tests in the service suite fail the audit and the e-invoice hand-off and still receive the invoice.

Not this:
- Charging a card, a checkout, subscriptions, dunning: The payment provider's invoices, or [stripe-connect-subscriptions](https://github.com/timerise-ai/stripe-connect-subscriptions)
- Talking to KSeF: auth, encryption, sessions, UPO, purchase invoices: [ksef](https://github.com/timerise-ai/ksef); this skill builds the file and joins to it
- A general ledger, VAT returns, JPK files: An accounting system
- Deciding a rate, an exemption or whether to correct: An accountant; this skill covers the module, not interpretations of the VAT Act
- Fiscal receipts from a cash register: The fiscal device's integration

Requirements:
- A Next.js App Router app. The route template uses the promise form of `params` from Next.js 15 and 16.
- Postgres for production. The module runs on the in-memory store with no database, for tests and a first build only.
- No runtime dependency for the core module. The optional KSeF bridge needs `qrcode` and the [ksef](https://github.com/timerise-ai/ksef) skill.

Booking features we build with it:
- Invoices and e-invoicing: /features/invoicing

What to tell your agent:
- Add invoicing to this app: staff issue VAT invoices with numbers that never skip, can issue a correction when one is wrong, see them all in a list, and download each as a PDF.
- Our invoices need to go to KSeF. Build the FA(3) file for each invoice we issue and put the KSeF QR code on the PDF.
- Audit the invoices module in this app: can a number be skipped or used twice, and can an invoice change after it was issued?

Agent eval results (newest per agent and prompt):
- Claude Code (claude-opus-5-5) on v0.1.2, 2026-10-07: pass (No data store)
- Gemini CLI (gemini-3.8-flash) on v0.1.2, 2026-10-07: pass (No data store)
- Codex CLI (gpt-6.1-sol) on v0.1.2, 2026-10-07: pass (No data store)

Recent releases:
- v0.1.2 (2026-10-07): Fix release, from scoring the prompt-1 agent eval runs against 0.1.1.
- v0.1.1 (2026-10-06): Documentation-only release: the templates, the references' rules and the non-negotiables are unchanged from 0.1.0. Wording brought in line with the skill standard.
- v0.1.0 (2026-10-03): First release. A VAT invoicing module for a Next.js App Router app: numbering, corrections, a register, a PDF, and an optional bridge to the ksef skill.
