Country packs

A country pack holds everything in Quittio that differs between countries: VAT rates and exemption texts, national invoice rules and profiles, the formats a country prescribes, legal notices, letter layouts, numbering and retention periods, and the law on late payment. The core of Quittio stays country-neutral. Quittio ships a pack for Germany, and quittio/quittio installs it. Packs for Austria, Belgium, Switzerland and France are published as separate packages; their legal wording is not reviewed by a tax adviser yet (Other countries).

Read this page when you invoice from Germany and need more than a standard invoice: an exemption or reverse charge, a small business invoice, XRechnung for a public buyer, a reminder with default interest or a letter layout after DIN 5008 (the German standard for business letters). Read it also when you want to support another country. If terms such as EN 16931, XRechnung, profile or BR-DE codes are new to you, read E-invoicing basics first.

The page has two parts:

The legal wording, references, rules and defaults of the German pack were reviewed in October 2026 and confirmed by a tax adviser; they reflect the law of that time. Quittio is no tax advice, and the issuer of an invoice remains responsible for it (see the legal review and the disclaimer in the README).

Germany (quittio/country-de)#

The German pack implements German VAT law (the VAT Act UStG and its implementing ordinance UStDV), XRechnung and German business letter conventions. Its class is Quittio\Country\DE\CountryDE (code DE, translation namespace quittio-de).

• Installation. Laravel discovers the pack automatically, so there is nothing to register. Without Laravel, pass new CountryDE to Quittio::create() (see Registering packs). The builder macro de() leads to the German special cases (Quittio\Country\DE\Builder\GermanInvoice), e.g. ->de()->smallAmount(); it is available as soon as Composer loads the package. Each method returns the builder, so the chain continues there. The macros of version 0.2 directly on the builder (->smallAmount(), ->selfBilled() …) still work, but are deprecated and report an E_USER_DEPRECATED. stubs/InvoiceBuilder.stub.php describes de() for IDEs and PHPStan.
• When it applies. The pack leads every invoice whose seller is in Germany (seller country code DE). It then checks the German rules, chooses the format and provides the defaults: the German locale (unless the invoice or the configuration sets one), A4 paper and the DIN 5008 form B layout. For an invoice from another country to a business in Germany, only its format rules apply, so that German public buyers receive XRechnung. Details are in How a pack is selected.
• Legal references. This page writes German legal references in English form: "section 14 (4) no. 1 UStG" stands for "§ 14 Abs. 4 Nr. 1 UStG". Other laws cited are the Civil Code (BGB), the Fiscal Code (AO) and the VAT application decree (UStAE). Values that the pack stores or prints in German keep their German form. German terms such as Gutschrift, Kleinunternehmer or Leitweg-ID are explained on first use and in the glossary.

Common tasks:

Complete invoices for these cases are on Examples.

Tax presets#

A tax preset is a ready-made VAT treatment for an invoice line. It sets the VAT category (BT-151) and the rate, and for exempt supplies also the exemption reason code (BT-121) and text (BT-120). Use a preset instead of a bare category and rate: the line then carries the wording German law requires, and the German rules recognise the case. Lines without vat: take the default VAT; in Laravel that is 19 % for a German seller and VatPreset::SmallBusiness for a small business.

The categories are the codes of EN 16931: S standard rate, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export outside the EU, O not subject to VAT (see Categories).

Quittio\Country\DE\Tax\VatPreset is a string-backed enum that implements TaxPreset. Apply it per line:

use Quittio\Core\Enums\UnitCode;
use Quittio\Country\DE\Tax\VatPreset;
use Quittio\Laravel\Facades\Quittio;

$builder = Quittio::invoice()
    ->line('Web development', netPrice: '95.00', quantity: 24, unit: UnitCode::Hour, vat: VatPreset::Standard)
    // an exemption without its own case: legal reference and VATEX code;
    // the invoice prints "Steuerfrei nach § 4 Nr. 14 UStG" (exempt under section 4 no. 14 UStG)
    ->line('Medical treatment', netPrice: '90.00', unit: UnitCode::Piece, vat: VatPreset::exempt('§ 4 Nr. 14 UStG', 'VATEX-EU-132-1C'));

The codes in column BT-121 are VATEX codes: the standard codes for the reason of an exemption.

Standard and Reduced take the rate that applied on the supply date of the line (TaxTables::STANDARD_RATE, TaxTables::REDUCED_RATE). The supply date is the end of the line period (BT-135), its start, the VAT point date (BT-7), the delivery date (BT-72), the end of the invoicing period (BT-74) or the issue date, in this order (Quittio\Core\Tax\SupplyDate). A delivery in August 2020 gets 16 % and 5 %, a correction of it issued in 2021 as well:

use Quittio\Core\Builder\InvoiceBuilder;
use Quittio\Country\DE\Tax\VatPreset;

InvoiceBuilder::make()
    ->issueDate('2021-01-20')
    ->deliveryDate('2020-08-15')
    ->line('Desk', netPrice: '400.00', vat: VatPreset::Standard);   // 16 %

VatPreset::Standard->rate() returns the rate of today. The plausibility rule DE-VAT-RATE warns when a line of category S within the German VAT territory has a rate that applied neither as standard nor as reduced rate on its supply date. It cannot tell whether the right one of the two was chosen: 19 % on restaurant meals, which are reduced again since 1 January 2026 (section 12 (2) no. 15 UStG, not for drinks), passes unnoticed. Average rates of agriculture and forestry (section 24 UStG) are a legitimate exception; switch the rule off for them with validation.rules.disabled (Switching rules off).

Up to version 0.2 the presets were called Standard19 (de.standard_19) and Reduced7 (de.reduced_7). These cases are deprecated and follow the dates as well; their keys stay readable: taxPresets()->get('de.standard_19') and quittio.defaults.vat find Standard, and lines of stored invoices keep their key. VatPreset::fromKey($key)?->canonical() turns an old key into the current case.

Standard, Reduced and ZeroRatedPv carry no text, because EN 16931 forbids an exemption reason for these categories (BR-S-10, BR-Z-10). The other presets print an exemption reason (BT-120) in German or English, from resources/lang/{de,en}/tax.php:

The English texts follow the terms of Directive 2006/112/EC ("exempt", "intra-Community supply", "Reverse charge"). The legal texts of the same notices use the same wording.

How presets behave:

• Language. The text is taken in the invoice locale (->locale() on the builder) when the line is built. The enum presets and VatPreset::exempt() (a Quittio\Country\DE\Tax\CustomVatPreset) use German when the invoice has no locale. Other locales without a text fall back to English.
• Preset key. The key stays on the line ($line->vat->presetKey). DE-USTG-09, DE-USTG-11, DE-USTG-14, DE-USTG-15 and the small business detection rely on it.
• VAT breakdown. Category, rate, code and text flow into the VAT breakdown (BG-23). When lines of one category and rate have different texts, the texts are joined in BT-120. The code (BT-121) is kept only when all codes agree; otherwise Quittio warns with QUITTIO-EXEMPTION-CONFLICT.
• Invoice notes. The mapping table of KoSIT and FeRD (recommended by the BMF letter of 15 October 2026) puts the statements of section 14a (6) and (7) UStG into the invoice note (BG-1). The margin scheme, travel agency and triangular presets therefore add their text once as note (BT-22, subject REG) as well, and ZeroRatedPv its reference to section 12 (3) UStG. A note with the same text is not added twice. Presets of other packs can do the same by implementing Quittio\Core\Tax\StatesInvoiceNote.
• PDF. The PDF lists the BT-120 texts of all categories other than the standard rate in its legal notes (legalNotes), together with the regulatory notes and without duplicates. Margin scheme and travel agency rows show no VAT amount and their lines no rate (section 14a (6) UStG), recognised by the code of the line.
• Margin scheme next to an exemption. EN 16931 allows one VAT group of category E only (BR-E-01). A margin scheme line and a line exempt under section 4 UStG therefore share it in the XML, with both texts in BT-120 and no code in BT-121 (QUITTIO-EXEMPTION-CONFLICT). The PDF shows the two parts in rows of their own, "Sonderregelung, kein gesonderter Steuerausweis: 500,00 €" and "Umsatzsteuerfrei (Steuerbefreit) auf 90,00 €", which add up to the group in the XML. With a document level allowance or charge of category E the parts cannot be told apart; then one row reads "Steuerfrei bzw. Sonderregelung, kein gesonderter Steuerausweis: 590,00 €" (label vat_row_exempt_special_scheme). Either way no "0 %" appears next to the margin scheme.
• Allowances and charges. Document level allowances and charges take a category and a rate, not a preset: ->charge(VatCategory::StandardRate, '19', amount: '10.00', reason: 'Shipping').
• Lookup by key, e.g. from a database column: VatPreset::from('de.standard'), (new CountryDE)->taxPresets()->get('de.standard') or, across all installed packs, $quittio->countries()->taxPreset('de.standard'). de.exempt is not part of the collection.

Small businesses#

A small business (Kleinunternehmer, section 19 UStG) charges no VAT. Its invoices state the exemption instead. Three steps make an invoice a correct small business invoice:

1. Mark the seller as a small business. Set quittio.seller.small_business = true (applied by Quittio::invoice()), the Managed issuer setting tax_settings.small_business, or ->flag(Meta::FLAG_SMALL_BUSINESS). Flags::SMALL_BUSINESS is the same flag (small_business). With the flag, a standard rated line, allowance or charge is an error (DE-USTG-09). The flag does not set presets or texts.
2. Use VatPreset::SmallBusiness on every line. Lines without ->vat() get it automatically when the invoice has the small business flag and the default VAT comes from the country pack (CountryDefaultVat; in Laravel always, see Default VAT). The preset's text (BT-120) appears in the PDF.
3. Give a seller identifier if you have no VAT identifier. Without a VAT identifier, EN 16931 needs a seller identifier (BT-29) or a legal registration (BT-30) (rule BR-CO-26). In Laravel set quittio.seller.identifiers or legal_registration (see Configuration).

use Quittio\Core\Enums\UnitCode;
use Quittio\Laravel\Facades\Quittio;

$builder = Quittio::invoice()                      // quittio.seller.small_business = true
    ->line('Consulting', netPrice: '80.00', unit: UnitCode::Hour);   // VatPreset::SmallBusiness by default

What the pack checks:

• An invoice with the small business flag, or with a line that uses the preset, is a small business invoice under section 34a UStDV. It needs no service date (DE-USTG-03), and the PDF is not checked for one. The tax number or VAT identifier is still required (DE-USTG-02).
• A small business needs no VAT identifier of its own for reverse charge services in another member state (DE-USTG-11; section 19 (1) sentence 2 UStG). The buyer's VAT identifier is still required.
• A small business that takes part in the cross-border small business scheme may state its small business identification number (Kleinunternehmer-Identifikationsnummer, suffix EX) instead of the tax number (section 34a sentence 1 no. 2 UStDV). It is no VAT identifier and belongs to the tax number (BT-32): ->de()->smallBusinessId('DE123456789EX') sets it there and sets the small business flag. DE-TAX-NUMBER accepts it. In a VAT identifier field (BT-31) it gets the info QUITTIO-SME-ID instead of a format warning.
• A small business cannot use the exemption for intra-community supplies (category K; DE-USTG-14, section 19 (1) sentence 2 UStG). The only exception is the intra-community supply of a new vehicle (->de()->newVehicle(), section 19 (6) sentence 1 UStG).

A complete invoice is in Examples: Small business.

Reverse charge, intra-community supplies and VAT identifiers#

With reverse charge (German: Steuerschuldnerschaft des Leistungsempfängers), the buyer owes the VAT instead of the seller. The invoice shows no VAT and must say why. An intra-community supply (innergemeinschaftliche Lieferung) is a VAT-exempt delivery of goods to a business in another EU member state. Use the presets ReverseChargeDomestic, ReverseChargeEu, TriangularTransaction and IntraCommunitySupply for these cases (Tax presets). The pack then checks:

• Wording. Reverse charge rows (category AE) must name "Steuerschuldnerschaft des Leistungsempfängers" (DE-USTG-06, error; the buyer owes the VAT all the same). The texts of the reverse charge presets are accepted in every locale the pack ships, so English invoices with the presets pass as well. Your own texts must contain "Steuerschuldnerschaft".
• VAT identifiers. Reverse charge in another member state and triangular transactions need the VAT identifiers of seller and buyer (DE-USTG-11). The rule does not apply to ReverseChargeDomestic (section 13b UStG), and a small business needs none of its own (section 19 (1) sentence 2 UStG).
• Deadline. Invoices for intra-community supplies and for services in another member state (ReverseChargeEu) must be issued by the 15th of the month following the supply (DE-USTG-15, warning; section 14a (1) sentence 2 and (3) sentence 1 UStG). This includes final invoices: advance payments trigger no VAT on intra-community supplies, so the invoice for the supply is the one with the deadline.
• PDF. The PDF must show the reverse charge or exemption note and the VAT identifiers (see Mandatory PDF output).
• Tax representative. A tax representative of the seller (BG-11, ->taxRepresentative($name, $vatId, $address)) satisfies DE-USTG-02 and BR-DE-16. Its VAT identifier satisfies DE-USTG-11 and the mandatory output.
• Number formats. The tax number (Steuernummer, BT-32) of a seller in Germany is checked for format and check digit (DE-TAX-NUMBER, see Tax number). VAT identifiers are checked by the core plausibility rules: QUITTIO-VATID-FORMAT (for DE nine digits) and optionally QUITTIO-VIES, an online check against the EU's VIES service. The same rules warn about category K with a domestic or non-EU destination, and about G within the EU (see Validation).

Complete invoices are in Examples: EU business: services, EU business: goods and Export.

Format choice#

Without ->format(), Quittio chooses the format for each invoice (Automatic choice). The German pack adds only the cases in which German law prescribes a format. Quittio\Country\DE\Formats\GermanFormatRule returns a choice for these cases and null (no opinion) otherwise:

A Leitweg-ID is the routing ID of a German public buyer, such as an authority or a municipality. The buyer names it in the order, and it goes into the buyer reference (BT-10). Its last two digits are check digits.

use Quittio\Core\Builder\Party;
use Quittio\Laravel\Facades\Quittio;

$builder = Quittio::invoice()
    ->buyerReference('04011000-12345-03')                // a Leitweg-ID: XRechnung
    ->buyer(Party::make('Stadt Beispielstadt')
        ->electronicAddress('04011000-12345-03', '0204'));  // or the same ID as electronic address (scheme 0204)

• Order numbers shaped like a Leitweg-ID (e.g. 4711-01) do not switch to XRechnung. A Leitweg-ID with a typo does not either; validation reports it as DE-LEITWEG-ID-SUSPECT (info, see Leitweg-ID). Correct it, set the 0204 endpoint as well, or choose the format explicitly (->format('xrechnung-ubl')).
• An explicit ->format() or a configured quittio.defaults.format always wins.

Everything else follows the general order of the resolver:

• Domestic business invoices: the Peppol lookup of the resolver, if one is configured, then zugferd with the configured profile (en16931 by default; EXTENDED when EXTENDED features are used).
• Consumers: pdf.
• Cross-border invoices: the e-invoicing obligation of section 14 (2) UStG covers only supplies between businesses established in Germany. Sellers outside the EU invoicing a German business get pdf from the resolver, sellers in other member states zugferd. Buyers in Büsingen or Heligoland are outside the EU VAT territory and get pdf.
• German public buyers receive XRechnung whatever the seller's country: for cross-border invoices to a buyer in Germany, the rule runs as the rule of the buyer's pack.

A complete invoice to a public buyer is in Examples: Public sector.

E-invoice obligation#

When an explicit format or profile produces no e-invoice, the German rules check whether one was required (section 14 (1) and (2), section 27 (38) UStG). A run produces an e-invoice when one of its formats writes XML of an EN 16931 profile; MINIMUM, BASIC WL and a plain pdf do not. xrechnung-cii with pdf in one run is an e-invoice with a readable copy. Drafts and previews (watermark) are not checked.

The obligation applies when seller and buyer are in the German Inland and the buyer is a business. It does not apply to:

• consumers (->consumer());
• supplies exempt only under section 4 no. 8 to 29 UStG, told by the legal reference ("§ 4 Nr. 14 UStG") or a VATEX code of Article 132 or 135;
• small amount invoices up to 250 EUR gross (section 33 sentence 4 UStDV), with or without ->de()->smallAmount();
• small businesses (section 34a sentence 4 UStDV);
• tickets (section 34 UStDV, ->de()->ticket(), flag de.ticket);
• cancellations and corrections of earlier invoices (section 14.11 (1) sentence 9 UStAE).

The supply date decides (UstgRules::supplyDate(), otherwise the issue date); for a prepayment invoice the issue date (BMF letter of 15 October 2026, marginal no. 2):

Set the turnover with quittio.countries.de.prior_year_turnover_above_800k (core: Quittio::create(['countries' => ['de' => ['prior_year_turnover_above_800k' => true]]], …)); the default is false. Both findings belong to the BMF error class "Formatfehler" (format error, marginal no. 6a). An other invoice instead of a required e-invoice is no administrative offence (marginal no. 28), but it is no proper invoice, and the buyer may lose the input tax deduction.

Mapping table of KoSIT and FeRD#

Which mandatory detail of the UStG goes into which field of an e-invoice is set out in the mapping table of KoSIT and FeRD (Empfehlungen zu Pflichtangaben in einer E-Rechnung, as of 25 July 2025), which the BMF letter of 15 October 2026 recommends (marginal no. 8 f.). The pack follows it: exemption and reverse charge texts in BT-120 with the code in BT-121, the statements of section 14a (6) and (7) UStG also as note, the retention notice and "Gutschrift" as note, vehicle details as item attributes (BG-32), the date of receipt of an advance payment in BT-7, a service month as invoicing period (BG-14). Details such as time sheets may go into an embedded attachment, the type, quantity and kind of the service must be in the structured part (marginal no. 10 to 12).

XRechnung profiles#

XRechnung is the German e-invoice standard for public buyers: EN 16931 with additional German rules, as an XML file in the CII or UBL syntax (see Formats). The pack registers three profiles for it. XRechnung 3.0 is the one you normally use. The extension allows data that XRechnung 3.0 does not, such as sub lines. XRechnung CVD is XRechnung 3.0 for the procurement of road vehicles under the Clean Vehicles Directive (CVD, Directive (EU) 2019/1161). How Quittio writes XRechnung files is described in Formats: XRechnung.

The profiles exist only when the pack is registered. Without it, the formats xrechnung-cii and xrechnung-ubl cannot be rendered, and incoming XRechnung files are reported as an unknown profile (QUITTIO-READER-UNKNOWN-PROFILE).

