Migration guide v2026-03-02 → v2026-04-20

This guide helps you upgrade from X-B2B-API-Version: 2026-03-02 to X-B2B-API-Version: 2026-04-20, focusing on what you need to change, not just what changed.

Changelog For the full list of additions and fixes, see the v2026-04-20 changelog.

At a glance

What changed	Do you need to act?
Credit notes and amendments use a new invoice_references structure	Yes — affects all integrations that create or read corrective invoices
payment_method_info removed from invoice responses	Yes — remove any code that reads this field
clasification_code_scheme typo fixed in invoice line responses	Yes — update your field name if you read it
New validation when creating child contacts (offices)	Yes — only if you set tin_value on contacts with a parent_id
New validation when creating invoices with an inline contact	Yes — ensure tin_value or cin_value is always included
New fields in invoice, account, and Peppol transport responses	Only if your code fails on unexpected JSON fields
Peppol transport: pending_peppol_directory_publish replaced	Only if you read this field
TIN verification endpoint (new)	No — opt-in feature
New account fields (routing_codes, auto_remittance, etc.)	No — opt-in
KSeF additions	No — only relevant for Polish KSeF integrations

---

Changes that require action

1. Credit notes and amendments: replace flat fields with invoice_references

This is the most significant change. The individual amendment fields on invoices have been replaced by a single invoice_references array. If your integration creates or reads corrective invoices (credit notes, amendments), you must update both your requests and your response handling.

The following fields are no longer sent or returned:

Removed field	Replaced by invoice_references[].
amended_number	number
amended_date	date
amended_invoicing_period_start	invoicing_period_start (send only, not returned)
amended_invoicing_period_end	invoicing_period_end (send only, not returned)
amend_reason	reason
amend_code_tax	tax_correction_code
correction_method	correction_method

Each entry in invoice_references requires a reference_type. Use "amend" for corrective invoices referencing an original invoice.

Updating your request (create/update):

Before (v2026-03-02)

{
  "invoice": {
    "number": "CN-2026-001",
    "is_credit_note": true,
    "contact_id": 123,
    "amended_number": "INV-2026-042",
    "amended_date": "2026-02-10",
    "amend_reason": "Price correction"
  }
}

After (v2026-04-20)

{
  "invoice": {
    "number": "CN-2026-001",
    "is_credit_note": true,
    "contact_id": 123,
    "invoice_references": [
      {
        "reference_type": "amend",
        "number": "INV-2026-042",
        "date": "2026-02-10",
        "reason": "Price correction"
      }
    ]
  }
}

Updating your response handling (read):

Before (v2026-03-02)

const originalNumber = invoice.amended_number;
const reason = invoice.amend_reason;

After (v2026-04-20)

const ref = invoice.invoice_references.find(
  (r) => r.reference_type === "amend",
);
const originalNumber = ref?.number;
const reason = ref?.reason;

Affected endpoints: GET /invoices/{id}, POST /accounts/{account}/invoices, PATCH /invoices/{id}

---

2. payment_method_info removed from invoice responses

The field payment_method_info is no longer returned. It contained a human-readable, HTML-formatted payment summary — if you were using it, switch to the structured fields already present in the response: payment_method, contact_iban, contact_bic, etc.

Affected endpoints: GET /invoices/{id}, POST /accounts/{account}/invoices, PATCH /invoices/{id}

---

3. Typo fix in invoice line field name: clasification_code_scheme → classification_code_scheme

The field was misspelled in all previous versions. The response now returns the correct spelling. If your code reads clasification_code_scheme (one ‘s’) from invoice line responses, update it.

Note: sending the correct spelling in requests was already accepted in all versions — only the response key changes.

Before (v2026-03-02)

{ "clasification_code_scheme": "..." }

After (v2026-04-20)

{ "classification_code_scheme": "..." }

Affected endpoints: GET /invoices/{id}, POST /accounts/{account}/invoices, PATCH /invoices/{id}

---

4. Child contacts (offices): tin_value is now validated against the parent

When creating or updating a contact that belongs to a parent company (using parent_id), the API now rejects the request if the provided tin_value does not match the parent contact’s. Previously, a mismatched value was silently ignored.

The recommended approach is to omit tin_value entirely when creating offices — it is automatically inherited from the parent.

// Recommended (v2026-04-20) — create a branch office
{
  "contact": {
    "name": "Branch Office Madrid",
    "parent_id": 456
  }
}

