API Version 2026-04-20

Select this version by sending X-B2B-API-Version: 2026-04-20 in your request headers.

Changes overview

Change	Area	Breaking
Add additional identifiers to accounts (`routing_codes`)	Accounts	✅
Add `auto_remittance` to accounts	Accounts	✅
Add `skip_line_taxable_base_rounding` to accounts	Accounts	✅
Expose `cin_value` and `cin_scheme` in invoice contact fields	Invoices	✅
Replace amend fields with `invoice_references`	Invoices	❌
Peppol transport changes (remove `standard_documents`, `pending_peppol_directory_publish`; add `sml_status`, `peppol_directory_status`, `reception_document_types`)	Transports	❌
Validate `tin_value` and `tin_scheme` against parent contact	Contacts	❌
Require `tin_value` or `cin_value` when creating a contact inline on invoices	Invoices	❌
New TIN verification endpoint	TIN Verifications	✅
New `tin_verification.finished` webhook event	Webhooks	✅
Add `exchange_rate` and `exchange_date` to invoice response	Invoices	✅
Remove `payment_method_info` from invoice response	Invoices	❌
Fix `clasification_code_scheme` typo in invoice line responses	Invoices	❌
Add `order_date` to invoice response	Invoices	✅
(KSeF) Add `total_amount_due` to invoice request	Invoices	✅
(KSeF) Add `third_party` support to invoices	Invoices	✅
(KSeF) Add `customer_party_jst` and `customer_party_gv` to tax reports	Tax Reports	✅
(KSeF) Add `purchase_order_date` and `despatch_advice_reference` to tax reports	Tax Reports	✅
(KSeF) Add `supplier_party_krs`, `supplier_party_regon` and `supplier_party_bdo` to tax reports	Tax Reports	✅
(KSeF) Add `supplier_contact_phone` and `supplier_contact_email` to tax reports	Tax Reports	✅
(KSeF) Add `previous_advance_total` to tax reports	Tax Reports	✅
(KSeF) Add `order_total_amount` to tax reports	Tax Reports	✅
(KSeF) Add `prepayment_references` to tax reports	Tax Reports	✅
(KSeF) Make `third_party` fields writable on tax reports	Tax Reports	✅
(KSeF) Add KSeF invoice type codes	Invoices	✅

Added

TIN verification endpoint

New endpoint to verify TIN (Tax Identification Number) + name pairs against a tax authority census. Currently supports Spain (AEAT) only.

Processing is asynchronous: POST returns 202 Accepted immediately, and results are fetched via GET or received through the tin_verification.finished webhook event. Results from the last 24 hours are cached to avoid redundant calls to the tax authority.

New endpoints:

POST /tin_verifications?country=es — Submit a batch of up to 20,000 TIN+name pairs for verification.
GET /tin_verifications/{id} — Retrieve the status and results of a verification request.

Example: Submit verification

curl --request POST \
     --url 'https://app-staging.b2brouter.net/tin_verifications?country=es' \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
     --header 'content-type: application/json' \
     --data '[{"tin": "B12345678", "name": "Ejemplo S.L."}]'

{
  "id": 42,
  "status": "pending",
  "results": []
}

Example: Fetch results

{
  "id": 42,
  "status": "success",
  "results": [
    {
      "tin": "B12345678",
      "normalized_tin": "ESB12345678",
      "name": "Ejemplo S.L.",
      "tin_format_valid": true,
      "census_match": true
    }
  ]
}

When census_match is true, the name field in results returns the canonical name from the tax authority census; otherwise it echoes the submitted name.

TIN verification webhook

New webhook event tin_verification.finished is fired when a TIN verification request reaches a terminal state (success or failed). The payload contains only the request ID and status — use GET /tin_verifications/{id} to fetch the full results.

Subscribe to this event when configuring a webhook:

{
  "web_hook": {
    "url": "https://example.com/hooks",
    "events": ["tin_verification.finished"]
  }
}

Add additional identifiers to accounts (`routing_codes`)

New object routing_codes on accounts to support up to 5 additional Company Identifier Numbers beyond the primary cin. Contains fields cin1_value, cin1_scheme through cin5_value, cin5_scheme (string, nullable). Scheme codes are returned as zero-padded 4-character strings (e.g. "0088"), or null when the scheme is unknown.

GET response:

"routing_codes": {
  "cin1_value": "7080000950171",
  "cin1_scheme": "0088",
  "cin2_value": null,
  "cin2_scheme": null,
  ...
  "cin5_value": "1234567890",
  "cin5_scheme": "0001",
}

POST/PUT input: use the same nested routing_codes object. If cinN_value is provided, cinN_scheme is required (and vice versa).

"account": {
  "routing_codes": {
    "cin1_value": "7080000950171",
    "cin1_scheme": "0088"
  }
}

Affected endpoints:

POST /accounts — accepts routing_codes in the request body.
PUT /accounts/{account} — accepts routing_codes in the request body.
GET /accounts/{account} — returns routing_codes in the response.
GET /accounts — returns routing_codes in each account entry.

Add `auto_remittance` to accounts

New boolean field auto_remittance (default false) on accounts enables automatic generation of structured remittance references (OGM codes) for Belgian invoices, without requiring an integration group that enforces them.

When auto_remittance is true and both the account and the invoice contact are located in Belgium, the invoice will automatically receive a structured remittance reference — the same behavior previously available only through integration groups that require OGM codes.

Affected endpoints:

POST /accounts — accepts auto_remittance in the request body.
PUT /accounts/{account} — accepts auto_remittance in the request body.
GET /accounts/{account} — returns auto_remittance in the response.

Add `skip_line_taxable_base_rounding` to accounts

New boolean field skip_line_taxable_base_rounding (default false) on accounts. When enabled, the invoice tax calculation skips rounding of individual line taxable bases and per-line tax amounts, rounding only the final accumulated totals. This reduces rounding drift on invoices with many lines.

Requires apply_taxes_per_line to be true — the API returns 422 Unprocessable Entity if skip_line_taxable_base_rounding is set to true while apply_taxes_per_line is false.

Affected endpoints:

POST /accounts — accepts skip_line_taxable_base_rounding in the request body.
PUT /accounts/{account} — accepts skip_line_taxable_base_rounding in the request body.
GET /accounts/{account} — returns skip_line_taxable_base_rounding in the response.
GET /accounts — returns skip_line_taxable_base_rounding in each account entry.

Expose `cin_value` and `cin_scheme` in invoice contact fields

The contact object in invoice responses now includes cin_value and cin_scheme fields alongside the existing tin_value and tin_scheme.

Affected endpoints:

GET /invoices/{id} — contact object now includes cin_value and cin_scheme.
GET /accounts/{account}/invoices — contact object in index entries now includes cin_value and cin_scheme.

Changed

Validate `tin_value` and `tin_scheme` against parent contact

The requests POST /accounts/{account}/contacts and PATCH /contacts/{id} with parent_id now validate tin_value and tin_scheme against the parent contact. Offices (organizational units) inherit TIN from their parent; if the provided tin_value does not match the parent's, the API returns 422 Unprocessable Entity with code parameter_invalid. Previously, mismatched values were silently ignored.

cin_value and cin_scheme are inherited from the parent contact and not validated against it.

To migrate, either omit tin_value when creating offices (recommended), or ensure it matches the parent's value exactly.

Affected endpoints:

POST /accounts/{account}/contacts — rejects mismatched tin_value / tin_scheme when parent_id is set.
PATCH /contacts/{id} — rejects mismatched tin_value / tin_scheme when the contact has a parent.

Require `tin_value` or `cin_value` when creating a contact inline on invoices

POST /accounts/{account}/invoices now validates that when a contact object is provided inline, at least one of tin_value or cin_value is present. If both are missing, the API returns 422 Unprocessable Entity with code parameter_blank and param: "contact".

IssuedSimplifiedInvoice is exempt from this validation — simplified invoices (tickets) do not require an identified contact.

To migrate, always include tin_value or cin_value when sending an inline contact on invoice create. Alternatively, use contact_id to reference an existing contact instead.

Affected endpoints:

POST /accounts/{account}/invoices — rejects inline contact objects without a tin_value or cin_value (except for IssuedSimplifiedInvoice).

Replace amend fields with `invoice_references`

🚨
Breaking change

A new invoice_references array replaces the flat amendment fields (amended_number, amended_date, amended_invoicing_period_start, amended_invoicing_period_end, amend_reason, amend_code_tax, correction_method) on the Invoice resource.

Each reference has a reference_type:

amend — corrective invoice referencing the original. Max 1 per invoice.
prepayment — settlement invoice (ROZ) referencing advance payment invoices (ZAL). Multiple allowed.