use Quittio\Laravel\Facades\Quittio;

Quittio::make($invoice)->format('xrechnung-ubl')->render();                                   // XRechnung 3.0, UBL
Quittio::make($invoice)->format('xrechnung-ubl')->profile('xrechnung-extension')->render();   // extension
Quittio::make($invoice)->format('xrechnung-cii')->profile('xrechnung-cvd')->render();         // Clean Vehicles Directive
Quittio::make($invoice)->format('zugferd')->profile('xrechnung')->render();                   // PDF/A-3 with xrechnung.xml

The automatic choice always uses xrechnung, also when the invoice carries extension data: the specification identifier never switches by itself. Choose xrechnung-extension explicitly for extension data. With xrechnung, third party payments fail with QUITTIO-PROFILE-XRECHNUNG-EXTENSION-ONLY. The same holds for xrechnung-cvd: request it when the buyer asks for an XRechnung CVD.

XRechnung CVD#

A public buyer that procures road vehicles reports them under the Clean Vehicles Directive. The invoice then names the contract and the tender or lot, and every vehicle line carries the vehicle category as item classification with the scheme CVD (BT-158, M1, M2, M3, N1, N2 or N3) and the vehicle type as item attribute cva (BT-160, BT-161: clean, zero-emission or other):

use Quittio\Core\Enums\UnitCode;
use Quittio\Country\DE\Tax\VatPreset;
use Quittio\Laravel\Facades\Quittio;

$invoice = Quittio::invoice()
    ->buyerReference('04011000-12345-03')
    ->contractReference('V-2026-0017')                       // BT-12
    ->tenderReference('LOS-3')                               // BT-17
    ->line(fn ($line) => $line->name('Elektro-Kleinbus')->quantity(1)->netPrice('68000.00')->vat(VatPreset::Standard)
        ->classification('M2', 'CVD')                        // vehicle category (BT-158)
        ->attribute('cva', 'zero-emission'))                 // vehicle type (BT-160, BT-161)
    ->line(fn ($line) => $line->name('Einweisung')->quantity(2, UnitCode::Hour)->netPrice('95.00')->vat(VatPreset::Standard));
    // … seller, buyer, payment as for every XRechnung

Quittio::make($invoice)->format('xrechnung-cii')->profile('xrechnung-cvd')->render();

The constants of XRechnung30Cvd hold the values (CLASSIFICATION_SCHEME, VEHICLE_CATEGORIES, ATTRIBUTE, ATTRIBUTE_VALUES). Lines without a vehicle, such as services, need neither. Credit notes are possible in both syntaxes.

XRechnung rules#

Quittio\Country\DE\Rules\XRechnungRules (level L3) are the business rules of the XRechnung profiles, with codes BR-DE-…. They apply whenever the profile is xrechnung, xrechnung-extension or xrechnung-cvd, whatever the seller's country; the rules BR-DE-CVD-… only with the specification identifier of XRechnung CVD.

The severity follows the flags of the official Schematron, the rule file of the official validator. Rules flagged fatal ("muss", must) are errors, rules flagged warning ("soll", should) are warnings, and BR-DE-TMP-32 (flagged information) is an info. The KoSIT validator (the official XRechnung validator) remains authoritative (see Validation).

The BR-DEX-… rules apply only to the profile xrechnung-extension; those marked UBL are skipped when the XML is written in CII, where the official Schematron does not have them. As in the official validator configuration, where the replaced rules are only an information, the extension replaces BR-CL-10, -11, -21, -25 and -26 with BR-DEX-04 to BR-DEX-08 and, in UBL, BR-CO-16 with BR-DEX-09 and QUITTIO-SUBLINES with BR-DEX-02 (XRechnung30Extension::replacedRules()), so a violation is reported once, with the official code.

#SKONTO# lines state a cash discount (Skonto) in a form software can read: TAGE is the number of days, PROZENT the percentage and BASISBETRAG the base amount. Quittio writes structured cash discounts itself (#SKONTO#TAGE=7#PROZENT=2.00#), so BR-DE-18 only concerns lines you put into the payment terms text yourself.

Small amount invoices#

German law allows a simplified invoice for small amounts (section 33 UStDV). ->de()->smallAmount() marks an invoice of at most 250.00 EUR gross as such a small amount invoice. The gross total counts, including exempt or non-taxable parts (section 14.6 (4) UStAE). The limit of the supply date applies (TaxTables::SMALL_AMOUNT_LIMIT: 150.00 EUR from 2007, 250.00 EUR from 2017; the raise applies to supplies from 1 January 2017), or of the issue date if the invoice states no supply date. As long as no reverse charge (AE) or intra-community supply (K) is involved, it relaxes:

• DE-USTG-01: the buyer's address is not required (the seller's still is);
• DE-USTG-02: no tax number or VAT identifier is required;
• DE-USTG-03: no service date is required;
• the mandatory PDF output for the tax number and the service date;
• the format: pdf instead of zugferd when seller and buyer are in the German Inland. A Leitweg-ID still leads to XRechnung (see Format choice).

DE-USTG-08 enforces the limit. DE-USTG-12 excludes reverse charge and intra-community supplies (section 33 sentence 3 UStDV): such invoices need all mandatory information and are not rendered as plain PDF. Possible distance sales (goods sent to a consumer in another member state, section 3c UStG) keep the simplifications, with a warning.

Builder macros#

Quittio\Country\DE\Builder\GermanInvoiceMacros adds methods for German special cases to InvoiceBuilder, and so to Quittio::invoice():

The notes and their texts are listed in Legal texts.

Macros are invisible to IDEs and static analysis. The pack ships a stub with their signatures, stubs/InvoiceBuilder.stub.php; it is never loaded at runtime. Add it to PHPStan (vendor/quittio/quittio/packages/country-de/stubs/… with the complete package):

parameters:
    stubFiles:
        - vendor/quittio/country-de/stubs/InvoiceBuilder.stub.php

• The $locale parameter selects the language of the note. It is independent of the invoice locale.
• A locale with a region uses the text of its language (en_GB → English). Locales without a text of the pack get the German text (LegalTexts::text()).
• Notes with subject REG (regulatory information) are listed in the PDF's legal notes (legalNotes). Notes with subject PMT (payment information) appear with the other notes.

Prepayment invoices#

A prepayment invoice (Anzahlungsrechnung, type code 386) must show that it invoices an advance payment, e.g. by the expected date or month of the service (section 14.8 (1) and (4) UStAE). ->de()->advance() sets the type code and the note:

use Quittio\Core\Enums\UnitCode;
use Quittio\Laravel\Facades\Quittio;

$advance = Quittio::invoice()
    ->de()->advance('2027-03')                     // "Anzahlungsrechnung. Die Leistung wird voraussichtlich im März 2027 erbracht."
    ->line('Website relaunch, advance payment', netPrice: '1000.00', unit: UnitCode::LumpSum);

$paid = Quittio::invoice()
    ->de()->advance('2027-03-15', receivedOn: '2026-10-01')   // "… am 15.03.2027 erbracht. Die Anzahlung wurde am 01.10.2026 vereinnahmt."
    ->line('Website relaunch, advance payment', netPrice: '1000.00', unit: UnitCode::LumpSum)
    ->prepaid('1190.00');

• $expectedService is a date or a month ("2027-03"). null states that the date is not agreed yet (serviceDateOpen(), section 14.8 (4) sentence 5 UStAE). Either way DE-USTG-03 does not warn.
• $receivedOn is the date a payment was already received. It is stated as VAT point date (BT-7), to which the mapping table of KoSIT and FeRD assigns the date of receipt, and in a note (section 14 (4) sentence 1 no. 6 UStG). A prepayment invoice with a prepaid amount but no BT-7 gets DE-USTG-17.
• XRechnung warns about type code 386 (BR-DE-17): its list names 326 and 380 but not 386. The mapping table of KoSIT and FeRD prescribes 386 for prepayment invoices all the same, so the warning is to be accepted.

Final invoices (deductAdvance)#

A final invoice (Schlussrechnung, section 14 (5) sentence 2 UStG) states the full service with its full VAT and deducts the advance payments received. ->de()->deductAdvance(InvoiceData $advance, string $locale = 'de', $received = null, string $style = GermanInvoice::PREPAID) does this for one advance invoice:

use Quittio\Core\Enums\UnitCode;
use Quittio\Country\DE\Builder\GermanInvoice;
use Quittio\Country\DE\Tax\VatPreset;
use Quittio\Laravel\Facades\Quittio;

$advance = $advanceResult->data();                 // the rendered advance invoice, already calculated

$final = Quittio::invoice()
    // number, dates, buyer, payment …
    ->line('Website', netPrice: '3000.00', unit: UnitCode::Piece, vat: VatPreset::Standard)
    ->de()->deductAdvance($advance, received: GermanInvoice::RECEIVED_IN_FULL);

The advance invoice must be calculated. The data of a rendered invoice ($result->data()) already is; calculate data you built yourself with (new En16931Calculator)->calculate($advanceInvoice) (Quittio\Core\Calculation\En16931Calculator).

With an advance invoice RE-2026-0040 of 1,000.00 EUR net plus 19 % VAT, the final invoice shows a gross total of 3,570.00 EUR, VAT 570.00 EUR, prepaid 1,190.00 EUR and an amount due of 2,380.00 EUR, with the note:

Abzüglich Anzahlung gemäß Rechnung RE-2026-0040 vom 01.09.2026: Entgelt 1.000,00 € zzgl. 19 % Umsatzsteuer 190,00 € (§ 14 Abs. 5 Satz 2 UStG).

With ->de()->deductAdvance($advance, 'en') the note is in English: "Less advance payment according to invoice RE-2026-0040 of 01/09/2026: net 1,000.00 € plus 19% VAT 190.00 € (section 14 (5) sentence 2 UStG)."

• Checks. The advance invoice must be calculated (totals set), have a positive gross total and be in the currency of the final invoice. Otherwise an InvalidArgumentException is thrown. Set ->currency() before calling the macro.
• Accepted documents. Only documents that can be advance invoices are accepted (GermanInvoiceMacros::ADVANCE_TYPES): type codes 380 (commercial invoice), 386 (prepayment invoice), 326 (partial invoice), 875 (partial construction invoice) and 389 (self-billed invoice). Credit notes, debit notes, corrected invoices (384), final invoices (876, 877) and cancellations by negative invoice are rejected.
• Amount received. Only advance payments actually received are deducted (section 14 (5) sentence 2 UStG). Pass what you received as received:: GermanInvoice::RECEIVED_IN_FULL (or the full amount) deducts the advance invoice's gross total plus its cash rounding (BT-114). A smaller amount, e.g. received: '595.00' for half of the example, deducts that amount: it is distributed over the VAT rows of the advance invoice in proportion to their gross amounts, and the VAT is taken out of each part at its rate (section 14.8 (5) UStAE). The note then names these amounts. Zero or more than the advance invoice throws an InvalidArgumentException.
• Unconfirmed amount. Without received: the advance invoice is deducted in full as before, but the flag de.advance_receipt_unconfirmed is set and DE-USTG-20 warns. Deducting an advance that was not paid states too little VAT; not deducting one that was paid makes you owe its VAT twice (section 14.8 (10) UStAE).
• Unpaid advance invoices. Do not deduct them. The advance invoice need not be cancelled (section 14.8 (2) UStAE); you may cancel it for clarity in your accounts.
• Remainder invoice. style: GermanInvoice::REMAINDER adds instead a line "Abzüglich Anzahlung gemäß Rechnung … vom …" per VAT row with quantity −1 and the net amount received, and the note LegalTexts::ADVANCE_DEDUCTION_REMAINDER ("Restrechnung: Abgezogen ist die vereinnahmte Anzahlung gemäß Rechnung …"). The invoice then shows only the VAT of the remainder (section 14.8 (11) UStAE), which the buyer's system cannot deduct twice. The default PREPAID (BT-113 with the itemisation in BT-22) is the variant the BMF letter of 15 October 2026 (marginal no. 3) explicitly accepts until 30 June 2030.
• Itemisation. Every VAT row of the advance invoice is itemised. Standard rated rows read "Entgelt … zzgl. … Umsatzsteuer …" ("net … plus … VAT …", LegalTexts::ADVANCE_DEDUCTION_TAXED), other rows "Entgelt … ohne Umsatzsteuer" ("net … without VAT", LegalTexts::ADVANCE_DEDUCTION_UNTAXED). Rows are separated by semicolons.
• Language. The whole note is in one language: the language of $locale if the pack has it (de, en), otherwise German. Amounts and dates are formatted in $locale when the note is in its language (e.g. de_AT). Otherwise they are formatted in the language of the note: fr gives the German note with German formatting.
• Several advance invoices. Call the macro once per advance invoice; the prepaid amounts add up.
• Self-billed advances. An advance settled by self-billing (389) must be deducted as well. If the final invoice is no self-billed invoice, DE-USTG-19 notes the change of the way of invoicing.
• Review in 2030. The acceptance of BT-113 with the itemisation in BT-22 ends on 30 June 2030 (BMF letter of 15 October 2026, marginal no. 3); the default will be reviewed then.

A complete example with the advance invoice is in Examples: Advance payment and final invoice.

Self-billing (Gutschrift)#

In self-billing, the buyer issues the invoice for the seller's supply. German law requires the word "Gutschrift" on such an invoice (section 14 (4) no. 10 UStG). Quittio uses "Gutschrift" only for self-billing; commercial credit notes and cancellations carry other titles.

• ->de()->selfBilled() sets type code 389 and adds the note "Gutschrift" (English variant: "Gutschrift (self-billed invoice)").
• The PDF is titled "Gutschrift" in German and "Self-billed invoice (Gutschrift)" in English, and shows the buyer as issuer.
• DE-USTG-04 requires the label on every self-billed type code (389, 261, 527); in an e-invoice the type code is label enough, so there it is a warning.
• The mandatory output requires the title and the "Gutschrift" note in the PDF.

What Quittio cannot check, and you must make sure of:

• Prior agreement. Self-billing must be agreed before the first self-billed invoice (section 14 (2) sentence 2 UStG), best in writing, e.g. in the framework contract with the supplier. Without the agreement the document is no invoice, and the issuer loses the input tax deduction. The agreement is not stated on the document, so Quittio does not ask for it.
• Objection. The supplier may object to a self-billed invoice (section 14 (2) sentence 6 UStG). It then loses its effect as invoice, for the future only (BFH XI R 41/20), and the supplier issues an invoice of its own. An objection is no cancellation; do not issue a cancellation for it.
• Corrections and cancellations of a self-billed invoice come from its issuer, the buyer (section 14.11 (2) sentence 2 UStAE). Quittio::cancellation() keeps the document self-billed (261, or 389 negative for XRechnung).

A complete example is in Examples: Self-billing.

Cancellations and corrections#

CountryDE::correctionPolicy() sets how invoices of a German seller are cancelled and corrected (see Building invoices: cancellations and corrections):

• Cancellation strategy credit_note: a cancellation is a credit note (type code 381) with positive amounts.
• Correction strategy cancel_and_reissue: the Managed layer corrects an invoice by cancelling it and issuing a new one.

Both cancellation strategies are permitted in Germany. Change them with quittio.corrections.cancellation_strategy and quittio-managed.correction.strategy. For the XRechnung extension in UBL use negative_invoice (DE-XRECHNUNG-EXT-01).

A self-billed invoice (389) with a Leitweg-ID (BT-10), i.e. sent as XRechnung, is cancelled by a negative self-billed invoice (389) instead of a self-billed credit note (261): XRechnung lists 261 not among its type codes and warns (BR-DE-17). Receiving portals of public buyers may treat that warning strictly. An explicit $strategy or corrections.cancellation_strategy still wins. ZUGFeRD keeps 261.

A corrected invoice (384) should state that it corrects and replaces the original (DE-USTG-18); Quittio::correction() adds the note. A price reduction (Quittio::priceReduction()) is titled "Entgeltminderung".

