> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.invoice-api.xhub.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.invoice-api.xhub.io/_mcp/server.

# Changelog

What changed in the Invoice.xhub API — new countries and formats, new endpoints, and changes that
affect the requests you send or the data you get back.

An RSS feed of this page is available at `/changelog.rss` — subscribe to hear about changes
before they reach your integration.

## November 1, 2026

## Upcoming enforcement — all dates at a glance

Each of these cases gets a warning today and is rejected from the date shown. Details are in the entry of the week
the warning was introduced. Every pending rule also answers with `SPEC_RULE_PENDING` and `enforceFrom`; send
`enforcePending: true` to get the rejection today and test your integration.

| From       | What is rejected                                                                               | Code                                  | Details    |
| ---------- | ---------------------------------------------------------------------------------------------- | ------------------------------------- | ---------- |
| 2026-11-11 | Empty `buyer.countryCode`, sellers in EU member states                                         | 422 `BUYER_COUNTRY_REQUIRED`          | 2026-10-18 |
| 2026-11-11 | AT ebInterface: seller and buyer phone and email move into the address block (document change) | —                                     | 2026-10-11 |
| 2026-11-14 | Card payment without a card account                                                            | `CARD_ACCOUNT_REQUIRED`               | 2026-10-11 |
| 2026-11-14 | BE Factur-X: credit transfer without payment account                                           | `PAYMENT_ACCOUNT_REQUIRED`            | 2026-10-11 |
| 2026-11-14 | FR and BE: credit transfer without payment account                                             | `CREDIT_TRANSFER_ACCOUNT_REQUIRED`    | 2026-10-11 |
| 2026-11-14 | Sellers outside the EU: above the small-invoice limit without the buyer's country              | `BUYER_COUNTRY_REQUIRED`              | 2026-10-11 |
| 2026-11-15 | ES Facturae: rules `ES-FAE322-055` and `ES-FAE322-056` (empty invoice number)                  | rule id                               | 2026-10-11 |
| 2026-11-16 | A date that is readable but not `YYYY-MM-DD`                                                   | 400 `INVALID_DATE`                    | 2026-10-18 |
| 2026-11-17 | Allowance or charge on document level without a tax category                                   | `ALLOWANCE_TAX_CATEGORY_REQUIRED`     | 2026-10-11 |
| 2026-11-17 | Invoice without the buyer's name where the seller's country requires it                        | `RECIPIENT_REQUIRED`                  | 2026-10-11 |
| 2026-11-17 | Quantity that rounds to 0 (AT, PT, IT, HU formats)                                             | `QUANTITY_ROUNDS_TO_ZERO`             | 2026-10-11 |
| 2027-01-01 | Invalid block inside a `columns` block of an inline PDF template                               | 400, warning `TEMPLATE_BLOCK_INVALID` | 2026-10-25 |

Announced without a date yet (a later release, announced in advance): the `FIELD_TOO_LONG` limits and
`INVOICE_LINES_ABOVE_MODE_LIMIT` (see 2026-10-04), and the removal of `countrySpecific.peppolEndpointId`
(see 2026-09-27).

## PDF templates over the REST API

You can now store, update and read PDF templates with your API key:

* `POST /api/v1/pdf/templates` stores a BlockTemplate for your organization and returns it with its `id` (201). Use
  the `id` as `templateId` in `POST /api/v1/pdf/generate` or in `formatOptions.templateId` of the invoice routes. The
  template also appears in the Console under PDF templates.
* `PUT /api/v1/pdf/templates/{id}` changes only the fields you send. `isActive` is not accepted (400
  `UNSUPPORTED_FIELD`); system templates are read-only (403 `SYSTEM_TEMPLATE_READ_ONLY`).
* `GET /api/v1/pdf/templates/{id}` returns a template of your organization or a system template.

Body fields: `name` and `template` (required), `documentType` (default `invoice`), `description`, `sampleData`,
`pageSettings`, `isDefault`. `isDefault: true` makes the template the default of the **whole organization**.

Entitlements: `pdf:template:create`, `pdf:template:update`, `pdf:template:read` — on plans that include the PDF template
editor, not on the Free plan. Only API keys you created in the Console may use these routes; session keys get 403
`SESSION_KEY_FORBIDDEN`. The body is limited to 2 MiB (413 `PAYLOAD_TOO_LARGE`). Not metered.

## Send the generated invoice by e-mail

`POST /api/v1/invoice/{countryCode}/{format}/generate` takes a new optional field `emailRecipients` (**paid plans
only**): up to 10 recipients, each an address or `{ email, subject?, body? }` (`subject` 1–300, `body` 1–10,000
characters, sent as plain text).

* After a successful generation, the document is sent as attachment — the hybrid PDF for ZUGFeRD / Factur-X, otherwise
  the XML (the `data` of the response with its `mimeType`).
* A bare address gets a default subject (`Rechnung <number> von <seller>` for `/DE` and `/AT`, otherwise
  `Invoice <number> from <seller>`) and a default text. Duplicate addresses (case-insensitive) are sent once.
* The sender is our invoice mail address with your organization's name; replies go to the contact e-mail of your
  seller profile.
* The response is the same as without the field; the result per recipient is in your generation log.
* Without an active paid subscription the call is rejected with **403** before anything is generated. A generation that
  answers 422 sends nothing. Sending does not count as extra usage.

## TRAFFIQX delivery: planned endpoint

`POST /api/v1/traffiqx/send` (tag `TRAFFIQX`) is listed in the reference. Delivery via the TRAFFIQX network is planned
for Q1/2027 and not implemented yet: the endpoint answers **501** `NOT_IMPLEMENTED_PLANNED` with the planned quarter and
the roadmap URL. The request body is ignored; nothing is billed.

## October 25, 2026

## Blocks inside a column of an inline PDF template — rejected from 2027-01-01