Breaking change — response: the flat fields amended_number, amended_date, amended_invoicing_period_start, amended_invoicing_period_end, amend_reason, and correction_method are no longer returned in the GET response. Use invoice_references instead.

Breaking change — request: the flat write parameters amended_number, amended_date, amended_invoicing_period_start, amended_invoicing_period_end, amend_reason, amend_code_tax, and correction_method are no longer accepted. Use invoice_references in the request body instead.

Migration guide — field mapping:

v20260302 (flat field)	v20260420 (`invoice_references`)	Notes
`amended_number`	`invoice_references[].number`	Read + Write
`amended_date`	`invoice_references[].date`	Read + Write
`amended_invoicing_period_start`	`invoice_references[].invoicing_period_start`	Write-only in v20260420 (not returned in response)
`amended_invoicing_period_end`	`invoice_references[].invoicing_period_end`	Write-only in v20260420 (not returned in response)
`amend_reason`	`invoice_references[].reason`	Read + Write
`amend_code_tax`	`invoice_references[].tax_correction_code`	Already write-only in v20260302
`correction_method`	`invoice_references[].correction_method`	Read + Write
(new)	`invoice_references[].reference_type` (`amend` or `prepayment`)	Required
(new)	`invoice_references[].tax_registration_code`	Read + Write
(new)	`invoice_references[].total_amount`	Read + Write

Affected endpoints:

GET /invoices/{id} — returns invoice_references array. Flat amend fields removed from response.
POST /accounts/{account}/invoices — accepts invoice_references array.
PATCH /invoices/{id} — accepts invoice_references array. Use { "id": 123, "_destroy": true } to delete a reference.

InvoiceReference fields:

Field	Type	Description
`id`	integer	Read-only identifier
`reference_type`	string	`amend` or `prepayment` (required)
`number`	string	Invoice number of the referenced invoice
`series_code`	string	Series code of the referenced invoice
`date`	date	Issue date of the referenced invoice
`invoicing_period_start`	date	Start of the invoicing period (write-only; not returned in response)
`invoicing_period_end`	date	End of the invoicing period (write-only; not returned in response)
`reason`	string	Correction reason
`correction_method`	string	Correction method (e.g. Facturae 01-04)
`tax_registration_code`	string	Tax authority registration code (e.g. KSeF NrKSeF number)
`tax_correction_code`	string	Tax correction type code (e.g. KSeF TypKorekty)
`total_amount`	float	Total of the referenced invoice
`currency`	string	Currency of total_amount (ISO 4217)

Example: Create a credit note referencing the original invoice

curl --request POST \
     --url 'https://app-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices' \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
     --header 'content-type: application/json' \
     --data '{
       "invoice": {
         "number": "CN-2026-001",
         "date": "2026-03-15",
         "is_credit_note": true,
         "contact_id": {CONTACT_ID},
         "invoice_references": [
           {
             "reference_type": "amend",
             "number": "INV-2026-042",
             "date": "2026-02-10"
           }
         ],
         "invoice_lines_attributes": [
           { "quantity": 2, "price": 50, "description": "Product returned",
             "taxes_attributes": [{ "name": "VAT", "percent": 21 }] }
         ]
       }
     }'

Example: Create a ROZ (settlement) invoice with prepayment references

curl --request POST \
     --url 'https://app-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices' \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
     --header 'content-type: application/json' \
     --data '{
       "invoice": {
         "number": "ROZ/2026/001",
         "date": "2026-08-17",
         "type_code": "ROZ",
         "contact_id": {CONTACT_ID},
         "invoice_references": [
           {
             "reference_type": "prepayment",
             "tax_registration_code": "9999999999-20260215-8BEF280C8D35-4D"
           },
           {
             "reference_type": "prepayment",
             "number": "ZAL/2026/100"
           }
         ],
         "invoice_lines_attributes": [
           { "quantity": 1, "price": 8000, "description": "Service — final settlement",
             "taxes_attributes": [{ "name": "VAT", "percent": 8 }] }
         ]
       }
     }'

Example: Create a KOR_ZAL (advance correction) with amend reference