What a correction does for the parties (for your users' information, not checked by Quittio):

• Seller. VAT shown too high (section 14c (1) UStG) is corrected in the period of the correction (section 17 (1) sentence 7 UStG), whichever way you correct.
• Buyer. A correction, also by cancellation and new invoice, takes effect back to the original invoice if it had the minimum details of seller, buyer, supply, consideration and VAT and the correction refers to it specifically (BFH V R 26/15, XI R 10/17; BMF letter of 18 September 2020). Quittio refers by number and date (BG-3) and the note.
• Procedure. A correction is no retroactive event under section 175 (1) sentence 1 no. 2 and section 233a (2a) AO (section 14 (4) sentence 4 UStG).
• Double invoices. If an invoice was issued twice, cancel the second one: its VAT is owed under section 14c (1) UStG until it is corrected.

The policy also sets the document titles:

• cancellation and cancellation_self_billed title the documents of Quittio::cancellation().
• correction titles a corrected invoice (384) of Quittio::correction() and of the Managed layer.
• price_reduction titles the documents of Quittio::priceReduction().
• self_billed titles self-billed invoices (389, 261, 527) unless the presentation sets a title. Locales without a title of their own fall back to English ("Self-billed invoice (Gutschrift)"), which keeps the word "Gutschrift" required by section 14 (4) no. 10 UStG.

Dunning law#

When a customer pays late, German law (section 288 BGB) gives the seller default interest (Verzugszinsen) and, from business debtors, a flat rate of 40 EUR. The pack provides these values and a calculator for the interest. Quittio's documents do not apply them by themselves: calculate the interest with DefaultInterest and pass the results to a payment reminder (see Documents: payment reminders).

CountryDE::dunningLaw() returns these values:

Default interest#

Quittio\Country\DE\Dunning\DefaultInterest calculates the default interest on an open amount:

use Brick\Money\Money;
use Quittio\Core\Support\Amount;
use Quittio\Core\Support\Date;
use Quittio\Country\DE\Dunning\DefaultInterest;
use Quittio\Laravel\Facades\Quittio;

$interest = new DefaultInterest;
$reminder = Quittio::paymentReminder(1)                          // first reminder ("1. Mahnung"); seller and bank account from the config
    ->number('M-2026-0003')
    ->buyer($buyer)
    ->openItem('RE-2026-0042', '2026-06-01', '1190.00', dueDate: '2026-06-15');

// first day with interest: the day after the due date; 2026-10-04 is the first day without interest
foreach ($interest->calculate(Money::of('1190.00', 'EUR'), Date::parse('2026-06-16'), Date::parse('2026-10-04')) as $charge) {
    $reminder->interest(Amount::format($charge->base), $charge->ratePercent, $charge->from, $charge->until, $charge->description, dayCount: $charge->dayCount);
}
$reminder->flatRate('RE-2026-0042');   // 40.00 EUR for this claim, "Pauschale für Beitreibungskosten (§ 288 Abs. 5 BGB), Forderung RE-2026-0042"

• Descriptions. They name the rate, the base rate, the points and the last day with interest. With the locale de (the default) a description reads "Verzugszinsen 10,27 % p. a. (Basiszinssatz 1,27 % + 9,00 Prozentpunkte) vom 16.06.2026 bis 30.06.2026". Any other locale gives "Default interest 10.27 % p.a. (base rate 1.27 % + 9.00 points) from 2026-06-16 to 2026-06-30".
• Day count. The charges use the day count of the dunning law (InterestCharge::$dayCount). CountryDE::dunningLaw() counts actual/actual: the days of each calendar year are divided by its length, 366 in a leap year, as the statutory day count conventions do (annex to section 16 PAngV). No federal court has decided the question for section 288 BGB; the fixed basis of 365 days would overstate the interest of a leap year slightly. Pass the day count to interest() as above (dayCount: $charge->dayCount), or use interestCharge().
• Periods. A charge covers a whole period with the same base rate. Interest from 1 December 2025 to 28 February 2026 is one charge, although the table has an entry for 1 January 2026.
• Flat rate. DocumentBuilder::flatRate($claim) adds it as a fee of kind DunningFeeKind::FlatRate for one claim (invoice or instalment). It is due for every late payment, also of instalments and of recurring payments under one contract (section 288 (5) sentence 2 BGB; CJEU C-370/21), only from businesses, and counts towards the costs of legal pursuit (sentence 3): reminder fees of your own are recovery costs and may be claimed beside it only in so far as they exceed 40 EUR (CJEU C-287/17, C-131/18). The builder rejects a second flat rate for the same claim in one reminder and a flat rate for a consumer; a flat rate together with reminder fees gets the notice QUITTIO-DUNNING-FLAT-RATE-FEES (Documents: payment reminders). Which claims already carried it in earlier reminders is up to your application or the Managed layer. A creditor who brings about the conditions of the flat rate abusively loses it (CJEU C-209/25).
• Reminder fees. The reminder that puts the debtor in default is part of the creditor's own receivables management; its costs are not damages (BGH VIII ZR 138/23, marginal no. 77). Quittio has no default fee. Fee clauses towards consumers are subject to section 309 no. 5 BGB.
• No VAT. Default interest, reminder costs and the flat rate are damages, not consideration (section 1.3 (6) UStAE). Interest agreed for a deferral of payment (e.g. in an instalment agreement) is consideration for a service of its own, possibly exempt under section 4 no. 8 (a) UStG; Quittio does not cover it.
• Consumers. Without an agreed date, a debtor is in default only after a reminder, or 30 days after due date and receipt of the invoice; a consumer only if the invoice points this out (section 286 (3) BGB). A due date the seller sets on the invoice alone does not put the buyer in default (BGH VIII ZR 215/15). The pack therefore adds the notice to every invoice for a consumer (CountryDE::complete(), see below); ->de()->consumerDefaultNotice() adds it explicitly.

A complete reminder is in Examples: Payment reminder.

VAT identifiers on invoices of category O#

EN 16931 allows no VAT identifiers of seller (BT-31), buyer (BT-48) or tax representative (BT-63) on an invoice of supplies not subject to VAT (category O, rule BR-O-02), and such an invoice has no other VAT category (BR-O-11). In Laravel the seller's VAT identifier comes from the configuration, so every such invoice would fail. CountryDE::complete() therefore leaves out the VAT identifiers of seller and buyer when:

• every line is of category O (VatPreset::NotTaxableInGermany, BusinessTransfer or your own),
• the seller has a tax number (BT-32), which satisfies section 14 (4) sentence 1 no. 2 UStG instead,
• and there is no tax representative: EN 16931 requires its VAT identifier (BR-56) and forbids it here, so such an invoice cannot be issued at all.

The invoice gets the flag de.vat_ids_omitted and the info DE-CATEGORY-O-01. The rendered data ($result->data()), XML and PDF are without the VAT identifiers; the builder keeps them. Without a tax number or with a tax representative nothing changes: BR-O-02 stays an error, and the info DE-CATEGORY-O-02 names what is missing. Switch the completion off with quittio.countries.de.omit_vat_ids_for_category_o = false.

Default notice for consumers#

CountryDE completes invoices before they are calculated and rendered (Quittio\Core\Countries\Capabilities\CompletesInvoices): an invoice for a consumer (->consumer() on the buyer) gets the note LegalTexts::CONSUMER_DEFAULT with subject PMT, "Sie kommen spätestens in Verzug, wenn Sie nicht innerhalb von 30 Tagen nach Fälligkeit und Zugang dieser Rechnung zahlen (§ 286 Abs. 3 BGB)." in the language of the invoice. Credit notes and invoices that already have such a note (a note containing "286") are left alone. The note is part of the rendered data ($result->data()), not of the builder.

Switch it off with the setting consumer_default_notice of the pack: quittio.countries.de.consumer_default_notice = false in Laravel, Quittio::create(['countries' => ['de' => ['consumer_default_notice' => false]]], …) in the core.

Base rate table#

The base rate (Basiszinssatz, section 247 BGB) changes on 1 January and 1 July. Quittio\Country\DE\Dunning\BaseRateTable holds the rates. Quittio ships these (BaseRateTable::PUBLISHED):

Rates after the last entry are unknown until they are published. Interest for days from 1 January 2027 is therefore rejected instead of silently using the old rate. There are three ways to add new rates without a new Quittio release:

1. Laravel configuration. Add the rate to quittio.countries.de.base_rates in config/quittio/countries/de.php (publish it with php artisan vendor:publish --tag=quittio-de-config; see Configuration). Up to 0.3 this was config/quittio-de.php, which is still read until 1.0.

   phpCopy

   'base_rates' => ['2027-01-01' => '1.77'],

2. Automatic update from the Deutsche Bundesbank (Laravel). php artisan quittio:base-rate:update fetches the series BBIN1.M.DE.BBK.BBKBAS2.EUR.ME ("Basiszinssatz gemäß BGB", the base rate under the BGB) from the Bundesbank's statistics API (command).

   • It stores the rates the shipped table does not contain in quittio.countries.de.base_rate_file (default storage/app/quittio/base-rates.json), also those before 2023 for older claims.
   • It writes the file only when something changed; --dry-run shows the rates without writing.
   • A value that differs from the shipped table is reported, and the Bundesbank value is used.
   • Without a file (base_rate_file set to null) the command fails, except with --dry-run.

   Schedule it, e.g. weekly, so that the rate of 1 January and 1 July is there as soon as the Bundesbank has published it:

   phpCopy

   // routes/console.php
   Schedule::command('quittio:base-rate:update')->weekly();

3. Without Laravel. Call BaseRates::register(['2027-01-01' => '1.77']) once at start-up, fetch the rates yourself with (new BundesbankBaseRates)->fetch(), or use a table for one calculation:

   phpCopy

   $rates = (new BaseRateTable)->withRate('2027-01-01', '1.77');
   $interest = new DefaultInterest($rates);

DefaultInterest without a table uses BaseRates::table(): the shipped table, then the rates of the file, then those of quittio.countries.de.base_rates. The configuration wins for the same date. The service provider Quittio\Country\DE\Laravel\GermanyServiceProvider registers file and configuration at boot; Laravel discovers it automatically.

BaseRateTable:

Quittio\Country\DE\Dunning\BaseRates:

Quittio\Country\DE\Dunning\BundesbankBaseRates:

DIN 5008 letter layouts#

DIN 5008 is the German standard for business letters. It fixes where the address field sits, so that the address shows in the window of a window envelope, and where the fold and punch marks are. Quittio\Country\DE\Layouts\Din5008 provides two forms: form A (din5008a) with a low letterhead and form B (din5008b) with a higher one. Form B is the German default.

Din5008 has the methods formA(), formB() and all() (form A, form B and free). Values are in millimetres, as in DIN 5008:2020. They are unchanged since the 2011 edition, which enlarged the address field of both forms from 40 to 45 mm and moved the return address line (Rücksendeangabe) into the zone for additional information and notes (Zusatz- und Vermerkzone).

• The address field keeps its position when the invoice has a logo.
• The default templates print the sender line at the top of the address field and the recipient directly below it, inside the envelope window. The zones above are for your own templates.
• Select a layout per invoice with ->presentation(['letterLayout' => 'din5008a']), or for all invoices with quittio.pdf.layout.
• Fold and punch marks are printed unless quittio.pdf.fold_marks (core option fold_marks) is false.

See Templates: letter layouts.

UStG rules#

Quittio\Country\DE\Rules\UstgRules::all() (level L3) checks the mandatory content of an invoice under the German VAT Act (sections 14 (4) and 14a UStG) and the simplifications of sections 33 and 34a UStDV. The rules apply to every invoice of a German seller, in every format including a plain PDF. Messages and hints are in German and English.

You rarely need this table up front: a failing rule names its code, the field and a hint. Look the code up here when the hint is not enough.

Helpers used by the rules and available to you:

• UstgRules::isSmallAmountInvoice($invoice): the invoice has the small amount flag and its simplifications apply (no category AE or K);
• UstgRules::isSmallBusinessInvoice($invoice): the small business flag is set or a line uses VatPreset::SmallBusiness;
• UstgRules::hasServiceDate($invoice): delivery date, invoicing period or a period on every line;
• UstgRules::supplyDate($invoice): the latest of the delivery date, the end of the invoicing period and the ends of the line periods, or null without any of them;
• UstgRules::issuingDeadline($invoice): the 15th of the month after the supply, or null without a supply date.

Leitweg-ID#

UstgRules::plausibility() (level L7) checks buyer references (BT-10 buyerReference) that are shaped like a Leitweg-ID but have wrong check digits:

So a mistyped Leitweg-ID does not lead to ZUGFeRD unnoticed. An order number of the same shape (e.g. 4711-01) gets the same info, which you may ignore. Neither finding changes the format.

Quittio\Country\DE\Support\LeitwegId:

Tax number#

UstgRules::plausibility() also checks the tax number (Steuernummer, BT-32) of a seller in Germany. The local tax office issues this number; it is not the VAT identifier.

The checks follow the document "Prüfung der Steuer- und Steueridentifikationsnummer" (checking tax numbers and tax identification numbers) of ELSTER, the online service of the German tax authorities, published by the Bavarian State Office for Taxes (Bayerisches Landesamt für Steuern):

• Format. The 13-digit ELSTER format is FFFF0BBBUUUUP (NRW: FFFF0BBBBUUUP), with the 0 at the 5th position.
• Excluded districts. 000, 998 and 999; below 100 in the Bavarian group; in NRW 0000, 0998 and 0999, and UUUP must be above 0009.
• Check digit. Each state has its procedure: the modified 11 procedure (Rhineland-Palatinate), the 2 procedure (Baden-Württemberg, Hesse, Schleswig-Holstein), or the 11 procedure with the factors of the state (all others; Berlin with the variants A and B by tax office and district).
• Not checked: whether the tax office exists.
• Notation without state. A notation without the state (e.g. 93/815/08150) is valid when it is valid for any state that uses this notation.

Quittio\Country\DE\Support\TaxNumber:

Mandatory PDF output#

After rendering, the mandatory field guard checks that the PDF shows certain values (see Templates: mandatory field guard). CountryDE::mandatoryOutput() adds these German values to the base fields. Paths without a value are skipped. The legal basis is the value Quittio reports, in German citation form.

The default templates print all of them.

Legal texts#

Quittio\Country\DE\Texts\LegalTexts::catalog() (also CountryDE::legalTexts()) holds the German notices in German and English. The texts live in the pack's language files resources/lang/{de,en}/legal.php (the exemption reasons in tax.php) and are read through the translator, so in Laravel lang/vendor/quittio-de/{locale}/legal.php overrides single texts. Its fallback locale is de (LegalTexts::FALLBACK_LOCALE). Builder macros add some of them; texts marked "–" are for your own notes.

• REVERSE_CHARGE, INTRA_COMMUNITY_SUPPLY, EXPORT and SMALL_BUSINESS are the exemption reasons of the named tax presets, in every locale the pack ships (CountryDE::locales()). So a notice has one wording in BT-120 and in your notes, including overrides of tax.php.
• Validation and rendering add no text. The builder adds the notes of the presets that require one (StatesInvoiceNote, see Tax presets).
• LegalTexts::text($key, $locale, $replace) returns a text in the language of $locale (en_GB → English) or in German. LegalTexts::localeOf($key, $locale) names the catalog locale it uses.

A text for your own note, here on a prepayment invoice (386), which names the expected date of the service:

use Quittio\Core\Enums\NoteSubjectCode;
use Quittio\Country\DE\Texts\LegalTexts;

$builder->type('386')->note(
    LegalTexts::catalog()->get(LegalTexts::PREPAYMENT, 'de', ['date' => '01.11.2026']),
    NoteSubjectCode::RegulatoryInformation,
);

->de()->advance() adds this note itself (Prepayment invoices). Prepayment invoices (386) without a service date get a DE-USTG-03 warning instead of an error, unless advance() named the expected date or ->de()->serviceDateOpen() states that it is not agreed yet. A prepayment invoice for a payment already received (BT-113) states the date of receipt as VAT point date (->taxPointDate(), BT-7) if it differs from the issue date (DE-USTG-17).

Meta flags#

The pack marks German special cases with meta flags on the invoice (InvoiceData::$meta->flags). The builder macros set them, and the rules read them. Quittio\Country\DE\Support\Flags:

Retention#

CountryDE::retention() returns new RetentionRule(8, fromEndOfCalendarYear: true): invoices are kept for 8 years from the end of the calendar year of issue (section 14b UStG, section 147 AO as amended in 2025). An invoice issued on 3 October 2026 is kept until 31 December 2034. The Managed layer stores this date (retention_until); quittio-managed.retention.years may only lengthen it.

• Suspension. Section 147 (3) AO stays unaffected: documents that matter for taxes not yet time-barred, e.g. during a tax audit or an objection, must not be deleted after the 8 years. The Managed layer keeps them with a legal hold (legal_hold).
• Files. Keep every invoice in the format it was issued in: ZUGFeRD as the PDF with its embedded XML, XRechnung as the XML. At least the structured part must stay unchanged (section 14b.1 (1) UStAE). Keep a PDF sent with an XRechnung as well, and the validation report as evidence (BMF letter of 15 October 2025, marginal no. 35a). RenderedInvoice::save() stores the main output only; save the siblings with ->as('pdf')->save().
• Supervised institutions. For credit and financial services institutions, insurers and investment firms the 8 years apply only to invoices whose 10-year period had not expired on 1 January 2026 (section 27 (40) sentence 2 UStG); for everybody else, to invoices whose period was still running on 31 December 2024.

BMF error classes#

In its letter of 15 October 2025, the German Federal Ministry of Finance (BMF) sorts errors in e-invoices into three classes. Quittio\Country\DE\Rules\BmfErrorClass maps Quittio's findings to these classes ("Rz." is the marginal number in the letter):

• BmfErrorClass::of(ValidationMessage $message) classifies one finding.
• label() returns German for de and English otherwise.
• voidsEInvoice() is true for Format only: the document is then not an e-invoice but an "other invoice" (sonstige Rechnung).
• (new CountryDE)->errorClassification($result) groups the errors and warnings of a ValidationResult by class value:

use Quittio\Country\DE\CountryDE;

$classes = (new CountryDE)->errorClassification($result);   // ['format' => [...], 'business_rule' => [...], 'content' => [...]]

The validation levels are described in Validation; see also Validation: Germany: BMF error classes.

Translations#

The pack ships German and English catalogs in resources/lang/{de,en}/:

• rules.php: message and hint of every rule (BR-DE-*, BR-DEX-*, DE-XRECHNUNG-EXT-01, DE-USTG-*, DE-LEITWEG-ID, DE-LEITWEG-ID-SUSPECT, DE-TAX-NUMBER);
• tax.php: the exemption reason texts of the presets, including de.exempt for VatPreset::exempt() (placeholder :paragraph).

They are registered as the namespace quittio-de (e.g. quittio-de::rules.DE-USTG-03.message). CountryDE::registerTranslations() registers them lazily, so presets work without a Quittio instance. Other locales fall back to English. With Laravel, Laravel's translator is used, so the usual override files apply: lang/vendor/quittio-de/{locale}/rules.php and tax.php, also for additional locales.

CountryDE::locales() lists the locales the pack ships (the directories of resources/lang). Texts defined in PHP cannot be translated through files:

• the legal texts (German and English, fallback German; the four notices taken from the presets follow tax.php);
• the correction policy titles (fallback English);
• the BMF labels and the default interest descriptions (German for de, English otherwise).

The German pack's hooks#

For pack authors, this is how CountryDE fills the CountryPack contract:

Known limitations#

• The legal wording, references and defaults reflect the law and administrative practice of October 2026, when a tax adviser confirmed them (see the legal review and the disclaimer in the README). Later changes of the law need a new release.
• Final invoices: the EN 16931 variants of deductAdvance() (prepaid amount or remainder invoice) exist; the EXTENDED variant does not. The tax review found it unnecessary.
• The shipped base rate table ends with 1 July 2026. Later rates come from quittio.countries.de.base_rates or php artisan quittio:base-rate:update (see Base rate table).
• The documents layer checks the section 288 (5) BGB flat rate within one reminder (once per claim, not for consumers); across reminders the application or the Managed layer must track it.
• Distance sales (section 3c UStG) cannot be told from the data; DE-USTG-12 only warns about possible ones.
• Tax numbers are checked for format and check digit, not against the list of tax offices. Territories without a distinct postcode cannot be detected.
• The pack defines no buyer country rules, exporters (e.g. DATEV) or readers yet.

Other countries#

These packs are released with the same version as the rest of Quittio, but are not part of quittio/quittio. Their legal wording, rules and defaults have not been reviewed by a tax adviser of the country yet: check the mentions and rates of your invoices before you rely on them. Each page describes the presets, rules, formats, defaults and what is not included yet.

composer require quittio/country-fr

The packs declare themselves in their composer.json, so Laravel finds them after the installation; without Laravel, pass them to Quittio::create(), e.g. Quittio::create(['country' => 'FR'], [new CountryFR]) (Registering packs).

How a pack is selected#

This and the following sections are for authors of country packs, and for readers who want to know how Quittio picks a pack. A country pack implements Quittio\Core\Countries\CountryPack, usually by extending Quittio\Core\Countries\AbstractCountryPack, which supplies neutral defaults for every hook (every method of the contract). A pack may only add or tighten rules; it never relaxes EN 16931.

DefaultCountryResolver picks the packs for every run: render, check, prepare, documents, cancellations and the validation of incoming files.

1. Leading pack (seller side). Quittio takes the first of these values that is set:

   • the country passed to the run (->country('AT') on the pending invoice, RenderOptions::$country);
   • the seller's country code (BT-40);
   • the configured default country (quittio.defaults.country, core config key country);
   • otherwise XX.

   The registry returns the installed pack for that code. A country without a pack of its own takes the pack of the country whose VAT territory it belongs to (VatTerritory::vatCountry()): a seller in Monaco the French pack, a seller in Liechtenstein the Swiss pack. Otherwise Quittio uses a generic pack (CountryGeneric).

2. Buyer pack. If the buyer's country code (BT-55) is set and differs from the leading pack's code, the installed pack of the buyer's country (or of the country whose VAT territory it belongs to) is added, unless it is the leading pack. No generic pack is created for the buyer.

use Quittio\Laravel\Facades\Quittio;

Quittio::make($invoice)->country('DE')->render();   // force the leading pack

What each side contributes:

"Domestic" means that seller and buyer lie in the same VAT territory (see VatTerritory), or that the buyer has no country code. A buyer in a territory excluded from the seller's VAT territory (e.g. Büsingen for Germany) is cross-border. Without a buyer pack of its own, the format rules of the leading pack still apply to it.

Without a pack for the seller's country, CountryGeneric applies: EN 16931 rules only, international formatting and neutral defaults. Validation then reports the warning QUITTIO-GENERIC-COUNTRY (L3, BT-40): "No country pack is installed for the seller country :value. Only EN 16931 rules are checked; national mandatory information is not validated." ResolvedCountries::isGeneric() and CountryGeneric::isGeneric() tell this case apart.

With the Managed layer, the issuer's country selects the pack for numbering and retention. The leading pack of an issued invoice is stored with it (country_pack) and used again for re-rendering and corrections (see Managed layer).

Registering packs#

A pack must be registered before Quittio can use it. The German pack registers itself in Laravel.

Laravel#

Laravel finds packs in three places. All of them are instantiated through the container, so constructors may use dependency injection:

1. Composer metadata. Every installed package and the root composer.json of your application may declare packs. quittio/country-de declares itself this way, so composer require quittio/country-de (or quittio/quittio, which contains it) is all you need. Classes that do not exist are skipped.

   jsonCopy

   "extra": { "quittio": { "country-packs": ["Acme\\CountryAT\\CountryAT"] } }

2. Configuration. quittio.countries lists further pack classes; keys are ignored (see Configuration). Arrays under lower-case codes are the settings of a pack, not classes (Settings of your pack).

   phpCopy

   'countries' => [
       'AT' => \Acme\CountryAT\CountryAT::class,
   ],

3. At runtime. Call Quittio::registerCountry(new CountryAT) (facade Quittio\Laravel\Facades\Quittio), e.g. in a service provider. Packs registered this way win over packs with the same code from the other two sources.

A class from the first two sources that is not a country pack throws a ConfigurationException.

Packs are keyed by code(). Of two packs with the same code, the one registered last wins. Discovered packs come first, then the configured classes, then packs registered at runtime. So a subclass of CountryDE in quittio.countries replaces the discovered CountryDE.

php artisan quittio:countries lists the installed packs with code, class, profiles, number of rules and format rules, and the defaults (currency, locale, profile). Without any pack it prints a warning (see Artisan commands).

Without Laravel#

use Quittio\Core\Quittio;
use Quittio\Country\DE\CountryDE;

$quittio = Quittio::create(['country' => 'DE'], [new CountryDE]);
$quittio->registerCountry(new CountryAT);   // further packs at any time

Registering a pack does three things:

• it adds the pack to the CountryRegistry under its upper-case code;
• it registers the pack's profiles() in the profile registry, so that formats, ->profile('xrechnung') and the reader know them;
• it registers translationPath() as the translation namespace quittio-{code} (lower case, e.g. quittio-de).

$quittio->countries() returns the registry: has($code), get($code) (installed pack or null), getOrGeneric($code), all() (array keyed by code) and taxPreset($key) (the preset with this key from any installed pack, or null). Codes are case-insensitive.

Writing your own country pack#

1. Create a Composer package that requires quittio/core.
2. Extend AbstractCountryPack and override only what differs. code() is the one required method.
3. Add tax presets, rules, format rules, mandatory output, layouts and texts as needed, and national output formats with formats() (Formats of your pack).
4. Ship translations in resources/lang/{locale}/rules.php and return the directory from translationPath().
5. Declare the pack in composer.json (extra.quittio.country-packs), so that the Laravel integration finds it. If the pack has Laravel settings, keep them under quittio.countries.{code} (Settings of your pack).
6. Test it with example invoices and, where they exist, the official validation artefacts of the country. Have the legal content reviewed by a local tax adviser.

A minimal pack (values for illustration only):

namespace Acme\CountryAT;

use Quittio\Core\Countries\AbstractCountryPack;
use Quittio\Core\Countries\CountryDefaults;
use Quittio\Core\Countries\MandatoryField;
use Quittio\Core\Countries\MandatoryFieldList;
use Quittio\Core\Countries\RetentionRule;
use Quittio\Core\Data\InvoiceData;
use Quittio\Core\Enums\VatCategory;
use Quittio\Core\Tax\CustomTaxPreset;
use Quittio\Core\Tax\TaxPresetCollection;
use Quittio\Core\Validation\Rules\CallbackRule;
use Quittio\Core\Validation\Rules\Inspect;
use Quittio\Core\Validation\Rules\RuleReporter;

final class CountryAT extends AbstractCountryPack
{
    public function code(): string
    {
        return 'AT';
    }

    public function defaults(): CountryDefaults
    {
        return new CountryDefaults(currency: 'EUR', timezone: 'Europe/Vienna', locale: 'de');
    }

    public function taxPresets(): TaxPresetCollection
    {
        return new TaxPresetCollection([
            CustomTaxPreset::make('at.standard_20', VatCategory::StandardRate, '20'),
        ]);
    }

    public function rules(): array
    {
        return [
            CallbackRule::l3('ACME-AT-01', 'The seller VAT identifier (BT-31) must be stated.', function (InvoiceData $i, RuleReporter $report): void {
                if (! Inspect::filled($i->seller->vatId)) {
                    $report->error('BT-31', 'seller.vatId');
                }
            }, 'quittio-at'),
        ];
    }

    public function formatRules(): array
    {
        return [new ConsumerPdfRule];
    }

    public function mandatoryOutput(InvoiceData $invoice): MandatoryFieldList
    {
        return new MandatoryFieldList([new MandatoryField('seller.vatId', 'VAT identifier of the seller')]);
    }

    public function retention(): RetentionRule
    {
        return new RetentionRule(7);
    }

    public function translationPath(): string
    {
        return dirname(__DIR__).'/resources/lang';
    }
}

The format rule of the example sends invoices to consumers as PDF:

use Quittio\Core\Data\InvoiceData;
use Quittio\Core\Formats\FormatChoice;
use Quittio\Core\Formats\FormatRegistry;
use Quittio\Core\Formats\FormatRule;

final class ConsumerPdfRule implements FormatRule
{
    public function resolve(InvoiceData $invoice): ?FormatChoice
    {
        return $invoice->buyer->isConsumer
            ? new FormatChoice(FormatRegistry::PDF, null, 'Invoice to a consumer.')
            : null;   // null: the next rule or the default choice decides
    }
}

The German translation of the rule, in resources/lang/de/rules.php:

// "The seller's VAT identifier (UID, BT-31) must be stated." / "Set ->vatId() on the seller."
return [
    'ACME-AT-01' => [
        'message' => 'Die UID des Verkäufers (BT-31) muss angegeben sein.',
        'hint' => 'Setzen Sie ->vatId() beim Verkäufer.',
    ],
];

Presets of your pack#

A preset implements Quittio\Core\Tax\TaxPreset:

• CustomTaxPreset::make(string $key, VatCategory $category, BigDecimal|int|string|null $rate = null, VatExemptionReasonCode|RawCode|string|null $code = null, array|string|null $reason = null) builds a preset ad hoc. $reason is a text or locale => text. A plain string counts as English; without a locale the English text is used.
• For many presets a backed enum is convenient, as Quittio\Country\DE\Tax\VatPreset shows.
• TaxPresetCollection offers add(), has($key), get($key) (throws InvalidArgumentException for unknown keys), count() and iteration.

A preset is applied per line with ->vat($preset). The line stores category, rate, reason, code and the preset key (LineVat::$presetKey), so that rules can recognise it (see Building invoices: tax presets).

Rules of your pack#

A rule implements Quittio\Core\Validation\Rule (code(), level(), check(InvoiceData, ValidationContext): iterable<ValidationMessage>). CallbackRule::l3($code, $fallback, $check, $namespace) (business rules) and CallbackRule::l7(...) (plausibility) cover most cases. The closure receives the invoice and a RuleReporter:

• error(?string $bt = null, ?string $path = null, array $replace = []), warning(...) and info(...) add a finding with business term and data path;
• context() returns the ValidationContext: profile, countryPacks (leading pack first), locale, option($key) (e.g. option('syntax') with the Syntax that will be written), profileIs(...$keys), leadingCountry(), hasCountry($code).

Messages:

• They come from the catalog key {namespace}::rules.{code} with the entries message and hint, in the validation locale or English. Without an entry, the English $fallback is used.
• :name placeholders are replaced from $replace.
• Use the namespace quittio-{code} that registration gives your translationPath().

The rules of a pack run in every format, also for a plain PDF. Profile specific rules belong to a profile class (see Formats and profiles). See Validation for levels and results.

Format rules of your pack#

Quittio\Core\Formats\FormatRule::resolve(InvoiceData $invoice): ?FormatChoice returns a FormatChoice(string $format, ?string $profile = null, ?string $reason = null) or null.

• Rules run in order; the first non-null choice wins.
• The resolver consults the leading pack for domestic invoices and the buyer's pack for cross-border invoices to businesses.
• An explicit format always wins.
• A choice of zugferd or cii is upgraded to EXTENDED when EXTENDED features are used.

Formats of your pack#

AbstractCountryPack implements Quittio\Core\Countries\Capabilities\ProvidesFormats with empty defaults. Quittio::registerCountry() registers what a pack returns:

• formats(): list<OutputFormat>, e.g. a national format with its syntax and allowed profiles; a format with the key of a registered one replaces it.
• formatAliases(): further names, e.g. ['xrechnung' => 'xrechnung-cii'].
• serializers(): list<XmlSerializer> for syntaxes the core does not write; a serializer replaces the one of its syntax.

Germany brings XRechnung this way (Quittio\Country\DE\Formats\XRechnungFormats).

Capabilities of your profiles#

Profiles declare what they can transmit with interfaces in Quittio\Core\Profiles\Capabilities, instead of the core checking profile keys:

Builder macros of your pack#

A pack that offers builder helpers registers one macro named after its code, which returns an object with the helpers: InvoiceBuilder::macro('at', fn () => new AustrianInvoice($this)), used as ->at()->…. Germany uses ->de() (GermanInvoice). Ship an IDE stub for the macro, as packages/country-de/stubs/InvoiceBuilder.stub.php does.

Other hooks of your pack#

• paymentQr(): a Quittio\Core\Pdf\Qr\PaymentQrGenerator (key(), supports(InvoiceData), payload(InvoiceData, array $options = []): ?string) for the QR mode auto.
• addressFormatter(): a Quittio\Core\View\AddressFormatter (format(Address $address, array $nameLines = [], ?string $senderCountry = null, ?string $locale = null): list<string>).
• profiles(): national profiles, usually extending Quittio\Core\Profiles\AbstractProfile. They are registered with the pack.
• referenceRates() (capability ProvidesReferenceRates): the reference interest rate of the late payment law, so that Quittio\Core\Dunning\DefaultInterest::forCountry($pack) calculates default interest (DunningLaw).
• complete() (capability CompletesInvoices): adds what the law of the country expects to an invoice before it is rendered, e.g. a notice for consumers. It receives the settings of the pack (quittio.countries.{code}, core: Quittio::create(['countries' => ['{code}' => [...]]])). Germany adds the default notice for consumers (Default notice for consumers).

Settings of your pack#

A pack that needs settings in Laravel (rates, credentials of a national portal, …) keeps them under quittio.countries.{code} with its lower-case code, as the German pack does with quittio.countries.de (Configuration). Do not add a top-level configuration such as quittio-at. In the pack's service provider:

namespace Acme\CountryAT\Laravel;

use Illuminate\Support\ServiceProvider;

final class AustriaServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Defaults; the keys of config/quittio/countries/at.php or of 'countries' => ['at' => […]] win.
        $this->mergeConfigFrom(__DIR__.'/../../config/countries/at.php', 'quittio.countries.at');
    }

    public function boot(): void
    {
        if ($this->app->runningInConsole()) {
            // quittio:install publishes every tag quittio-{code}-config.
            $this->publishes([__DIR__.'/../../config/countries/at.php' => $this->app->configPath('quittio/countries/at.php')], 'quittio-at-config');
        }
    }
}

