# Monthly documents

> One document per seller and month for every company with its data in. The overview on Free, the voucher with the tax note on Books. Numbered, chained and never changed.

Hundreds of small payments to one seller make one document a month. Usually it is our record for the buyer: who was paid, for what, how much in USDC and EUR, not an invoice of the seller. Where the seller is on level 3 or agreed to self-billing, the month gets an invoice in the seller's name or a credit note instead, see [Invoices and credit notes](#invoices-and-credit-notes).

## Overview or voucher

The plan decides which document a month gets.

| Plan | Document | Number | What it adds |
|---|---|---|---|
| Free | Monthly overview | `U-…` | Lines, totals, rates and every payment. No tax note, not a voucher for bookkeeping |
| Books and up | Voucher (Eigenbeleg) | `B-…` | The same, plus why it is a voucher and the tax note for your company |

A paid plan counts for every month it ran into. Upgrade later and a month that already has an overview can be cancelled and issued again as a voucher.

## Invoices and credit notes

Three ways lead to a month's document, the run takes the best one the seller allows:

| Way | When | Document | Number |
|---|---|---|---|
| A, mandate | The seller's listing is on level 2, it signed the invoicing mandate and has Books | Invoice in the seller's name, issued by 402lounge | `L-…` |
| B, self-billing | The listing is on level 2 and the seller agreed to self-billing | Credit note (Gutschrift) of the buyer, prepared by 402lounge | `G-…` |
| C | Otherwise | Voucher or overview, as below | `B-…`, `U-…` |

A and B need a buyer on level 3 (VAT ID confirmed by VIES) in the EU with Books or Books for teams, and payments to wallets of the listing that proved themselves. The tax case follows the seller and the buyer:

| Seller | `tax_case` | On the document |
|---|---|---|
| Germany, charges VAT, buyer in Germany | `domestic_19` | 19 % VAT, worked out of what was paid |
| Germany, small business, buyer in Germany | `domestic_small_business` | No VAT, with the note on § 19 UStG |
| In the EU, buyer in another state | `eu_reverse_charge` | No VAT, both VAT IDs, "Reverse charge" with the term of the state whose rules apply |
| Outside the EU, buyer in the EU | `third_country_reverse_charge` | No VAT, the seller's tax id, the same mention |

Whose invoicing rules apply follows Art. 219a of the VAT Directive: the seller's state for an invoice with a mandate and an EU seller, the buyer's state for a seller outside the EU and for every credit note. The document names that state. The buyer's state is where the VAT is owed (Art. 196), and § 13b UStG appears only when the buyer is in Germany. A seller and a buyer in the same state outside Germany get the voucher, that case is not built yet. Credit notes go to buyers in twenty states, not yet to Italy, Hungary, Poland, Romania, Greece, Croatia and Portugal. A month up to 250 € gross for a German seller and a German buyer is a small amount invoice (§ 33 UStDV) and says so. Every invoice and credit note has its e-invoice under EN 16931 (UN/CEFACT CII D16B): `GET /v1/invoices/{id}/xml`. It lies in the archive next to the JSON and the PDFs, in the ZIP export, and the month CSV names it in the column `einvoice`. A document whose e-invoice does not pass our check is not issued. The seller sees every invoice in its name with `seller.invoices`, and its documents carry a second chain, `seller_prev_sha256`, from one invoice of the seller to the next.

Cancel an invoice or credit note like any document. Its cancellation (`S-…`) is in the seller's range and its e-invoice is a credit note that names the original. The month is then issued again. A late payment gets a supplement in the way that applies at that time.

## The tax note

The voucher picks its note from the company's country and `vat_status` (see [Companies](https://402lounge.com/docs/companies.md)). Tax notes are written for companies in Germany.

| Company | `tax_case` | What the note says |
|---|---|---|
| Germany, `vat_id` or `tax_number` | `rc_13b` | The buyer owes the VAT under § 13b UStG and deducts it where entitled |
| Germany, `small_business` | `rc_13b_small_business` | The buyer owes the VAT under § 13b UStG and cannot deduct it |
| Germany, `exempt` | `rc_13b_exempt` | The buyer owes the VAT and deducts it only as far as its sales allow |
| Germany, no status | `rc_13b_status_missing` | The status is missing and the deduction depends on it |
| Outside Germany | `not_germany` | No tax assessment, only the payments and the EUR values |

Every note also says what changes if the seller turns out to be established in Germany, and that EUR values are provisional until the tax adviser confirms them. This is not tax advice. Your tax adviser decides how you book it.

## When documents are issued

Every night at 03:15 UTC the run looks at last month (Europe/Berlin) and issues documents for every company on level 2 or 3 that has payments no document lists yet. The first night after a month issues it. A company whose agents reported payments the chain has not shown yet waits one more night. Companies on level 1 keep their receipts but get no documents, because a document names the buyer with its address and a confirmed email.