`/generate` checks the `header`, `body` and `footer` blocks of `formatOptions.template`, but blocks inside a column of a
`columns` block went to the renderer unchecked. They are now checked with the same rules, including columns in header
and footer and columns inside columns.

* **Until 2026-12-31:** the block is rendered as sent, with the warning `TEMPLATE_BLOCK_INVALID`. `field` is the path
  (for example `formatOptions.template.body.blocks.1.data.columns.0.blocks.0`), `params.rejectFrom` is `2027-01-01`.
* **From 2027-01-01:** such a block is rejected with **400**, with the same finding as a top-level block.
* `enforcePending: true` gives you the 400 now.

Templates selected with `templateId`, and country templates, are not checked here.

**Do I need to act?** If you see `TEMPLATE_BLOCK_INVALID`, change the block at `field` before 2027-01-01.

## Currency code checked against ISO 4217

`invoice.currency` must be an ISO 4217 code — three upper-case letters such as `EUR`. Before, whether a wrong code was
rejected depended on the format. On `/generate`, `/validate`, `/embed` and `/embed/upload`, a code that is not in
ISO 4217 now adds the warning `CURRENCY_CODE_UNKNOWN` with `field: "currency"`. The answer is otherwise unchanged. The
check is case-sensitive (`eur` is not `EUR`); we do not change your code. A code that is in ISO 4217 but not allowed by
a format (for example `BGN` in EN 16931) is still checked by that format's rules.

**Do I need to act?** If you see `CURRENCY_CODE_UNKNOWN`, fix the code.

## PDF template: page break, watermark and barcode

`formatOptions.template` now accepts three more block types in `header`, `body` and `footer` (rejected with 400
before):

* **`pageBreak`** — starts a new page; optional `data.label` (max. 100 characters).
* **`watermark`** — text across every page, behind the content; `data.text` required (max. 100). Optional `fontSize`,
  `color`, `opacity` (0–1), `rotation` (−90 to 90), `bold`, `font`.
* **`barcode`** — 1D barcode or Data Matrix; `data.content` required (max. 200, placeholders such as
  `{{invoiceNumber}}` allowed). Optional `format` (`code128` default; `code39`, `code93`, `ean13`, `ean8`, `upca`,
  `upce`, `itf14`, `codabar`, `datamatrix`), `width`, `height` (in `lengthUnit`), `alignment`, `includeText`.

Limits count the characters in the template, before placeholders are filled. `bordered`, `chart`, `formField`,
`repeater` and `toc` are still rejected with 400.

## Dates: preceding invoice date and empty strings

* The `YYYY-MM-DD` rule with the `DATE_NOT_ISO` warning (rejected from 2026-11-16) now also covers the preceding
  invoice date (BT-26): `referencedInvoiceDate`, `precedingInvoiceReferences[].issueDate` and
  `items[].creditedFrom.invoiceIssueDate`.
* An empty string (`""`) in `dueDate`, `deliveryDate`, `delivery.date`, `servicePeriod.start` / `end` or
  `items[].servicePeriod.start` / `end` is left out of the document with the warning `DATE_EMPTY_IGNORED` (`field`).
  Omit the field or send `YYYY-MM-DD`.

## October 18, 2026

## Upcoming enforcement

| From       | What is rejected                                                                                                                                                                                                   | Code                         |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
| 2026-11-11 | Empty `buyer.countryCode`, sellers in EU member states — also where it is accepted today (for example `/DE/pdf/generate`); sellers elsewhere: see the 2026-10-11 entry (2026-11-14, above the small-invoice limit) | 422 `BUYER_COUNTRY_REQUIRED` |
| 2026-11-16 | A date that is readable but not `YYYY-MM-DD`                                                                                                                                                                       | 400 `INVALID_DATE`           |

Until then the answer carries the warnings `BUYER_COUNTRY_REQUIRED` and `SPEC_RULE_PENDING`, or `DATE_NOT_ISO`. With
`enforcePending: true` you get the rejection today.

**Do I need to act?** Always send the buyer's country, and send dates as `YYYY-MM-DD`.

## Dates that are not `YYYY-MM-DD`

On `/generate` and `/embed`, `dueDate`, `deliveryDate`, `delivery.date`, `servicePeriod.start` / `end` and
`taxPointDate` should be `YYYY-MM-DD`. Another readable form (`01.05.2026` is read day first, `05/01/2026`) is written
as the date shown in `warnings[].params.written`, with the warning `DATE_NOT_ISO` (`field`, `params.received`,
`params.rejectFrom`). From 2026-11-16 it is rejected with 400 `INVALID_DATE`. A timestamp such as
`2027-03-15T23:30:00-05:00` writes its date part as sent.

## Changes for callers

* **Factur-X embed with an unreadable delivery note date:** `POST /FR/facturx/embed` with a `deliveryNote.date` that is
  not a real date (for example `31.02.2026`) answers **400** `INVALID_DATE`. Before, it answered 200 and silently left
  the delivery note out.
* **PDF without embedded XML:** `POST /parse` answers **400** `NO_EMBEDDED_XML` (before: 200 with `DE_UNKNOWN_FORMAT`);
  `POST /convert` answers 400 `NO_EMBEDDED_XML` instead of 422 `PARSE_FAILED`.
* **`/parse` payment term:** `invoice.paymentTerms.dueDays` is filled only from the document. Without a term in the
  document the field is absent instead of a fixed default.

**Do I need to act?** Handle `400 NO_EMBEDDED_XML` and a missing `dueDays` if you rely on them.

## PDF template: the reference describes what the renderer does

The PDF output does not change. The API reference for `formatOptions.template` now documents:

* 13 more `table` fields that already worked: `carryOver`, `carryOverByTaxRate`, `carryOverColumn`,
  `carryOverColumns`, `carryOverTaxRateField`, `carryOverLabels`, `prepaidReceiptLabels`, `rowFill`,
  `alternateRowFill`, `bodyTextColor`, `fontFamily`, `numberFormat`, `dateFormat`. A wrong type for one of them is now
  rejected with **400**.