curl --request POST \
     --url 'https://app-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices' \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
     --header 'content-type: application/json' \
     --data '{
       "invoice": {
         "number": "KOR_ZAL/2026/001",
         "date": "2026-03-17",
         "type_code": "KOR_ZAL",
         "contact_id": {CONTACT_ID},
         "invoice_references": [
           {
             "reference_type": "amend",
             "number": "ZAL/2026/050",
             "date": "2026-02-15",
             "tax_registration_code": "9999999999-20260215-8BEF280C8D35-4D",
             "tax_correction_code": "1",
             "total_amount": 20000.0,
             "currency": "PLN"
           }
         ],
         "invoice_lines_attributes": [
           { "quantity": 1, "price": 5000, "description": "Advance correction",
             "taxes_attributes": [{ "name": "VAT", "percent": 8 }] }
         ]
       }
     }'

Peppol transport changes

The Peppol transport response has been updated with new fields that replace the previous publication status indicators. Publish and unpublish operations now run asynchronously — poll these fields to track progress.

Removed fields:

standard_documents — no longer returned in responses. If sent in a request, it is silently ignored. The system now automatically configures standard documents for all Peppol transports.
pending_peppol_directory_publish — replaced by peppol_directory_status.

New fields:

sml_status — string. SML (Service Metadata Locator) registration status.
peppol_directory_status — string. Peppol Directory listing status.
reception_document_types — array of document type objects (code, name) listing the document types this participant can receive via Peppol. Empty when reception is false or the company has no reception services configured.

Possible values for the two status fields: "not_published", "processing" (async operation pending), and "published". These fields reflect the publication status of this participant on the Peppol network via B2Brouter as Access Point.

Example response (Peppol transport, published participant):

{
  "code": "peppol",
  "enabled": true,
  "reception": true,
  "invoice": true,
  "credit_note": true,
  "self_billing": false,
  "order": true,
  "application_response": true,
  "pin_scheme": "0208",
  "pin_value": "0123456789",
  "sml_status": "published",
  "peppol_directory_status": "published",
  "reception_document_types": [
    { "code": "xml.ubl.invoice.be", "name": "Belgium UBL.BE Invoice 3.0" },
    { "code": "xml.ubl.credit_note.bis3", "name": "Peppol BIS3 CreditNote" }
  ]
}

Affected endpoints:

GET /accounts/{account}/transports — response includes sml_status, peppol_directory_status, and reception_document_types; no longer returns standard_documents or pending_peppol_directory_publish.
PATCH /transports/{code} — standard_documents parameter is silently ignored.
PUT /transports/{code} — standard_documents parameter is silently ignored.

Add `exchange_rate` and `exchange_date` to invoice response

New fields on the invoice response:

exchange_rate (decimal, nullable) — the exchange rate used for currency conversion when the invoice currency differs from the tax authority's local currency.
exchange_date (date, nullable) — the date of the exchange rate.

These fields were previously accepted on input (write-only) but not returned in API responses. Starting with v2026-04-20, they are included in the response.

Affected endpoints:

GET /invoices/{id} — returns exchange_rate and exchange_date.
POST /accounts/{account}/invoices — returns both fields in the response.
PATCH /invoices/{id} — returns both fields in the response.

Add `order_date` to invoice response

New field order_date (date, nullable) on the invoice response. This is the purchase order date, complementing the existing ponumber (purchase order reference) field. Previously accepted on input but not returned in API responses.

Affected endpoints:

GET /invoices/{id} — returns order_date.
POST /accounts/{account}/invoices — returns order_date in the response.
PATCH /invoices/{id} — returns order_date in the response.

Fix `clasification_code_scheme` typo in invoice line responses

The invoice line response field clasification_code_scheme was misspelled (missing an 's') in all previous API versions. Starting with v2026-04-20, the response returns the correct spelling: classification_code_scheme.

Request (input): classification_code_scheme — unchanged, all versions already accepted the correct spelling.
Response (output): classification_code_scheme — corrected in v2026-04-20. Older versions (v2025-01-01, v2025-10-13, v2026-03-02) continue to return clasification_code_scheme to avoid breaking existing integrations.

If your code reads clasification_code_scheme from invoice line responses, update it to classification_code_scheme when migrating to v2026-04-20.

Affected endpoints:

GET /invoices/{id} — lines[].classification_code_scheme now uses correct spelling in response.
POST /accounts/{account}/invoices — response body uses correct spelling.
PATCH /invoices/{id} — response body uses correct spelling.

Add `total_amount_due` to invoice request