An admin, owner or finance can issue any finished month with `invoices.issue {month: "2026-10"}`. Receipts that still lack a EUR rate are skipped and listed in the answer. A month with more transactions than the plan covers is skipped with `month_locked` until the plan fits, see [plans and their limits](https://402lounge.com/docs/errors.md#plans-and-their-limits).

## The month so far

`invoices.draft {month?}` shows what the run would issue today, one draft per seller, with lines, totals and the tax case. Nothing is stored and there is no number. Without `month` it shows the current month. Each draft has a PDF at `GET /v1/invoices/draft/pdf?month=2026-11&seller=<key>`.

## Cancel and issue again

A document is never changed. If one is wrong, an admin, owner or finance cancels it with `invoices.cancel {id, reason}`. That issues a cancellation (`S-…`) that names the original with its sha256 and shows its amounts with a minus sign. The original keeps its number and turns to `cancelled`. Its payments are open again, so `invoices.issue` for that month, or the nightly run for last month, puts them in a new document with the current data.

## Late payments

Payments that arrive after a month was issued get a supplement: a document of the same kind for only the new payments, pointing to the month's first document with `supplement_of`. The first document stays valid.

## What a voucher holds

- The buyer with its address and VAT id, and the seller as the register knows it
- One line per endpoint: what was bought, how many calls, USDC and EUR
- Every receipt behind the lines, with its transaction hash
- The conversion method and the note that EUR values are provisional
- The tax note for the company, as above

## How long we keep them

As long as your company has a paid plan or the archive (5 € a month or 50 € a year, [Paying 402lounge](https://402lounge.com/docs/billing.md#the-archive)), its receipts and documents stay. Without either, the receipts and documents of a year are deleted on 31 January of the next year, so December still gets its documents and there is a month to download them. When a paid plan or the archive ends, at least 30 days pass before anything is deleted, and a notice comes on 1 December and on 15 January. Invoices and credit notes in a seller's name are the seller's records too: while the seller keeps its own, they stay for the seller when yours go, and you no longer see them. `company.get` shows the next date in `retention`. Your company keeps its own duty to retain its records, eight years in Germany and up to eleven years elsewhere in the EU, so download them with `GET /v1/company/export`, book the archive or keep a paid plan.

## Numbers and integrity

Every document has a number like `B-2610-10427-01`: a letter for the kind (B voucher, U overview, S cancellation, L invoice in the seller's name, G credit note), year and month, the seller's own number, and the count of that seller's documents of this kind in the month, nearly always 01. Every seller keeps its number, 4 or 5 digits, a wallet no listing claims gets one too. The numbers run per issuer: the buyer's vouchers, overviews and credit notes in its own range, invoices in the seller's range. Documents issued before 3 November 2026 keep their old numbers like `402B-northpine-2026-000017`.

A document carries the logo of whoever issues it, as it was on that day: the buyer's on vouchers, overviews and credit notes, the seller's on invoices in its name. Upload it with `PUT /v1/company/logo` as PNG or JPEG. A later logo never changes an issued document. A document is never changed after it is issued. Each one carries a sha256 of its content, chained to the company's previous document, so a gap or an edit would show. Documents of one company are issued one after the other, so the chain never forks.

## Read them

- `invoices.list {month}`: the documents of the company, newest first, with `kind`, `status`, `cancels_id` and `supplement_of`.
- `invoices.get {id}`: one document as JSON, by id or number, with `prev_sha256`.
- The PDF: `GET /v1/invoices/{id}/pdf` with the session token, in English, or German with `?lang=de`. Names in letters the PDF font lacks are written in Latin letters, the JSON keeps them as they are.
- The archive: when a document is issued, its JSON and both PDFs go into an archive in the EU. The files are never overwritten. Every download is that archived file, and its sha256 comes in the `X-Archive-SHA256` header.
- Everything at once: `GET /v1/company/export` returns a ZIP with every document, all receipts as `receipts.csv` and an index `documents.csv`. Your company keeps the duty to retain its records, and this file lets it do so on its own.

## Export for the books

From Books on, every finished month comes for the books in two forms. Admins, owners, finance and the adviser call `GET /v1/invoices/export?month=2026-10` with `format=csv` or `format=datev`. A locked month is not exported. The ZIP of `GET /v1/company/export` holds both files for every month the plan covers, under `exports/<month>/`.

**CSV:** one line per line of a document, with the number, kind, status, seller, level, description, calls, USDC and EUR, the rate in USD per EUR, the conversion method, the tax case and the sha256. A cancellation is one line with its amounts as a minus, so the month adds up. Overviews are listed, supplements name their first document in `supplement_of`. UTF-8, comma separated.

**DATEV:** a Buchungsstapel in the DATEV format (EXTF, version 700, category 21, format version 13), Windows-1252, semicolon separated, for the import into DATEV Rechnungswesen. Two bookings per voucher, both on the last day of the month with the document number in Belegfeld 1:

| Booking | Konto | Gegenkonto | BU-Schlüssel |
|---|---|---|---|
| Expense to the clearing account | SKR03 4900, SKR04 6300 | SKR03 1360, SKR04 1460 | 94 (§ 13b, 19 %), 95 for small businesses and exempt sales |
| Clearing account to the USDC holding | SKR03 1360, SKR04 1460 | SKR03 1500, SKR04 1300 | none |

A cancellation books its voucher back on the same accounts (Haben). Overviews are not booked. Buyers outside Germany get no tax key. Invoices and credit notes from sellers on level 2 and 3 take 9 (19 % input VAT, on the gross amount) for `domestic_19`, 506 for `eu_reverse_charge`, 511 for `third_country_reverse_charge` and none for `domestic_small_business`. The chart comes from `skr` in the company data. Bookings are not fixed (Festschreibung 0), so the adviser can still change them.

**All accounts and tax keys are proposals until your tax adviser confirms them.** The adviser's own numbers go in the URL: `konto_aufwand`, `konto_verrechnung`, `konto_usdc`, plus `berater` and `mandant` (the numbers DATEV knows the firm and the company by, default 1001 and 1) and `wj_beginn` (start of the fiscal year, default 1 January).

What each plan includes is on [Pricing](https://402lounge.com/pricing).