* `{{page.current}}` and `{{page.total}}` in header and footer blocks.
* `repeatOnAllPages`: header on every page by default, footer on the last page only by default.
* Block lengths are read in the template's `lengthUnit` (not always points).
* `dataSource` takes any array in your invoice data.
* Accepted block types: text, table, summary, keyvalue, columns, image, spacer, line, qrcode.

**Do I need to act?** If you set `lengthUnit` to `mm` or `inch`, give block lengths in that unit.

## October 11, 2026

## Upcoming enforcement

This week's releases change the answer to some requests. Where a rule gets stricter, you first get a warning
`SPEC_RULE_PENDING` with `enforceFrom`; from that date the request is rejected. Send `enforcePending: true` to get the
rejection today and test your integration.

| From       | What is rejected                                                                                                                                                                                                  | Code                               |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| 2026-11-11 | AT ebInterface: phone and email of seller and buyer move from `eb:Contact` into the address block (document change, warning until then)                                                                           | —                                  |
| 2026-11-14 | Card payment without a card account                                                                                                                                                                               | `CARD_ACCOUNT_REQUIRED`            |
| 2026-11-14 | BE Factur-X: credit transfer without payment account                                                                                                                                                              | `PAYMENT_ACCOUNT_REQUIRED`         |
| 2026-11-14 | FR and BE: credit transfer without payment account                                                                                                                                                                | `CREDIT_TRANSFER_ACCOUNT_REQUIRED` |
| 2026-11-14 | Sellers outside the EU: invoice above the small-invoice limit without the buyer's country                                                                                                                         | `BUYER_COUNTRY_REQUIRED`           |
| 2026-11-15 | ES Facturae: empty invoice number (`ES-FAE322-056`) and rule `ES-FAE322-055`                                                                                                                                      | rule id                            |
| 2026-11-17 | Document-level allowance or charge without a tax category, in every format                                                                                                                                        | `ALLOWANCE_TAX_CATEGORY_REQUIRED`  |
| 2026-11-17 | Creating an invoice (`/generate`, `/embed`, `/convert`, PDF) without the buyer's name where the seller's country requires it (23 countries)                                                                       | 422 `RECIPIENT_REQUIRED`           |
| 2026-11-17 | Small invoice without the buyer's name, sellers in 22 EU countries and Switzerland, also with reverse charge or intra-EU supply (`K`): `/validate` and the PDF route warn until then, then the invoice is invalid | `RECIPIENT_REQUIRED`               |
| 2026-11-17 | A quantity that becomes 0 after the format's rounding (AT ebInterface, PT CIUS-PT, IT FatturaPA, HU NAV)                                                                                                          | `QUANTITY_ROUNDS_TO_ZERO`          |

Small-invoice limits for the buyer's name are those of the seller's country (for example FR up to 150 EUR, PL up to
450 PLN, PT up to 100 EUR). Sellers in AE, AU, CA, GB, IS, JP, LI, NO, NZ, OM and US: no change for small invoices
without the buyer's name. E-invoice formats that already answered 422 with `BR-07` keep doing so. With
`enforcePending: true` the error is `RECIPIENT_REQUIRED` on `buyer.name` in `errors`.

## Stricter now (no warning phase)

* **Impossible invoice date** (for example `2026-02-30`): `/DE/validate` answers `valid: false` with
  `INVOICE_DATE_NOT_XS_DATE` at `issueDate`; `/convert` answers 422 `PARSE_FAILED` with `DE_INVALID_INVOICE_DATE`.
* **Empty `issueDate`:** `/validate` reports `BR-03` instead of `VAL-SYS-005`; `/generate` answers 422 `BR-03` instead
  of 400 `INVALID_DATE`.
* **`/parse` without an invoice date:** `success: false` with `DE_MISSING_INVOICE_DATE` instead of a filled-in date.
* **PDF route:** an unreadable invoice date gives 400 `INVALID_DATE` (before: a PDF printing the raw value); an empty one
  gives 422 `BR-03`.
* **`/validate` and totals (CII):** a VAT breakdown category that no line has is invalid with `AMT_004`, as at
  `/generate`. Wrong totals also report `AMT_00x` next to the format rules.
* **`buyer.taxableRecipient`** must be `true` or `false`; other values give 400 (`null` = not sent). In Portugal, with
  `true`, a small invoice without the buyer's `vatId` or `taxId` gets 422 `RECIPIENT_REQUIRED`.
* **Hungary (NAV):** `countrySpecific.customerVatStatus` now takes effect. `PRIVATE_PERSON` omits buyer name, address and
  tax number from the NAV report; a status contradicting the buyer's tax number gives 422
  `NAV_CUSTOMER_STATUS_CONFLICT`.
* **Portugal (`/PT/ubl/generate`):** `orderNumber` with 21–100 characters gives 422 `DT-CIUS-PT-012`; `quoteNumber`
  over 20 characters together with an order number gives 422 `DT-CIUS-PT-013`. Before, the values silently went missing.

## Accepted now (was rejected)

* `/validate` adds a missing VAT ID country prefix (BR-CO-09) with `VAT_ID_COUNTRY_PREFIX_ADDED`.
* CII (ZUGFeRD, Factur-X): a missing exemption reason gets the standard text with `TAX_EXEMPTION_REASON_SUBSTITUTED`.
* ES Facturae: `/validate` now runs the rules (`passed` instead of `not_run`).
* AT ebInterface: prices with many decimals are kept exactly.
* `/parse` (UBL): a missing trading name is taken from the legal name.
* Peppol UBL: a price base quantity ≤ 0 is ignored with `PRICE_BASE_QUANTITY_IGNORED` (before: 422
  `PEPPOL-EN16931-R121`).