• Ship the defaults as config/countries/{code}.php and publish them to config/quittio/countries/{code}.php; Laravel loads that file as quittio.countries.{code}.
• Name the publish tag quittio-{code}-config, so that php artisan quittio:install publishes it with config/quittio.php.
• Read the settings with config('quittio.countries.at.…'), and only in Laravel code (the service provider, commands); the pack class itself takes its values as constructor arguments or through Quittio\Core contracts, so it works without Laravel.
• Declare the provider in composer.json (extra.laravel.providers), as quittio/country-de does with GermanyServiceProvider.

The CountryPack contract#

Every method of Quittio\Core\Countries\CountryPack, its default in AbstractCountryPack and where Quittio uses it:

Optional capabilities (the interface gets new methods only in a major release, new abilities come as capabilities):

CountryDefaults#

new CountryDefaults(currency: 'EUR', timezone: 'UTC', locale: 'en', paper: 'A4', letterLayout: 'free', profile: 'en16931', requiredLocales: [], paymentQr: 'girocode', vatPreset: null, smallBusinessVatPreset: null)

CorrectionPolicy#

The default handling of cancellations and corrections (see Managed: cancellations and corrections).

The kinds Quittio reads:

• cancellation and cancellation_self_billed: the title of Quittio::cancellation();
• correction: the title of a Managed corrected invoice;
• self_billed: the PDF/HTML title and file name of self-billed invoices, after a title set in the presentation.