New write-only field total_amount_due on the Invoice resource. Accepts the invoice total amount directly, bypassing line-based calculation.

Primarily intended for KSeF ZAL (advance payment) and KOR_ZAL (advance correction) invoices, where the invoice total cannot be derived from invoice lines in the usual way. Maps to the P_15 field in the KSeF FA(3) XML.

total_amount_due is not returned in the response (write-only). The resolved total is returned via the standard total and payable_amount fields.

Affected endpoints:

POST /accounts/{account}/invoices — accepts total_amount_due in the request body.
PATCH /invoices/{id} — accepts total_amount_due in the request body.

KSeF Changes

Add `third_party` support to invoices

Three new fields on the Invoice resource support Polish KSeF invoicing scenarios where a third party (Podmiot3) is involved:

apply_to_local_government_unit — boolean, marks the invoice as addressed to a JST (Jednostka Samorządu Terytorialnego), a subordinate local government unit.
apply_to_vat_group_member — boolean, marks the invoice as addressed to a GV (Grupa VAT) member.
third_party — nested object with the third party's name, NIP (tin_value), and address. Required when either flag is true.

These fields are mutually exclusive: only one of apply_to_local_government_unit or apply_to_vat_group_member can be true on the same invoice.

These fields use an expandable response pattern: they are not included in API responses by default. Request them via the include query parameter.

When generating a KSeF tax report from an invoice, B2Brouter uses these flags to automatically set the buyer/third-party roles. The invoice contact becomes the buyer (Podmiot2) and the third_party becomes Podmiot3 (role 8 for JST, role 10 for GV).

Affected endpoints:

GET /invoices/{id} — returns the new fields when requested via ?include=apply_to_local_government_unit,apply_to_vat_group_member,third_party
POST /accounts/{account}/invoices — accepts the new fields in the request body
PATCH /invoices/{id} — accepts the new fields in the request body

Example: Create an invoice for a government unit (JST)

curl --request POST \
     --url 'https://app-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices' \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
     --header 'content-type: application/json' \
     --data '{
       "invoice": {
         "number": "FV/2026/001",
         "date": "2026-03-23",
         "contact_id": {CONTACT_ID},
         "apply_to_local_government_unit": true,
         "third_party": {
           "role": "local_government_unit_recipient",
           "name": "Przykład Jednostka Podrzędna",
           "tin_value": "PL1234567890",
           "tin_scheme": "9945",
           "address": "ul. Przykładowa 12",
           "city": "Warszawa",
           "postalcode": "00-001",
           "country": "pl"
         },
         "invoice_lines_attributes": [
           { "quantity": 1, "price": 100, "description": "Service" }
         ]
       }
     }'

Example: Read invoice with expanded fields

curl --request GET \
     --url 'https://app-staging.b2brouter.net/invoices/{INVOICE_ID}?include=apply_to_local_government_unit,apply_to_vat_group_member,third_party' \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

{
  "invoice": {
    "id": 67890,
    "apply_to_local_government_unit": true,
    "apply_to_vat_group_member": false,
    "third_party": {
      "role": "local_government_unit_recipient",
      "name": "Przykład Jednostka Podrzędna",
      "tin_value": "PL1234567890",
      "tin_scheme": "9945",
      "cin_value": null,
      "cin_scheme": null,
      "address": "ul. Przykładowa 12",
      "address2": null,
      "city": "Warszawa",
      "postalcode": "00-001",
      "province": null,
      "country": "pl"
    },
    ...
  }
}

Add `customer_party_jst` and `customer_party_gv` to KSeF tax reports

Two new boolean fields on KSeF tax reports indicate whether the buyer is a government unit or a VAT group member:

customer_party_jst — true if the buyer is a subordinate local government unit. Defaults to false.
customer_party_gv — true if the buyer is a VAT group member. Defaults to false.

When creating tax reports from invoices, these fields are set automatically based on the invoice's apply_to_local_government_unit and apply_to_vat_group_member flags. When creating tax reports directly via the API, set them explicitly.

Affected endpoints:

POST /accounts/{account}/tax_reports — accepts and returns customer_party_jst and customer_party_gv when the tax report type is Ksef.
POST /accounts/{account}/tax_reports/import — accepts the new fields when importing KSeF tax reports.

Example: Create a KSeF tax report for a government unit

{
  "tax_report": {
    "type": "Ksef",
    "customer_party_jst": true,
    "customer_party_gv": false,
    ...
  }
}