* `/convert`: DE CII sources with direct-debit mandate details in the schema position; IT FatturaPA with spaces in the
  IBAN; `zugferd` (DE, CH) with direct debit (code 59) and no seller bank account.

## Same request, different document

* Discounts are written in Factur-X, ISDOC, FatturaPA and NAV. A percentage discount with a price base quantity is
  quantity × price / base quantity.
* Payment means: Factur-X writes the seller's IBAN/BIC for credit transfer, and the code follows the payment method (for
  example 30 instead of 1), also in UBL. `cash` with a seller IBAN is code 10. `direct_debit` with a mandate now writes
  the seller's IBAN.
* HU NAV: unit price keeps all decimals; exchange rate up to 6 decimals (more are rounded with
  `EXCHANGE_RATE_DECIMALS_ROUNDED`).
* DE small business (§ 19 UStG): category `E` with the note text, no BT-121 code.
* ES Facturae: `BatchIdentifier` is the seller's tax number followed by the invoice number (`ES-FAE322-039`).
* CH QR bill: header version 0200.
* Portugal CIUS-PT: order number (BT-13) and quote number (BT-14) are now in the document.
* `/DE/xrechnung/validate` answers with the same codes as `/DE/validate` and `/generate` (for example
  `DE_SELLER_CONTACT_001` with rule `BR-DE-2`).
* AT ebInterface: wrong decimals give `AT-EBI61-004` instead of `XSD-ERROR`.
* An attachment with only a description: 422 `BR-52` instead of 400.
* `POST /api/v1/lroe/submit` without Bizkaia credentials: 409 `LROE_CREDENTIAL_MISSING` / `LROE_NRS_MISSING` or 503
  `ESCROW_UNAVAILABLE` instead of 500.
* `/convert` with a non-JSON body: 400 `Malformed JSON in request body` instead of 500.
* `DE_REF_002` now names its rule: `BR-DE-15`.

## Parsing and converting

* UBL from CH, CZ, ES, FR, HU, PT: buyer reference (BT-10) is in `countrySpecific.buyerReference`, order number (BT-13)
  in `orderNumber`.
* IBANs arrive without spaces and in capitals, in every input format.
* `paymentMethods[].type` follows one table: 10 `cash`; 30/42/58 `bank_transfer`; 48/54/55 `credit_card`; 49/59
  `direct_debit`; other `other`.
* The payment term comes from the source's due date (BT-9) instead of a fixed 30 days (UBL from FR, CZ, ES, HU, PT;
  KSeF; FatturaPA, ISDOC and Facturae with a due date on the invoice date give 0 days).
* UBL from FR, CZ, ES, HU, PT keeps payment account and means code; French CII keeps payment instructions for every means
  code.
* `/parse` (UBL) returns `seller.legalName` / `buyer.legalName`; CII from DE, CH, NL returns `directDebitMandate`; NAV
  returns `seller.bankAccount.iban`.
* Mandate details outside the CII schema position are read as before but listed in `errors`
  (`DE_DIRECT_DEBIT_MANDATE_OUTSIDE_SCHEMA`, `CH_…`, `NL_…`; NAV: `HU_BANK_ACCOUNT_OUTSIDE_SCHEMA`) while `success`
  stays `true`. If you treat any `errors` entry as failure, check this case.
* Missing party country: new warning `PARTY_COUNTRY_ASSUMED` with field and place.
* `/convert` has a new field `sourceErrors` with the findings from reading the source.

## New

* **`/{country}/{format}/validate` checks a document you received.** Send
  `{ "data": "<base64 XML or PDF>", "filename": "…" }` instead of `invoice`. The file itself is checked against XSD and rulebook; a PDF also gets
  `extractedFromPdf: true`. Billed 1 unit on the format's `parse` entitlement. New answers: 400 `NO_EMBEDDED_XML`, 400
  `FORMAT_MISMATCH`; with both `invoice` and `data`, `invoice` is checked and you get `DATA_IGNORED`.
* **`/fr/ubl` validation follows the file:** Peppol BIS, EXTENDED-CTC-FR (EN 16931 + CTC-FR rules) or EN 16931;
  `results[].format` names the rulebook.
* **`/validate` explains a non-Unified body:** the 400 gains a `hint` (`ValidationHint`) with `code`
  (`BODY_NOT_JSON`, `INVOICE_MISSING`, `INVOICE_LOOKS_LIKE_XML`, `INVOICE_NOT_UNIFIED`), `message` and, where useful,
  `next`. Status, `error` and `success` are unchanged.
* Warning `TAX_SUMMARY_CATEGORY_WITHOUT_LINES` when a breakdown row has a category and rate no line uses.
* Portugal: optional `buyer.taxableRecipient`; `false` lets you omit buyer name and address
  (`TAXABLE_RECIPIENT_CONFLICT` with reverse charge).
* Some formats warn `FIELD_NOT_WRITTEN` when a field has no place in the format.
* `POST /api/v1/lroe/submit` is listed under the tag `LROE`.

## Rule ids, Portuguese VAT numbers, certificates, Hungarian tax numbers

* **ZUGFeRD 2.4 / CII against EN 16931:** a rulebook finding has `code: "SPEC_RULE_FAILED"` and the identifier in
  `rule` (for example `FX-SCH-A-000155`). If you match on `code` values starting with `FX-SCH-A-`, match on `rule`.
* **Portugal (CIUS-PT):** BT-31 and BT-48 carry the `vatId` you send, unchanged. Without it, `PT` plus the checked
  `taxId`. New warnings `BUYER_VAT_ID_PLACEHOLDER`, `BUYER_VAT_ID_MISSING`, `SELLER_VAT_ID_MISSING`. Send `vatId` for
  business customers outside Portugal.