The sign strategy of a cancellation comes from the call, then quittio.corrections.cancellation_strategy, then the pack. The correction strategy comes from quittio-managed.correction.strategy, then the pack.

DunningLaw#

Statutory late payment values; amounts and percentage points are decimal strings.

Quittio's documents do not read these values. Quittio\Core\Dunning\DefaultInterest calculates default interest from them and the reference rates of a pack that implements Countries\Capabilities\ProvidesReferenceRates (referenceRates(): Dunning\ReferenceRates with rateOn() and periods()): DefaultInterest::forCountry($pack)->calculate($amount, $from, $until). A pack without reference rates works only when its law fixes both rates (DunningLaw::hasFixedRates(), e.g. Switzerland); otherwise forCountry() throws a ConfigurationException. Germany provides the Basiszinssatz this way (DefaultInterest); a pack of another country implements ReferenceRates, e.g. for the ECB main refinancing rate, on top of Quittio\Core\Support\DatedValues.

NumberingRules#

Used by Managed numbering (see Managed: numbering).

RetentionRule#

new RetentionRule(int $years, bool $fromEndOfCalendarYear = true). until(Date $issueDate): Date returns the last day of the retention period: 31 December of the issue year plus $years, or, with fromEndOfCalendarYear: false, the issue date plus $years. The Managed layer stores this date with every issued invoice; quittio-managed.retention.years may only lengthen it.