Add `purchase_order_date` and `despatch_advice_reference` to KSeF tax reports

Two new fields on KSeF tax reports to support order and despatch traceability:

purchase_order_date — date (YYYY-MM-DD), nullable. The date of the purchase order (BT-92). Mapped automatically from the invoice's order date.
despatch_advice_reference — string, nullable. The despatch advice reference number (BT-16). Mapped automatically from the invoice's delivery note number.

Both fields are readable and writable via the API.

Affected endpoints:

POST /accounts/{account}/tax_reports — accepts and returns both fields when the tax report type is Ksef.
GET /tax_reports/{id} — returns both fields for KSeF tax reports.

Add `supplier_party_krs`, `supplier_party_regon` and `supplier_party_bdo` to KSeF tax reports

Three new fields on KSeF tax reports for Polish company registry identifiers:

supplier_party_krs — string, nullable. KRS (Krajowy Rejestr Sądowy) number of the supplier. Must be exactly 10 digits when provided.
supplier_party_regon — string, nullable. REGON (statistical identification number) of the supplier. Must be exactly 9 or 14 digits when provided.
supplier_party_bdo — string, nullable. BDO (waste database register) number of the supplier.

These are mapped automatically from the invoice company's CIN values when the scheme codes match (8036 for REGON, 8037 for KRS, 8038 for BDO). If provided directly via the API, supplier_party_krs and supplier_party_regon are validated and return 422 Unprocessable Entity if they do not meet the digit requirements.

Affected endpoints:

POST /accounts/{account}/tax_reports — accepts and returns the fields when the tax report type is Ksef.
GET /tax_reports/{id} — returns the fields for KSeF tax reports.

Add `supplier_contact_phone` and `supplier_contact_email` to KSeF tax reports

Two new fields on KSeF tax reports for supplier contact details (EN16931 BT-41, BT-42, BT-43):

supplier_contact_phone — string, nullable. Supplier contact telephone number (BT-42). Mapped from the invoice company's phone. Exported in the FA(3) XML as DaneKontaktowe/Telefon.
supplier_contact_email — string, nullable. Supplier contact email address (BT-43). Mapped from the invoice company's email. Exported in the FA(3) XML as DaneKontaktowe/Email.

Affected endpoints:

POST /accounts/{account}/tax_reports — accepts and returns the fields when the tax report type is Ksef.
GET /tax_reports/{id} — returns the fields for KSeF tax reports.

Add `previous_advance_total` to KSeF tax reports

New field on KSeF tax reports for corrective advance-payment invoices (KOR_ZAL):

previous_advance_total — decimal, nullable. The gross total of the original ZAL (advance payment) invoice being corrected. Maps to the P_15ZK field in the KSeF FA(3) XML. Required when invoice_type_code is KOR_ZAL.

When generating a tax report from an invoice, this value is mapped automatically from the invoice's amend reference total_amount. When creating a tax report directly via the API, it must be set explicitly.

Affected endpoints:

POST /accounts/{account}/tax_reports — accepts and returns the field when the tax report type is Ksef.
GET /tax_reports/{id} — returns the field for KSeF tax reports.

Example: Create a KOR_ZAL tax report

{
  "tax_report": {
    "type": "Ksef",
    "invoice_type_code": "KOR_ZAL",
    "previous_advance_total": 1230.00,
    ...
  }
}

Add `order_total_amount` to KSeF tax reports

New field on KSeF tax reports for advance payment and advance correction invoices:

order_total_amount — decimal, nullable. The total value of the order (WartoscZamowienia). Required when invoice_type_code is ZAL or KOR_ZAL.

When generating a tax report from an invoice, this value is mapped automatically from the invoice. When creating a tax report directly via the API, it must be set explicitly for ZAL and KOR_ZAL invoices.

Affected endpoints:

POST /accounts/{account}/tax_reports — accepts and returns the field when the tax report type is Ksef.
GET /tax_reports/{id} — returns the field for KSeF tax reports.

Add `prepayment_references` to KSeF tax reports

New array field on KSeF tax reports for settlement invoices (ROZ/KOR_ROZ):

prepayment_references — array of objects, each referencing an advance payment invoice that this ROZ invoice settles. Each entry maps to a FakturaZaliczkowa element in the KSeF FA(3) XML. Required (non-empty) when invoice_type_code is ROZ or KOR_ROZ.