* **PKCS#12 certificates** with an iteration count above 100,000 are refused with `PKCS12_PARSE_FAILED` (TicketBAI,
  Batuz/LROE, connection test). Files exported with default settings are not affected.
* **Hungary:** the tax number check digit follows the official seven-weight rule; valid numbers refused before
  (`HU_TAX_001`, `HU_TAX_002`, `HU_TAX_006`) are now accepted.

## October 4, 2026

## Upcoming enforcement

These limits warn today and will be rejected with **400** in a later release. We will announce that release in
advance — watch for the warnings now.

| Warning                          | Field                                                                    | Limit                                                                       |
| -------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| `FIELD_TOO_LONG`                 | `seller.` / `buyer.` `street`, `additionalStreet`                        | 200 characters                                                              |
| `FIELD_TOO_LONG`                 | `seller.` / `buyer.` `city`                                              | 100 characters                                                              |
| `FIELD_TOO_LONG`                 | `seller.` / `buyer.` `postalCode`                                        | 20 characters                                                               |
| `FIELD_TOO_LONG`                 | `seller.state`, `buyer.state`, `delivery.address.state`, `projectNumber` | 100 characters                                                              |
| `FIELD_TOO_LONG`                 | `attachments`                                                            | 20 attachments; 15 MiB decoded each; 30 MiB decoded together                |
| `INVOICE_LINES_ABOVE_MODE_LIMIT` | `items`                                                                  | 5000 lines including sub-items, on servers without large-invoice validation |

The warnings appear on `/generate`, `/embed` and `/validate`. Leading and trailing spaces do not count, except for
`projectNumber`.

## Sub-items count as lines; depth and body limits

* All lines together — top-level items and sub-items at any depth — may not exceed **25,000**. Above that: **400**
  with `params.code: "TOO_MANY_INVOICE_LINES"`, `count` and `limit`.
* Sub-items may be nested at most **100** levels. Deeper: **400** `SUB_ITEMS_TOO_DEEP` with `depth` and `path`.
* The request body is limited to **128 MiB** on every route. This was already the limit; it now answers **413**
  with `error: "PAYLOAD_TOO_LARGE"` and `limit` in bytes. Attachments travel in the same body.

The plan limit `TOO_MANY_LINE_ITEMS` still counts top-level items only.

## Czech ISDOC in a foreign currency needs the exchange rate

If `currency` is not `CZK`, `/CZ/isdoc/generate` needs `countrySpecific.exchangeRate` (CZK for 1 unit of your
currency). Without it the request fails with `CZ_ISDOC_EXCHANGE_RATE_REQUIRED` on that field. With it, the document
carries all amounts in both currencies, as ISDOC requires. There was no warning phase: the old output ("1 EUR = 1 CZK",
no CZK amounts) never passed the ISDOC check. CZK invoices do not change.

## Unreadable dates answer 400 `INVALID_DATE`

On `/generate`, `/embed` and `/convert`, in all formats, a date that cannot be read (for example `not-a-date`, or
`2026-13-01` in a `/convert` source) now answers **400** with `code: "INVALID_DATE"` and the `field`. Before, it failed
at the XML schema with 422 and no field. Facturae, myDATA and NAV still answer 422 `XSD-ERROR` for now.

**Do I need to act?** If you handle 422 for bad dates, also handle 400 `INVALID_DATE`. See the 2026-10-18 entry for
readable dates that are not `YYYY-MM-DD`.

## Invalid unit codes are replaced, not rejected

An `items[].unit` that is not a UN/ECE Recommendation 20 code is written as `C62` ("one"), together with the price base
unit, and the response warns with `UNIT_CODE_SUBSTITUTED` at `items.N.unit`. Before, some formats rejected the invoice
(for example Peppol rule R130). Send a Rec 20 code such as `H87` or `HUR` to avoid the warning.

## `null` means omitted

On `/generate`, `/embed` and both `/validate` routes, an optional field sent as `null` is the same as leaving it out.
An object whose fields are all `null` counts as omitted. A required field sent as `null` is rejected like a missing one
(400 with the path) — for example `servicePeriod` with `start` set and `end: null`.

**`payloadHash` changes once** for invoices that contain `null` fields: it is now the hash without them. If you use
`payloadHash` or `X-Payload-Hash` as a key, expect a new value for those invoices.

In the OpenAPI file, optional input fields are nullable and request line items use the type `InvoiceLineItemInput`.
Response types do not change.

## 400 validation errors are documented

A request body that fails the input check answers `{ "success": false, "error": [ … ] }`, each entry with `code`,
`path` and `message` (plus `maximum`, `minimum`, `expected`, `values` or `keys` where relevant). This was always the
behaviour; the 400 of every JSON route now lists it as `RequestValidationError`. Regenerate your client to read the
field paths. `POST /api/v1/invoice/convert` is not affected.

## Busy server: 503 with `Retry-After`; server errors carry an `errorId`

* Generating, embedding, converting and validating run with a limited number of parallel calls, per server and per
  organization. If no slot is free within about 2 seconds you get **503** `SERVER_BUSY` with a `Retry-After` header.
  Nothing is billed. Wait and retry.
* A **500** now has `code: "INTERNAL_ERROR"` and an `errorId` (UUID) — send it to support. The answer never contains
  internal details. This also covers `GET /api/v1/verifactu/chain/{vatId}/export`, `POST /api/v1/lroe/submit` (no more
  `detail` field) and `POST /api/v1/pdf/attachments`.
* A brief database problem gives **503** `SERVICE_UNAVAILABLE` with `errorId` and `Retry-After` instead of 500.
* A call that ends with a 5xx is not billed.

All changes are additive; `error` and `message` remain.

## New endpoint: upload your carrier PDF as a file

`POST /api/v1/invoice/{country}/{format}/embed/upload` takes the `/embed` request as `multipart/form-data`: `pdf` (file
part), `invoice` (JSON text), optional `validate` and `formatOptions`. Same checks, entitlement and price as `/embed`.