LegalTextCatalog#

new LegalTextCatalog(array $texts = [], string $fallbackLocale = 'en') with $texts as key => [locale => text].

• has(string $key): bool
• get(string $key, ?string $locale = null, array $replace = []): ?string: the text in $locale, else in the fallback locale, else the first variant; null for unknown keys. :name placeholders are replaced from $replace.

Mandatory output#

mandatoryOutput() names values the rendered PDF must show for one invoice, in addition to the base fields every PDF needs. After rendering, the mandatory field guard checks that the template printed them (see Templates: mandatory field guard).

new MandatoryField(string $accessKey, string $description, ?string $legalBasis = null). The access key is a view model path:

• | separates alternatives, & combines paths that must all be printed;
• [*] stands for every index, e.g. vatRows[*].amount;
• a path counts only where the view model has a value: null values and empty lists are not required, and a field whose alternatives all have no value is skipped.

MandatoryFieldList::merge() combines two lists; for equal access keys the later field wins. MandatoryFieldGuard::notePath($invoice, $matches) returns the view model path of the first note that matches a callback (legalNotes[i] for regulatory, legal and tax notes, notes[i].content|notes[i].html otherwise), so that a pack can require a specific note.

Letter layouts#

letterLayouts() returns Quittio\Core\View\LetterLayout objects by name. CountryDefaults::$letterLayout names the default; the presentation property letterLayout (Laravel: pdf.layout) selects another one. free is always available; an unknown name throws a ConfigurationException. Values are millimetres from the top left corner of the first page:

letterheadHeight(float $pageMarginTop) returns the space above the address field: addressTop minus the top page margin (15 mm on the first page in the default templates). See Templates: letter layouts for how the default templates use them; the German layouts are in DIN 5008 letter layouts.

VatTerritory#

Quittio\Core\Countries\VatTerritory tells the EU VAT territory (Art. 5 to 7 of Directive 2006/112/EC) from a country code and a postcode. The format resolver, the German rules and the core plausibility checks use it; packs can use it in their own rules.

Northern Ireland belongs to the territory for goods only ($goods = false excludes it). Territories that are excluded and recognised by postcode:

• Germany: Büsingen am Hochrhein (78266) and Heligoland (27498);
• Spain: the Canary Islands (35xxx, 38xxx), Ceuta (51xxx) and Melilla (52xxx);
• Italy: Livigno (23041) and Campione d'Italia (22061);
• Finland: the Åland Islands (22xxx);
• Greece: Mount Athos (63086);
• France: the overseas territories (97xxx, 981xx to 989xx; Monaco 980xx stays France).

Territories without a distinct postcode (e.g. the part of Cyprus not controlled by the government) cannot be detected.