Each object in the array has:

Field	Type	Description
`id`	integer	Read-only internal identifier (returned in response)
`number`	string	Invoice number of the advance payment invoice (`NrFaZaliczkowej`). Required when `registration_code` is absent.
`registration_code`	string	KSeF registration number of the advance payment invoice (`NrKSeFFaZaliczkowej`). Required when `number` is absent.
`_destroy`	boolean	Set to `true` (with `id`) to remove the reference

When generating a tax report from an invoice, the references are mapped automatically from the invoice's prepayment invoice references. When creating directly via the API, set them explicitly.

Affected endpoints:

POST /accounts/{account}/tax_reports — accepts and returns the array when the tax report type is Ksef.
GET /tax_reports/{id} — returns the array for KSeF tax reports.

Example: Create a ROZ tax report

{
  "tax_report": {
    "type": "Ksef",
    "invoice_type_code": "ROZ",
    "prepayment_references": [
      { "registration_code": "9999999999-20260215-8BEF280C8D35-4D" },
      { "number": "ZAL/2026/001" }
    ],
    ...
  }
}

Make `third_party` fields writable on KSeF tax reports

The third_party_* identifier fields on KSeF tax reports were previously read-only — populated only when generating a tax report from an invoice. Starting with v2026-04-20, they are writable so API consumers can set the Podmiot3 data when creating tax reports directly.

Newly writable fields:

third_party_name — string, nullable.
third_party_id — string, nullable. Identifier value (e.g. GLN).
third_party_scheme — string, nullable. Identifier scheme (e.g. "0088" for GLN).
third_party_tax_id — string, nullable. NIP / VAT number of the third party.
third_party_tax_scheme — string, nullable. Tax scheme code.
third_party_country — string, nullable. ISO 3166-1 alpha-2 country code.
third_party_endpoint_id — string, nullable. Peppol endpoint identifier for routing purposes.

Already-writable fields in previous versions (unchanged): third_party_role (KSeF code 2–11, e.g. 2 = delivery recipient, 8 = local government unit, 10 = VAT group member), third_party_address, third_party_postalcode, third_party_city.

Validation: when third_party_role is set, third_party_country is now required. The API returns 422 Unprocessable Entity with param: "third_party_country" if missing. (This validation is new in v2026-04-20 — possible because third_party_country is now writable.)

Affected endpoints:

POST /accounts/{account}/tax_reports — accepts the third-party fields in the request body.
PATCH /tax_reports/{id} — accepts the third-party fields in the request body.

Add KSeF invoice type codes

New type_code values for Polish KSeF advance-payment and correction invoice workflows:

`type_code`	Description
`ZAL`	Advance payment invoice (Faktura zaliczkowa)
`ROZ`	Settlement invoice (Faktura rozliczeniowa) — settles one or more ZAL invoices
`KOR_ZAL`	Correction of an advance payment invoice
`KOR_ROZ`	Correction of a settlement invoice
`KOR`	Generic correction invoice (KSeF FA(3) Korekta)
`VAT`	VAT-only invoice (Faktura VAT)
`UPR`	Simplified invoice (Faktura uproszczona)

These values are accepted on create (POST /accounts/{account}/invoices) and update (PUT /invoices/{id}), and returned in invoice responses. Existing type codes (IssuedInvoice, ReceivedInvoice, etc.) remain unchanged.

Affected endpoints:

POST /accounts/{account}/invoices — accepts the new type_code values.
PUT /invoices/{id} — accepts the new type_code values.
GET /invoices/{id} — may return the new values in the type_code field.

Removed

Remove `payment_method_info` from invoice response

The payment_method_info field has been removed from the invoice response. This field contained an HTML-formatted summary of payment details (e.g. "Bank transfer to<br />IBAN ES13 210..."), which is redundant with the structured fields already present in the response (payment_method, contact_iban, contact_bic, etc.) and rendered poorly in JSON consumers.

Affected endpoints:

GET /invoices/{id} — no longer returns payment_method_info.
POST /accounts/{account}/invoices — no longer returns payment_method_info in the response.
PATCH /invoices/{id} — no longer returns payment_method_info in the response.

Changelog

Changelog - 2026-04-20

API Version 2026-04-20

Changelog - 2026-03-02

API Version 2026-03-02

Changelog - 2025-10-13

API Version Release - 2025-10-13