* **Binary answer:** with `Accept: application/pdf` you get the hybrid PDF itself — only when there is nothing to
  report (check passed or skipped, no `warnings`, no `carrier.warnings`). Otherwise you get the JSON answer. Headers:
  `X-Validation-Status`, `X-Hash`, `X-Payload-Hash`, `X-Result-Rechecked`.
* **Large carriers:** up to **64 MiB** on this route. Above 15 MiB the result is not re-opened for checking
  (`PDF_RESULT_NOT_RECHECKED`, `X-Result-Rechecked: false`). If the embedding service is unavailable for such a
  carrier: **503** `EMBED_UNAVAILABLE` with `Retry-After: 60`, not billed.
* **Signed carriers (both embed routes):** we keep the signature valid. If that is not possible, you get
  `CARRIER_SIGNATURE_INVALIDATED` (or `CARRIER_CERTIFICATION_INVALIDATED`) instead of a silently broken signature.
* **New warning on both embed routes:** `CARRIER_FONTS_NOT_CHECKED` when the carrier could not be opened for the font
  check. Nothing is rejected.

`/embed` itself does not change and never answers binary.

## Rulebook check with a time limit

The rulebook check now stops after a time limit, mainly for ZUGFeRD / Factur-X EXTENDED with many sub-items. You still
get your document (200) with the warning `SELF_CHECK_INCOMPLETE`. With `validate: true`, `validation.status` is
`not_run`, `valid` is `null` and `validation.reason` is `time-budget`. A second new reason, `sidecar-unavailable`,
replaces `transform-failed` when our check service did not answer for a document too large to check without it.

## Smaller changes

* **ISDOC:** a VAT category ISDOC cannot carry (anything except `S`, `O` and domestic `AE`) now adds the warning
  `ISDOC_TAX_CATEGORY_NOT_REPRESENTABLE` (`params.category`, `params.positions`, `lossy: true`). Nothing is rejected.
* **XRechnung UBL, category `E` without a reason:** the substituted reason is now the text `Exempt from VAT` without a
  code, instead of `VATEX-EU-132`. With `countrySpecific.isKleinunternehmer: true` it is the small-business notice valid
  on `issueDate`. Warning `DE_TAX_EXEMPTION_REASON_SUBSTITUTED` as before. A reason you send is never changed; CII is
  unchanged.
* **PDF:** the default templates no longer need `seller.bankAccount.iban` (the IBAN line is left out) or `buyer.name`.
  On the Swiss and Liechtenstein payment part without a payer, the "Payable by (name/address)" box is shown empty, as
  SIX IG v2.4 requires. Invoices with buyer, IBAN and buyer country look exactly as before.

## September 27, 2026

## Taxable amount per VAT category is checked — and your tax breakdown is written as sent

This can reject a request that passed before.

Each `taxSummary` entry has a `netAmount` (BT-116, the taxable amount). It must match the line net amounts of that
category and rate, plus charges, minus allowances. When you ask for an e-invoice format, we now check this. If it does
not match, you get **422** with error code `AMT_004`, field `taxSummary[n].netAmount`, and the rule (for example
`BR-S-08`) in the message. The message names the expected sum.

The tolerance is the one in the official rule set of the format you ask for, not our own number:

* Peppol BIS, XRechnung, CIUS-PT, CIUS-RO: the EN 16931 limit (± 1.00) — less strict than our former 0.01
* PINT AE: 0.02 · PINT A-NZ: 1.00 · PINT OM and SI-UBL (Netherlands): the limit of their rule sets
* ZUGFeRD and Factur-X: the limits of the rule sets we check these profiles with
* Formats whose official rules have no such check (PINT JP, KSeF, ebInterface, ISDOC, Facturae, FatturaPA, NAV,
  myDATA, QR-bill): no check any more
* **Stricter in one case:** for categories `Z`, `E`, `AE`, `K`, `G` and `O` the official rule requires an exact match.
  A difference below 0.01 that we accepted before is now rejected.

Without an e-invoice format (no format, or only `pdf` / `html`) this check does not run, and `POST /validate`
without a format no longer returns `AMT_004` for the taxable amount.

**We write the tax breakdown you send.** If you send `taxSummary`, every e-invoice format now writes exactly these
values into the VAT breakdown (BG-23): taxable amount, tax amount, category and exemption reason. Before, most UBL
formats recalculated the breakdown from the lines. A `taxSummary` row without a category takes it from the lines with
the same rate.

**Do I need to act?** If you get the new 422, check that each `netAmount` is the sum of its lines (plus charges, minus
allowances).

## Australia and New Zealand: PINT A-NZ Billing 1.1.3

The Peppol network removed the old A-NZ version on 2026-03-31. Every AU and NZ invoice now carries the identifiers of
the current version:

| Element               | Before                                                                                           | Now                                |
| --------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------- |
| `cbc:CustomizationID` | `urn:cen.eu:en16931:2017#conformant#urn:fdc:peppol.eu:2017:poacc:billing:international:aunz:3.0` | `urn:peppol:pint:billing-1@aunz-1` |
| `cbc:ProfileID`       | `urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`                                                    | `urn:peppol:bis:billing`           |

* The created invoice is checked against PINT A-NZ 1.1.3. The rule set name in responses changes from
  `pint-au-nz-1.0` to `pint-au-nz-1.1`.
* Error messages name PINT rule ids, for example `ibr-006` (seller name missing) instead of `BR-06`, and `ibr-120`
  for a malformed ABN.
* Australia: the seller's GST registration (`PartyTaxScheme`) is written only when at least one line has a GST
  category other than `O`.

**Do I need to act?** If you send your own `businessProcess` (BT-23), use `urn:peppol:bis:billing`. If your system or
access point checks the old identifiers, or matches on rule ids, update it.