Affected endpoints: POST /accounts/{account}/contacts, PATCH /contacts/{id}

---

5. Creating an invoice with an inline contact now requires an identifier

If you create an invoice and pass the contact data inline (using a contact object instead of a contact_id), the contact must now include at least one of tin_value or cin_value. Requests without either will be rejected with 422 Unprocessable Entity.

This does not apply to simplified invoices (IssuedSimplifiedInvoice), which do not require an identified contact.

// v2026-04-20 — tin_value or cin_value is required
{
  "invoice": {
    "contact": {
      "name": "Acme Corp",
      "tin_value": "B12345678",
      "tin_scheme": "9915"
    }
  }
}

Affected endpoints: POST /accounts/{account}/invoices

---

New fields in existing responses

The following fields have been added to existing responses. They are backwards-compatible — your integration will continue to work without changes. However, if your code fails when it encounters unexpected JSON fields, update your response models to allow them.

Invoice responses (GET /invoices/{id}, POST, PATCH):

• invoice_references — array of amendment/prepayment references (see section 1 above)
• exchange_rate — the exchange rate applied when the invoice currency differs from the local tax authority currency
• exchange_date — the date of the exchange rate
• order_date — purchase order date (complements the existing ponumber field)
• contact.cin_value, contact.cin_scheme — company identifier of the invoice contact

Account responses (GET /accounts/{account}, GET /accounts):

• routing_codes — object containing up to 5 additional company identifiers (cin1_value/cin1_scheme through cin5_value/cin5_scheme)
• auto_remittance — boolean
• skip_line_taxable_base_rounding — boolean

Peppol transport response (GET /accounts/{account}/transports):

• sml_status — SML registration status: "not_published", "processing", or "published"
• peppol_directory_status — Peppol Directory listing status (replaces the old pending_peppol_directory_publish boolean)
• reception_document_types — list of document types this participant can receive via Peppol
• standard_documents and pending_peppol_directory_publish are no longer returned

---

New features available in this version

TIN verification — verify that a company name and tax number are registered with the tax authority before sending an invoice. Currently supports Spain (AEAT).

• POST /tin_verifications?country=es — submit a list of up to 20,000 TIN+name pairs for verification; returns 202 Accepted while processing runs in the background
• GET /tin_verifications/{id} — retrieve the results once processing is complete
• Subscribe to the tin_verification.finished webhook event to be notified automatically

New account configuration fields:

• routing_codes on accounts — store up to 5 additional company identifiers, useful for Peppol routing
• auto_remittance — automatically generate structured OGM remittance references on Belgian invoices
• skip_line_taxable_base_rounding — useful for invoices with many lines where small rounding differences accumulate; requires apply_taxes_per_line: true

KSeF (Polish e-invoicing) additions — if your integration handles Polish invoices, this version adds support for advance payment workflows (ZAL, ROZ, KOR_ZAL, KOR_ROZ), local government and VAT group invoicing scenarios, and several new tax report fields. See the changelog for the full list.

---

Migration checklist

Use this checklist before switching to v2026-04-20 in production.

Corrective invoices (credit notes, amendments):

• Replace the flat amendment fields (amended_number, amended_date, amend_reason, etc.) with invoice_references in all invoice create/update requests
• Include reference_type: "amend" on each entry
• Update response handling to read from invoice_references instead of the flat fields
• Test: create a credit note, read it back, and confirm the invoice_references array is present and correct

Invoice response fields:

• Remove any code that reads payment_method_info
• Update clasification_code_scheme → classification_code_scheme wherever you read invoice line responses
• Confirm your response handling accepts new fields: exchange_rate, exchange_date, order_date, contact.cin_value, contact.cin_scheme

Contacts:

• If you create contacts with parent_id, remove or align tin_value with the parent contact’s value
• If you create invoices with an inline contact object, ensure tin_value or cin_value is always included

Peppol transport:

• Update transport response handling: replace pending_peppol_directory_publish with peppol_directory_status, and remove standard_documents reads
• Confirm your response model accepts sml_status, peppol_directory_status, and reception_document_types

Accounts:

• Confirm your account response handling accepts the new routing_codes, auto_remittance, and skip_line_taxable_base_rounding fields

Testing your integration

Switch to the new version header in your sandbox or staging environment first:

X-B2B-API-Version: 2026-04-20

You can set this header per-request, so you can test against sandbox (or staging) without touching your production configuration. Once you have validated the checklist above, update the version in your production API key settings or request headers.