# Update the e-invoicing settings > The einvoice.settings.update operation: PUT /api/v1/einvoice/settings in the REST API and the einvoice_settings_update tool in the MCP server. Replaces the legal entity's e-invoicing settings in the mode of the request: its routes and, optionally, its electronic address. A route says which provider sends the e-invoices of documents to buyers in `country` for `transactionType`: `b2b` and `b2c` follow the invoice's buyer, `b2g` applies to customers whose metadata says `einvoice_buyer_type: b2g`. Each country and type takes one route. The provider must exist, be usable here (the `fake` provider only in development and test) and serve the country and type. From then on, every invoice and credit note issued for a routed case gets an e-invoice (EN 16931 UBL, Peppol BIS Billing 3.0), sent after it is issued; documents issued before aren't sent. Configuring the home country's domestic B2B route in live mode meets the go-live checklist item `einvoice_home`. Pass `expectedVersion` to refuse the change if someone else changed the settings meanwhile. Needs `entities:invoice_settings` (owners, admins and finance). ## At a glance - **REST:** `PUT /api/v1/einvoice/settings` - **MCP tool:** `einvoice_settings_update` - **Operation ID:** `einvoice.settings.update` - **Scope:** Legal entity - **Permission:** `entities:invoice_settings` - **Risk tier:** `write` - **Dry run:** Supported (send `Ownrecord-Dry-Run: true`) - **Idempotency:** `Idempotency-Key` optional - **Modes:** Test and live - **Plan feature:** `einvoicing.enabled` - **Authentication:** API key with the `entities:invoice_settings` scope - **Since:** M13 ## Request ### Body A JSON object (`Content-Type: application/json`): | Field | Type | Required | Description | | -------------------------- | ------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `routes` | array of object | Yes | Every route, replacing the current ones; \[] removes them all. | | `routes[].country` | string | Yes | The country of the buyers this route serves. | | `routes[].transactionType` | one of `b2b`, `b2g`, `b2c` | Yes | | | `routes[].provider` | string | Yes | A provider ID from `einvoice.settings.get` → `providers`. | | `routes[].format` | one of `UBL_2_1_PEPPOL_BIS_3`, `CII`, `national` | No | The document format; Ownrecord generates EN 16931 UBL 2.1 (Peppol BIS Billing 3.0). | | `endpoint` | string or null | No | The entity's electronic address, \:\ (e.g. 9934:HR12345678903); null removes it, omitted keeps it. | | `expectedVersion` | integer (at least 0) | No | | ## Response `200 OK` with a JSON object: | Field | Type | Description | | ------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `object` | `"einvoice_settings"` | | | `entityId` | `ent_…` ID | | | `livemode` | boolean | | | `version` | integer (at least 0) | 0 while nothing is configured; pass it as `expectedVersion`. | | `routes` | array of object | | | `routes[].country` | string | ISO 3166-1 alpha-2 country of the buyers this route serves. | | `routes[].transactionType` | one of `b2b`, `b2g`, `b2c` | | | `routes[].provider` | string | | | `routes[].format` | one of `UBL_2_1_PEPPOL_BIS_3`, `CII`, `national` | | | `routes[].providerAvailable` | boolean | Whether the provider can be used here (the fake provider only in development and test). | | `endpoint` | string or null | The entity's electronic address (\:\) as configured. | | `derivedEndpoint` | string or null | The address derived from the entity's VAT ID, used when `endpoint` is null. | | `homeMandate` | object or null | The home country's domestic B2B e-invoicing mandate in force, and whether a usable route covers it (a go-live requirement). | | `suggestions` | array of object | | | `suggestions[].country` | string | | | `suggestions[].transactionType` | one of `b2b`, `b2g`, `b2c` | | | `suggestions[].mandate` | string | | | `suggestions[].scope` | string | | | `suggestions[].startDate` | string | | | `suggestions[].inForce` | boolean | | | `suggestions[].configured` | boolean | | | `suggestions[].knowledgeId` | string | | | `suggestions[].status` | string | The mandate record's review status in the knowledge base. | | `providers` | array of object | | | `providers[].id` | string | | | `providers[].name` | string | | | `providers[].description` | string | | | `providers[].formats` | array of one of `UBL_2_1_PEPPOL_BIS_3`, `CII`, `national` | | | `providers[].countries` | `"*"` or array of string | | | `providers[].devOnly` | boolean | | | `providers[].available` | boolean | | | `updatedAt` | date-time or null | | ## Examples ### Route domestic B2B e-invoices to a provider ```http PUT /api/v1/einvoice/settings Authorization: Bearer or_test_… Content-Type: application/json { "routes": [ { "country": "HR", "transactionType": "b2b", "provider": "fake", "format": "UBL_2_1_PEPPOL_BIS_3" } ], "expectedVersion": 0 } ``` Response (`200`): ```json { "object": "einvoice_settings", "entityId": "ent_01jacq4m3xf0v8w9zq2y7k5n6h", "livemode": false, "version": 1, "routes": [ { "country": "HR", "transactionType": "b2b", "provider": "fake", "format": "UBL_2_1_PEPPOL_BIS_3", "providerAvailable": true } ], "endpoint": null, "derivedEndpoint": "9934:HR12345678903", "homeMandate": { "country": "HR", "name": "Fiscalization 2.0, domestic B2B e-invoicing", "startDate": "2026-01-01", "configured": true }, "suggestions": [ { "country": "HR", "transactionType": "b2g", "mandate": "B2G e-invoicing", "scope": "b2g", "startDate": "2019-07-01", "inForce": true, "configured": false, "knowledgeId": "kn_01jacq4m3xf0v8w9zq2y7k5n80", "status": "researched" }, { "country": "HR", "transactionType": "b2b", "mandate": "Fiscalization 2.0, domestic B2B e-invoicing", "scope": "b2b_domestic", "startDate": "2026-01-01", "inForce": true, "configured": true, "knowledgeId": "kn_01jacq4m3xf0v8w9zq2y7k5n81", "status": "researched" } ], "providers": [ { "id": "fake", "name": "Fake provider", "description": "Development and test only: records each e-invoice and reports it queued, delivered after a minute and accepted after five.", "formats": ["UBL_2_1_PEPPOL_BIS_3"], "countries": "*", "devOnly": true, "available": true } ], "updatedAt": "2026-10-20T09:00:00.000Z" } ``` ## Errors | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`einvoice_provider_unknown`](https://ownrecord.io/docs/reference/errors.md#einvoice_provider_unknown) | 400 | A route names a provider that doesn't exist. | Use one of the providers `einvoice.settings.get` lists under `providers`. | | [`einvoice_provider_unavailable`](https://ownrecord.io/docs/reference/errors.md#einvoice_provider_unavailable) | 400 | A route names a provider that can't be used here (the fake provider outside development and test). | Choose a provider that is available in this environment. The fake provider exists only in development and test; certified providers are added with the product owner (spec §35 #8). | | [`einvoice_provider_unsupported`](https://ownrecord.io/docs/reference/errors.md#einvoice_provider_unsupported) | 400 | The provider doesn't serve the route's country and type, or not in that format. | Choose another provider for this country and transaction type, or remove the route. `providers[].countries` in `einvoice.settings.get` says what each provider covers. | | [`einvoice_routes_invalid`](https://ownrecord.io/docs/reference/errors.md#einvoice_routes_invalid) | 400 | A country and type has more than one route. | Give each country and transaction type at most one provider, with ISO 3166-1 country codes and the types b2b, b2g or b2c. | | [`einvoice_endpoint_invalid`](https://ownrecord.io/docs/reference/errors.md#einvoice_endpoint_invalid) | 400 | The electronic address isn't \:\ with a Peppol scheme. | Write it as \:\ with a scheme from the Peppol list of electronic address schemes, e.g. 9934:HR12345678903 or 0208:0123456789. | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A country code or another value is malformed. | Fix the fields listed in `details.issues` and send the request again. | | [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict) | 409 | The settings changed since `expectedVersion`, or at the same moment. | Fetch the object again and retry the change. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't change this entity's invoice settings. | Ask an organization owner or admin for a role or scope that allows this action. | | [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required) | 400 | The request names no legal entity. | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`). | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`entitlement_required`](https://ownrecord.io/docs/reference/errors.md#entitlement_required), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).