Migration guide v2025-01-01 → v2025-10-13

Everything you need to update your code.

This guide helps you upgrade from X-B2B-API-Version: 2025-01-01 to X-B2B-API-Version: 2025-10-13, focusing on what you need to change, not just what changed.

Changelog For the full list of additions and fixes, see the v2025-10-13 changelog.

Updating Your Integration

Update Base URL: Change your API base URL from app.b2brouter.net or app-staging.b2brouter.net to api.b2brouter.net or api-staging.b2brouter.net respectively.
Add Version Header: Include X-B2B-API-Version: 2025-10-13 header in all requests, or configure the default version in your group’s API Key settings.
Remove Format Extensions: Remove .json or .xml extensions from all endpoint paths. All responses are now JSON by default.
Update Path Segments:

Replace /projects/ with /accounts/ in all paths
Replace /clients/ with /contacts/ in all paths
Remove /users/ prefix from code list endpoints
Remove /api/v1/ prefix from directory and tax report endpoints

Update Pagination Handling: Update your code to read pagination data from the meta object instead of root-level properties:

Old (v2025-01-01)
New (v2025-10-13)

const totalCount = response.total_count;
const offset = response.offset;
const limit = response.limit;

const totalCount = response.meta.total_count;
const offset = response.meta.offset;
const limit = response.meta.limit;

Update Property Names: Replace all references to client with contact in your request and response handling code:

Old (v2025-01-01)
New (v2025-10-13)

// Request body
{
  "invoice": {
    "client_id": 123,
    "client": {
      "name": "Client Name",
      "taxcode": "9920:ESD29766391"
    }
  }
}

// Response body
{
  "invoice": {
    "id": 123,
    "client": { ... }
  }
}

// Request body
{
  "invoice": {
    "contact_id": 123,
    "contact": {
      "name": "Contact Name",
      "tin_scheme": "9920",
      "tin_value": "ESD29766391"
    }
  }
}

// Response body
{
  "invoice": {
    "id": 123,
    "contact": { ... }
  }
}

Consolidate Invoice Listings: Replace separate invoice listing endpoints with the consolidated /accounts/{account}/invoices endpoint using the type parameter:

For received invoices: GET /accounts/{account}/invoices?type=ReceivedInvoice
For self-invoices: GET /accounts/{account}/invoices?type=IssuedSelfInvoice
For simplified invoices: GET /accounts/{account}/invoices?type=IssuedSimplifiedInvoice

Update Tax Reports: Replace old deprecated tax report endpoints with the new consolidated endpoints under /accounts/{account}/tax_reports and /tax_reports/{id}. Check on New Tax Reports API for more details.
Handle Full Responses: Update your code to handle full resource representations returned by PUT, DELETE, and POST operations instead of empty 204 responses.
Remove XML Support: If your integration relied on XML responses, convert your code to handle JSON responses only.
Update Deprecated Invoice Attributes: Replace deprecated invoice attributes with their standardized alternatives:

Old (v2025-01-01)
New (v2025-10-13)

{
  "invoice": {
    "contact_person": "John Doe",
    "state": "accepted",
    "customer_party_identification": "12345",
    "accounting_cost": "DEPT-001",
    "iban": "ES6000000000000000000000",
    "bic": "ABCDESMMXXX",
    "num_contracte": "CONTRACT-2024",
    "organ_gestor": "ORG-001",
    "oficina_comptable": "OFF-001"
  }
}

{
  "invoice": {
    "customer_contact_person": "John Doe",
    // state removed - use POST /invoices/{id}/mark_as instead
    "contact": {
      "party_identification": "12345"
    },
    "buyer_accounting_reference": "DEPT-001",
    "bank_account": {
      "iban": "ES6000000000000000000000",
      "bic": "ABCDESMMXXX"
    },
    "contract_number": "CONTRACT-2024",
    "managing_unit": "ORG-001",
    "accounting_unit": "OFF-001"
  }
}

Update Contact/Client Attributes: Replace deprecated contact attributes with their standardized alternatives:

Old (v2025-01-01)
New (v2025-10-13)

{
  "contact": {
    "old_channel": "peppol",
    "taxcode": "9920:ESD29766391",
    "contact": "John Doe",
    "bank_account": "ES6000000000000000000000",
    "company_identifier": "A12345678",
    "transport_type": "peppol",
    "document_type": "xml.ubl.invoice.bis3",
    "posta_elettronica_certificata": "pec@example.it",
    "codice_destinatario": "ABC1234"
  }
}

{
  "contact": {
    "transport_type_code": "peppol",
    "tin_scheme": "9920",
    "tin_value": "ESD29766391",
    "contact_person": "John Doe",
    "bank_account_number": "ES6000000000000000000000",
    "cin_value": "A12345678",
    "document_type_code": "xml.ubl.invoice.bis3",
    "certified_email": "pec@example.it",
    "recipient_code": "ABC1234"
  }
}

Update Routing Codes: Routing code fields (cin1_value, cin1_scheme, …, cin5_value, cin5_scheme) are no longer accepted as top-level contact attributes. They must be sent inside a routing_codes wrapper:

Old (v2025-01-01)
New (v2025-10-13)

{
  "contact": {
    "name": "Ajuntament de Girona",
    "cin1_value": "L01170792",
    "cin1_scheme": "8014",
    "cin2_value": "L01170792",
    "cin2_scheme": "8014",
    "cin3_value": "L01170792",
    "cin3_scheme": "8014"
  }
}

{
  "contact": {
    "name": "Ajuntament de Girona",
    "routing_codes": {
      "cin1_value": "L01170792",
      "cin1_scheme": "8014",
      "cin2_value": "L01170792",
      "cin2_scheme": "8014",
      "cin3_value": "L01170792",
      "cin3_scheme": "8014"
    }
  }
}

In responses, routing codes are also returned inside the routing_codes object.

Update Invoice State Changes: Replace direct state attribute updates with the mark_as endpoint:

Old (v2025-01-01)
New (v2025-10-13)

PUT /invoices/{id}.json
{
  "invoice": {
    "state": "accepted"
  }
}

POST /invoices/{id}/mark_as
{
  "state": "accepted"
}

Testing Your Migration

We recommend thoroughly testing your integration in the staging environment (api-staging.b2brouter.net) before deploying to production. The X-B2B-API-Version header allows you to test the new version without affecting your current integration.