# Einvoice tools

> MCP tools for Einvoice: einvoice_settings_get, einvoice_settings_update.

- `einvoice_settings_get`: Get the e-invoicing settings
- `einvoice_settings_update`: Update the e-invoicing settings

## `einvoice_settings_get`

**Get the e-invoicing settings.** Operation [`einvoice.settings.get`](https://ownrecord.io/docs/reference/einvoice-settings-get.md) · Legal entity level · permission `entities:read` · risk tier `read` · since M13

Returns the legal entity's e-invoicing settings in the mode of the request: its routes (which provider sends the
e-invoices of documents to buyers in a country, for a transaction type `b2b`, `b2g` or `b2c`), its electronic
address (its Peppol participant ID; else the one derived from its VAT ID), the providers that can be used here,
and what the knowledge base's e-invoicing mandates of its home country suggest configuring.

`homeMandate` is the home country's domestic B2B mandate in force, if there is one; its `configured` must be true
in live mode before a brand of the entity can go live (the go-live checklist item `einvoice_home`). Test and live
mode have their own settings. Mandates are shown whatever their review status in the knowledge base (`status`).

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument    | Type         | Required | Description                                                                                                                                       |
| ----------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity_id` | ID (`ent_…`) | no       | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. |

- **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity.
- **Read-only:** changes nothing; `idempotency_key` is ignored.
- **Plan feature:** needs `einvoicing.enabled`.

### Errors

- [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): The entity doesn't exist in this organization.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see this entity.

### Examples

**A Croatian entity before configuration**

The home country requires e-invoices for domestic B2B sales; nothing is configured yet.

Arguments:

```json
{
  "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy"
}
```

Result `output`:

```json
{
  "object": "einvoice_settings",
  "entityId": "ent_01jacq4m3xf0v8w9zq2y7k5n6h",
  "livemode": false,
  "version": 0,
  "routes": [],
  "endpoint": null,
  "derivedEndpoint": "9934:HR12345678903",
  "homeMandate": {
    "country": "HR",
    "name": "Fiscalization 2.0, domestic B2B e-invoicing",
    "startDate": "2026-01-01",
    "configured": false
  },
  "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": false,
      "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": null
}
```

**Domestic B2B e-invoices routed to a provider**

Arguments:

```json
{
  "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy"
}
```

Result `output`:

```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"
}
```

## `einvoice_settings_update`

**Update the e-invoicing settings.** Operation [`einvoice.settings.update`](https://ownrecord.io/docs/reference/einvoice-settings-update.md) · Legal entity level · permission `entities:invoice_settings` · risk tier `write` · since M13

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).

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument          | Type            | Required | Description                                                                                                                                                                                              |
| ----------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `routes`          | array of object | yes      | Every route, replacing the current ones; \[] removes them all. (at most 200 items)                                                                                                                       |
| `endpoint`        | string or null  | no       | The entity's electronic address, \<scheme>:\<identifier> (e.g. 9934:HR12345678903); null removes it, omitted keeps it.                                                                                   |
| `expectedVersion` | integer         | no       | (0–9007199254740991)                                                                                                                                                                                     |
| `entity_id`       | ID (`ent_…`)    | no       | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity.                                                        |
| `idempotency_key` | string          | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean         | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity.
- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.
- **Plan feature:** needs `einvoicing.enabled`.

### Errors

- [`einvoice_provider_unknown`](https://ownrecord.io/docs/reference/errors.md#einvoice_provider_unknown): A route names a provider that doesn't exist.
- [`einvoice_provider_unavailable`](https://ownrecord.io/docs/reference/errors.md#einvoice_provider_unavailable): A route names a provider that can't be used here (the fake provider outside development and test).
- [`einvoice_provider_unsupported`](https://ownrecord.io/docs/reference/errors.md#einvoice_provider_unsupported): The provider doesn't serve the route's country and type, or not in that format.
- [`einvoice_routes_invalid`](https://ownrecord.io/docs/reference/errors.md#einvoice_routes_invalid): A country and type has more than one route.
- [`einvoice_endpoint_invalid`](https://ownrecord.io/docs/reference/errors.md#einvoice_endpoint_invalid): The electronic address isn't \<scheme>:\<identifier> with a Peppol scheme.
- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A country code or another value is malformed.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The settings changed since `expectedVersion`, or at the same moment.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't change this entity's invoice settings.
- [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity.

### Example

**Route domestic B2B e-invoices to a provider**

Arguments:

```json
{
  "routes": [
    {
      "country": "HR",
      "transactionType": "b2b",
      "provider": "fake",
      "format": "UBL_2_1_PEPPOL_BIS_3"
    }
  ],
  "expectedVersion": 0,
  "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```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"
}
```