Skip to navigation

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.

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.

FromWhat is rejectedCodeDetails
2026-11-11Empty buyer.countryCode, sellers in EU member states422 BUYER_COUNTRY_REQUIRED2026-10-18
2026-11-11AT ebInterface: seller and buyer phone and email move into the address block (document change)—2026-10-11
2026-11-14Card payment without a card accountCARD_ACCOUNT_REQUIRED2026-10-11
2026-11-14BE Factur-X: credit transfer without payment accountPAYMENT_ACCOUNT_REQUIRED2026-10-11
2026-11-14FR and BE: credit transfer without payment accountCREDIT_TRANSFER_ACCOUNT_REQUIRED2026-10-11
2026-11-14Sellers outside the EU: above the small-invoice limit without the buyer’s countryBUYER_COUNTRY_REQUIRED2026-10-11
2026-11-15ES Facturae: rules ES-FAE322-055 and ES-FAE322-056 (empty invoice number)rule id2026-10-11
2026-11-16A date that is readable but not YYYY-MM-DD400 INVALID_DATE2026-10-18
2026-11-17Allowance or charge on document level without a tax categoryALLOWANCE_TAX_CATEGORY_REQUIRED2026-10-11
2026-11-17Invoice without the buyer’s name where the seller’s country requires itRECIPIENT_REQUIRED2026-10-11
2026-11-17Quantity that rounds to 0 (AT, PT, IT, HU formats)QUANTITY_ROUNDS_TO_ZERO2026-10-11
2027-01-01Invalid block inside a columns block of an inline PDF template400, warning TEMPLATE_BLOCK_INVALID2026-10-25
apipdf

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.
apipdf

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.
apipdf

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.

apipdf

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.
apivalidationpdf

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.

apivalidationpdf

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.
apivalidationpdf

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.
apivalidationpdf

Upcoming enforcement

FromWhat is rejectedCode
2026-11-11Empty 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-16A date that is readable but not YYYY-MM-DD400 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.

apivalidationpdfbreaking

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.

apivalidationpdfbreaking

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.
apivalidationpdfbreaking

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.
apivalidationpdfbreaking

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.

FromWhat is rejectedCode
2026-11-11AT ebInterface: phone and email of seller and buyer move from eb:Contact into the address block (document change, warning until then)—
2026-11-14Card payment without a card accountCARD_ACCOUNT_REQUIRED
2026-11-14BE Factur-X: credit transfer without payment accountPAYMENT_ACCOUNT_REQUIRED
2026-11-14FR and BE: credit transfer without payment accountCREDIT_TRANSFER_ACCOUNT_REQUIRED
2026-11-14Sellers outside the EU: invoice above the small-invoice limit without the buyer’s countryBUYER_COUNTRY_REQUIRED
2026-11-15ES Facturae: empty invoice number (ES-FAE322-056) and rule ES-FAE322-055rule id
2026-11-17Document-level allowance or charge without a tax category, in every formatALLOWANCE_TAX_CATEGORY_REQUIRED
2026-11-17Creating 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-17Small 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 invalidRECIPIENT_REQUIRED
2026-11-17A quantity that becomes 0 after the format’s rounding (AT ebInterface, PT CIUS-PT, IT FatturaPA, HU NAV)QUANTITY_ROUNDS_TO_ZERO
apivalidationcountriesbreaking

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.
apivalidationcountriesbreaking

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.
apivalidationcountriesbreaking

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.
apivalidationcountriesbreaking

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.
apivalidationcountriesbreaking

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.
apivalidationcountriesbreaking

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.
apivalidationcountriesbreaking

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.

WarningFieldLimit
FIELD_TOO_LONGseller. / buyer. street, additionalStreet200 characters
FIELD_TOO_LONGseller. / buyer. city100 characters
FIELD_TOO_LONGseller. / buyer. postalCode20 characters
FIELD_TOO_LONGseller.state, buyer.state, delivery.address.state, projectNumber100 characters
FIELD_TOO_LONGattachments20 attachments; 15 MiB decoded each; 30 MiB decoded together
INVOICE_LINES_ABOVE_MODE_LIMITitems5000 lines including sub-items, on servers without large-invoice validation
apivalidationlimitspdfcountries