## Swiss and Liechtenstein QR bill: the payee is the creditor

On a QR bill, creditor and account must match (SIX Implementation Guidelines, 4.3.1). Before, the QR bill always used
`seller.bankAccount`, even when a `payee` was shown as creditor. For `POST /api/v1/invoice/{CH|LI}/qr-bill/generate`:

* A `payee` is the creditor. It needs a postal code, city and country, otherwise **422** `CH_ADDR_004`
  (`payee.postalCode`), `CH_ADDR_005` (`payee.city`) or `CH_ADDR_006` (`payee.countryCode`).
* The payee needs its own account: without `payee.bankAccount.iban` you get **422** `CH_IBAN_003`.
* Without a `payee`, nothing changes.

`payee.bankAccount` is now documented. When set, it is the payment account (BT-84) in every format and the account in
the QR code. Payee address fields now have limits — `street` and `additionalStreet` 200, `city` 100, `postalCode` 20,
`countryCode` exactly 2 characters; longer values get **400**.

**Do I need to act?** If you send a `payee` on a QR bill, send its postal code, city, country and its own
`bankAccount`.

## Register and party identifiers need an ISO 6523 (ICD) scheme

EN 16931 has two scheme lists: **ICD** for party identifiers and legal registrations (BT-29, BT-30, BT-46, BT-47;
rules `BR-CL-10`, `BR-CL-11`) and **EAS** for electronic addresses (BT-34, BT-49; rule `BR-CL-25`). Codes like `9934`
or `9936` are EAS codes. Before, our check accepted an EAS code in an ICD position; the receiver's check does not.

* An EAS code (`99xx`) in `seller.registrationScheme`, `buyer.registrationScheme` or `identifiers[].schemeId` is
  rejected with **422** naming `BR-CL-10` or `BR-CL-11`.
* Croatia and Liechtenstein: these positions no longer carry a `schemeID`. In Croatia the seller identifier (BT-29) is
  written as `9934:<OIB>`.

**Do I need to act?** Use an ICD code for registers (for example `0088` for a GLN) or leave the scheme out. Put
electronic addresses in `seller.electronicAddress` / `buyer.electronicAddress`.

## Austria: ebInterface 6.1 is checked

There is no official Schematron for ebInterface 6.1, so we wrote 27 rules from the official documentation (AUSTRIAPRO,
14 June 2023), ids `AT-EBI61-001` … `AT-EBI61-027`.

* `POST /api/v1/invoice/at/ebinterface/validate` and `/at/validate` now give a verdict (`passed` / `failed`) instead
  of `not_run`.
* `/at/ebinterface/generate` can reject with **422** and an `AT-EBI61-…` rule id, for example when line amounts or
  totals do not add up.
* Invoices not in EUR need `taxCurrencyCode: "EUR"` and `taxSummary[].taxCurrencyTaxAmount` for every rate, otherwise
  **422** `AT_EBI_TAX_EUR_AMOUNT_REQUIRED` (`AT-EBI61-011`). We do not apply an exchange rate.
* `cardAccount.pan` may have at most 10 digits, otherwise **422** `AT_EBI_PAN_TOO_MANY_DIGITS` (`AT-EBI61-013`).
* The other 14 rules are warnings and do not change `valid`.

Three of the four official ebInterface 6.1 sample files do not pass these rules — their totals do not calculate as the
documentation says. If you copied one, check your totals.

## Security retention reaches every format with payment terms

`retention` was written only in German XRechnung and ZUGFeRD. It is now written as one sentence into the payment terms
(BT-20 or the national field) of every format that has them.

* The sentence is in the seller's language (German original; English, French, Dutch, Italian, Spanish and Polish are
  machine translations; other languages get English). A `reason` you send is written as sent.
* Amounts keep their full value; the retention only reduces the amount to pay. Do not model it as an allowance.
* France (Peppol) now writes `cac:PaymentTerms`. Netherlands, Portugal, Romania: an empty `cac:PaymentTerms` is gone.
* Italy (FatturaPA): non-Latin-1 characters are replaced, with warning `TEXT_CHARACTERS_REPLACED` on `retention.reason`.
* Hungary (NAV): a payment description over 512 characters is no longer cut but split into `X99999_PAYMENT_DESC`,
  `X99999_PAYMENT_DESC_2`, … (also without a retention).
* Spain (Facturae): written to `InvoiceTotals/AmountsWithheld`, and `TotalExecutableAmount` is lowered.
* **422** `RETENTION_NOT_CARRIED` (field `retention`) only where a format has no place for it: ZUGFeRD / Factur-X
  MINIMUM, and Greek myDATA without `paymentMethods`. A plain PDF is never rejected for this.

**Do I need to act?** If you compare XML with stored copies, expect the new sentence. For Greek invoices with a
retention, send a payment method.

## Buyer identifier is BT-46

BT-46 may occur once. Before, it held `customerNumber`, and some UBL formats wrote both values (rule UBL-SR-16).

* The first `buyer.identifiers` entry is now BT-46, with its `schemeId`.
* If you send a buyer identifier, `customerNumber` is not written — warning `FIELD_NOT_WRITTEN`, `field: customerNumber`.
  Further identifiers give `FIELD_NOT_WRITTEN` with `field: buyer.identifiers.<n>`.
* Without a buyer identifier, `customerNumber` stays BT-46.

**Do I need to act?** Only if you send both. If your receivers expect the customer number in BT-46, do not send
`buyer.identifiers`.

## `/validate` says when a rulebook was not run

Some formats have no official rulebook (Schematron) we can run. Before, `/validate` answered them with `valid: true`.
Now:

* `POST /api/v1/invoice/{country}/{format}/validate` answers **200** with `status: not_run`, `valid: null` and
  `reason: missing`. The XSD check still runs; a real finding still gives `failed`. A rulebook that failed to load
  still answers 503 (retryable); `missing` is not.
