Update the e-invoicing settings

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, <scheme>:<identifier> (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 (<scheme>:<identifier>) 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`	400	A route names a provider that doesn't exist.	Use one of the providers `einvoice.settings.get` lists under `providers`.
`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`	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`	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`	400	The electronic address isn't <scheme>:<identifier> with a Peppol scheme.	Write it as <scheme>:<identifier> with a scheme from the Peppol list of electronic address schemes, e.g. 9934:HR12345678903 or 0208:0123456789.
`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`	409	The settings changed since `expectedVersion`, or at the same moment.	Fetch the object again and retry the change.
`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`	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: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, resource_not_found, idempotency_key_reused, idempotency_in_progress, entitlement_required, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

Route domestic B2B e-invoices to a provider#

Errors#