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.
PDF templates over the REST API
You can now store, update and read PDF templates with your API key:
POST /api/v1/pdf/templatesstores a BlockTemplate for your organization and returns it with itsid(201). Use theidastemplateIdinPOST /api/v1/pdf/generateor informatOptions.templateIdof 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.isActiveis not accepted (400UNSUPPORTED_FIELD); system templates are read-only (403SYSTEM_TEMPLATE_READ_ONLY).GET /api/v1/pdf/templates/{id}returns a template of your organization or a system template.
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
dataof the response with itsmimeType). - A bare address gets a default subject (
Rechnung <number> von <seller>for/DEand/AT, otherwiseInvoice <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.
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.fieldis the path (for exampleformatOptions.template.body.blocks.1.data.columns.0.blocks.0),params.rejectFromis2027-01-01. - From 2027-01-01: such a block is rejected with 400, with the same finding as a top-level block.
enforcePending: truegives you the 400 now.
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.
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; optionaldata.label(max. 100 characters).watermark— text across every page, behind the content;data.textrequired (max. 100). OptionalfontSize,color,opacity(0–1),rotation(−90 to 90),bold,font.barcode— 1D barcode or Data Matrix;data.contentrequired (max. 200, placeholders such as{{invoiceNumber}}allowed). Optionalformat(code128default;code39,code93,ean13,ean8,upca,upce,itf14,codabar,datamatrix),width,height(inlengthUnit),alignment,includeText.
Dates: preceding invoice date and empty strings
- The
YYYY-MM-DDrule with theDATE_NOT_ISOwarning (rejected from 2026-11-16) now also covers the preceding invoice date (BT-26):referencedInvoiceDate,precedingInvoiceReferences[].issueDateanditems[].creditedFrom.invoiceIssueDate. - An empty string (
"") indueDate,deliveryDate,delivery.date,servicePeriod.start/endoritems[].servicePeriod.start/endis left out of the document with the warningDATE_EMPTY_IGNORED(field). Omit the field or sendYYYY-MM-DD.
Upcoming enforcement
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.
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/embedwith adeliveryNote.datethat is not a real date (for example31.02.2026) answers 400INVALID_DATE. Before, it answered 200 and silently left the delivery note out. - PDF without embedded XML:
POST /parseanswers 400NO_EMBEDDED_XML(before: 200 withDE_UNKNOWN_FORMAT);POST /convertanswers 400NO_EMBEDDED_XMLinstead of 422PARSE_FAILED. /parsepayment term:invoice.paymentTerms.dueDaysis filled only from the document. Without a term in the document the field is absent instead of a fixed default.
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
tablefields 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). dataSourcetakes any array in your invoice data.- Accepted block types: text, table, summary, keyvalue, columns, image, spacer, line, qrcode.
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.
Stricter now (no warning phase)
- Impossible invoice date (for example
2026-02-30):/DE/validateanswersvalid: falsewithINVOICE_DATE_NOT_XS_DATEatissueDate;/convertanswers 422PARSE_FAILEDwithDE_INVALID_INVOICE_DATE. - Empty
issueDate:/validatereportsBR-03instead ofVAL-SYS-005;/generateanswers 422BR-03instead of 400INVALID_DATE. /parsewithout an invoice date:success: falsewithDE_MISSING_INVOICE_DATEinstead 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 422BR-03. /validateand totals (CII): a VAT breakdown category that no line has is invalid withAMT_004, as at/generate. Wrong totals also reportAMT_00xnext to the format rules.buyer.taxableRecipientmust betrueorfalse; other values give 400 (null= not sent). In Portugal, withtrue, a small invoice without the buyer’svatIdortaxIdgets 422RECIPIENT_REQUIRED.- Hungary (NAV):
countrySpecific.customerVatStatusnow takes effect.PRIVATE_PERSONomits buyer name, address and tax number from the NAV report; a status contradicting the buyer’s tax number gives 422NAV_CUSTOMER_STATUS_CONFLICT. - Portugal (
/PT/ubl/generate):orderNumberwith 21–100 characters gives 422DT-CIUS-PT-012;quoteNumberover 20 characters together with an order number gives 422DT-CIUS-PT-013. Before, the values silently went missing.
Accepted now (was rejected)
/validateadds a missing VAT ID country prefix (BR-CO-09) withVAT_ID_COUNTRY_PREFIX_ADDED.- CII (ZUGFeRD, Factur-X): a missing exemption reason gets the standard text with
TAX_EXEMPTION_REASON_SUBSTITUTED. - ES Facturae:
/validatenow runs the rules (passedinstead ofnot_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: 422PEPPOL-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.
cashwith a seller IBAN is code 10.direct_debitwith 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
Ewith the note text, no BT-121 code. - ES Facturae:
BatchIdentifieris 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/validateanswers with the same codes as/DE/validateand/generate(for exampleDE_SELLER_CONTACT_001with ruleBR-DE-2).- AT ebInterface: wrong decimals give
AT-EBI61-004instead ofXSD-ERROR. - An attachment with only a description: 422
BR-52instead of 400. POST /api/v1/lroe/submitwithout Bizkaia credentials: 409LROE_CREDENTIAL_MISSING/LROE_NRS_MISSINGor 503ESCROW_UNAVAILABLEinstead of 500./convertwith a non-JSON body: 400Malformed JSON in request bodyinstead of 500.DE_REF_002now 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) inorderNumber. - IBANs arrive without spaces and in capitals, in every input format.
paymentMethods[].typefollows one table: 10cash; 30/42/58bank_transfer; 48/54/55credit_card; 49/59direct_debit; otherother.- 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) returnsseller.legalName/buyer.legalName; CII from DE, CH, NL returnsdirectDebitMandate; NAV returnsseller.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) whilesuccessstaystrue. If you treat anyerrorsentry as failure, check this case. - Missing party country: new warning
PARTY_COUNTRY_ASSUMEDwith field and place. /converthas a new fieldsourceErrorswith the findings from reading the source.
New
/{country}/{format}/validatechecks a document you received. Send{ "data": "<base64 XML or PDF>", "filename": "…" }instead ofinvoice. The file itself is checked against XSD and rulebook; a PDF also getsextractedFromPdf: true. Billed 1 unit on the format’sparseentitlement. New answers: 400NO_EMBEDDED_XML, 400FORMAT_MISMATCH; with bothinvoiceanddata,invoiceis checked and you getDATA_IGNORED./fr/ublvalidation follows the file: Peppol BIS, EXTENDED-CTC-FR (EN 16931 + CTC-FR rules) or EN 16931;results[].formatnames the rulebook./validateexplains a non-Unified body: the 400 gains ahint(ValidationHint) withcode(BODY_NOT_JSON,INVOICE_MISSING,INVOICE_LOOKS_LIKE_XML,INVOICE_NOT_UNIFIED),messageand, where useful,next. Status,errorandsuccessare unchanged.- Warning
TAX_SUMMARY_CATEGORY_WITHOUT_LINESwhen a breakdown row has a category and rate no line uses. - Portugal: optional
buyer.taxableRecipient;falselets you omit buyer name and address (TAXABLE_RECIPIENT_CONFLICTwith reverse charge). - Some formats warn
FIELD_NOT_WRITTENwhen a field has no place in the format. POST /api/v1/lroe/submitis listed under the tagLROE.
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 inrule(for exampleFX-SCH-A-000155). If you match oncodevalues starting withFX-SCH-A-, match onrule. - Portugal (CIUS-PT): BT-31 and BT-48 carry the
vatIdyou send, unchanged. Without it,PTplus the checkedtaxId. New warningsBUYER_VAT_ID_PLACEHOLDER,BUYER_VAT_ID_MISSING,SELLER_VAT_ID_MISSING. SendvatIdfor 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.
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.