* `POST /api/v1/invoice/{country}/validate` has a new field `validation` with the same shape. The top-level `valid` is
  unchanged.

Affected at the time of this release: parts of AT ebInterface, HU NAV, IT FatturaPA, ES Facturae, CH QR-bill and
ZUGFeRD 2.3 EXTENDED, CZ ISDOC 6.0 / 5.3, DE XRechnung 2.3 (German rules) and PT CIUS-PT 2.0. ebInterface 6.1 got its
rules in this same week; Facturae followed later.

**Do I need to act?** If you use `valid === true` as a gate, also handle `status: not_run`.

## Fewer silent omissions in the XML

* **VAT ID without country prefix:** a VAT ID that starts with a digit no longer fails with `BR-CO-09`. Where the
  format's rules require the prefix, we add the party's `countryCode` (`EL` for Greece) and warn with
  `VAT_ID_COUNTRY_PREFIX_ADDED`. VAT IDs starting with letters are not changed.
* **Seller identifier in XRechnung (BT-29):** the seller VAT ID is repeated as identifier only when nothing else
  satisfies BR-CO-26; then you get `SELLER_IDENTIFIER_DERIVED`.
* **Payee identifier (BT-60):** the first non-empty `payee.identifiers` entry is written, with its `schemeId`.
* **Payee and tax representative:** `payee.registrationNumber` (BT-61) is now written in XRechnung UBL, SI-UBL,
  CIUS-PT, CIUS-RO and all CII formats. The tax representative's `additionalStreet`, `addressLine3` and `state`
  (BT-65, BT-164, BT-68) are now written in CII, and in UBL also without street or city.
* **ZUGFeRD / Factur-X exemption reason:** a line exemption reason (BT-120/121) is written on the line only in
  EXTENDED and XRECHNUNG; in BASIC and EN 16931 it goes into the VAT breakdown. If it cannot reach the document you get
  `FIELD_NOT_WRITTEN` with `lossy: true`.
* **Rule ids instead of `UNKNOWN`:** rulebook findings without an id are now `SCHEMATRON_ASSERT_WITHOUT_ID`,
  `SCHEMATRON_REPORT_WITHOUT_ID` or `RULE_ID_MISSING`.
* **Netherlands:** checked with SI-UBL 2.0.3.13 and NLCIUS-CII 1.0.3.13 (release of 2026-05-21). UBL: new
  `UBL-SR-56`, `BR-CO-25` removed. CII: 28 new `CII-SR` rules, `BR-CO-25` and `BR-CO-27` removed.

## `countrySpecific.peppolEndpointId` is deprecated

The field (AE, AU, BE, NZ) was accepted but never written. Sending it now adds the warning `FIELD_NOT_WRITTEN` with
`field: "countrySpecific.peppolEndpointId"`. Use `buyer.electronicAddress` (BT-49) and `seller.electronicAddress`
(BT-34) instead. In Belgium, warning `BE_PEPPOL_001` now looks at `buyer.electronicAddress`. The field will be removed
in a later release, announced separately.

Three new warnings (with `substituted: true`) say when we fill in a value you did not send:
`SELLER_CONTACT_NAME_DERIVED` (`seller.contact.name`, XRechnung UBL), `BUSINESS_PROCESS_DEFAULTED` (`businessProcess`,
XRechnung UBL and ZUGFeRD XRECHNUNG) and `AE_TRANSACTION_TYPE_DEFAULTED` (`countrySpecific.transactionTypeCode`). ZUGFeRD
XRECHNUNG now writes BT-23, which fixes `PEPPOL-EN16931-R001`.

**Do I need to act?** If your code treats every warning as an error, send these values yourself.

## PDF output

* An amount and its currency symbol stay on one line.
* The tax rate in the totals uses the template language's percent format, as in the item column. Your own copies of
  system templates keep their label; change `{{taxRate}}%` to `{{taxRate:percent}}` to get it.
* The German default template shows `1.190,00 €` instead of `1,190.00 €`. The embedded XML does not change.

## September 25, 2026

## Typed request schemas on every parse endpoint

If you generate a client from our OpenAPI specification, it now knows what to send.

Previously, the 65 country- and format-specific parse endpoints carried no usable request schema. A
generated SDK turned that into an untyped, optional parameter — the required `data` field disappeared,
and calling the method with no arguments compiled cleanly. Only the server rejected it.

**What changed**

* Every parse endpoint declares its request body: `data` (required, Base64) and `filename` (optional)
* Invoice line items are a named type, `InvoiceLineItem`, instead of an unresolvable reference — so the
  36 fields of a line item, including nested `subItems`, are documented and typed
* Errors are a named `ErrorResponse` type, and the format options echoed back on a generated document
  are an `AppliedFormatOptions` type
* The specification carries an absolute server URL, so generated clients reach the API without
  extra configuration

**Do I need to act?** No endpoint, field or behaviour changed — this is the specification catching up
with what the API always did. Regenerate your client to pick up the types.

## New endpoints

* `POST /api/v1/invoice/{countryCode}/{format}/embed` — embed a generated e-invoice XML into your own
  carrier PDF
* `GET /api/v1/verifactu/declaracion` and `GET /api/v1/verifactu/chain/{vatId}/export` — Spanish
  VeriFactu declaration and chain export

## September 21, 2026

## Developer portal

The API reference now lives here, generated straight from the OpenAPI specification — so what you read
is what the API actually accepts and returns, across all 86 endpoints and 37 countries.

What you get:

* **Searchable reference** for every endpoint, with request and response schemas
* **Real examples** on the parse endpoints — round-trippable documents you can send as-is
* **Try it** directly from the page, with your own API key
* **Quickstart** that reads a German XRechnung end to end

The specification stays available at
[`/openapi-full.json`](https://service.invoice-api.xhub.io/openapi-full.json) if you would rather
generate a client yourself.