# Einvoices tools

> MCP tools for Einvoices: einvoices_get, einvoices_list, einvoices_retry.

- `einvoices_get`: Get an e-invoice
- `einvoices_list`: List e-invoices
- `einvoices_retry`: Retry an e-invoice

## `einvoices_get`

**Get an e-invoice.** Operation [`einvoices.get`](https://ownrecord.io/docs/reference/einvoices-get.md) · Brand level · permission `invoices:read` · risk tier `read` · since M13

Returns one e-invoice (`einv_…`): the invoice or credit note it was generated from, the route it was sent by
(country, transaction type, provider, format), its status and history, the provider's ID, the stored document
(its SHA-256 and the generator version) and, when it failed or was rejected, the reason. E-invoices of another
brand or mode are `resource_not_found`.

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

### Arguments

| Argument    | Type          | Required | Description                                                                                                                              |
| ----------- | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | ID (`einv_…`) | yes      | –                                                                                                                                        |
| `entity_id` | ID (`ent_…`)  | no       | Optional: the brand's legal entity (ent\_…); `brand_id` alone is enough.                                                                 |
| `brand_id`  | ID (`brd_…`)  | no       | The brand to act on (brd\_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand. |

- **Brand:** pass `brand_id` with an organization or entity key; a brand key acts on its own brand.
- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No such e-invoice for this brand in this mode.
- [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no brand.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see this brand's invoices.

### Examples

**An accepted e-invoice**

Arguments:

```json
{
  "id": "einv_01jbxa6qk3f0v8w9zq2y7k5n70",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz"
}
```

Result `output`:

```json
{
  "id": "einv_01jbxa6qk3f0v8w9zq2y7k5n70",
  "object": "einvoice",
  "livemode": false,
  "orgId": "org_01jacq4m3xf0v8w9zq2y7k5n6a",
  "entityId": "ent_01jacq4m3xf0v8w9zq2y7k5n6h",
  "brandId": "brd_01jacq4m3xf0v8w9zq2y7k5n6j",
  "documentKind": "invoice",
  "documentId": "inv_01jacq4m3xf0v8w9zq2y7k5n70",
  "documentNumber": "ACME-2026-000101",
  "customerId": "cus_01jacq4m3xf0v8w9zq2y7k5n6k",
  "country": "HR",
  "transactionType": "b2b",
  "provider": "fake",
  "format": "UBL_2_1_PEPPOL_BIS_3",
  "status": "accepted",
  "externalId": "fake_einv_000001_inv_01jacq4m3xf0v8w9zq2y7k5n70",
  "buyerEndpoint": null,
  "sellerEndpoint": null,
  "buyerReference": null,
  "file": {
    "fileId": "file_01jbxa6qk3f0v8w9zq2y7k5n71",
    "sha256": "3f0c1e9b7a2d4c6e8f0a1b3c5d7e9f1a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e",
    "size": 4211,
    "generator": "ubl_peppol_bis_3@1"
  },
  "error": null,
  "attempts": 1,
  "sentAt": "2026-10-14T09:31:02.000Z",
  "lastCheckedAt": "2026-10-14T09:45:00.000Z",
  "history": [
    {
      "status": "pending",
      "at": "2026-10-14T09:30:05.000Z",
      "reason": null
    },
    {
      "status": "queued",
      "at": "2026-10-14T09:31:02.000Z",
      "reason": null
    },
    {
      "status": "accepted",
      "at": "2026-10-14T09:45:00.000Z",
      "reason": null
    }
  ],
  "createdAt": "2026-10-14T09:30:05.000Z",
  "updatedAt": "2026-10-14T09:45:00.000Z"
}
```

**An e-invoice that couldn't be sent**

Arguments:

```json
{
  "id": "einv_01jbxa6qk3f0v8w9zq2y7k5n70",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz"
}
```

Result `output`:

```json
{
  "id": "einv_01jbxa6qk3f0v8w9zq2y7k5n70",
  "object": "einvoice",
  "livemode": false,
  "orgId": "org_01jacq4m3xf0v8w9zq2y7k5n6a",
  "entityId": "ent_01jacq4m3xf0v8w9zq2y7k5n6h",
  "brandId": "brd_01jacq4m3xf0v8w9zq2y7k5n6j",
  "documentKind": "invoice",
  "documentId": "inv_01jacq4m3xf0v8w9zq2y7k5n70",
  "documentNumber": "ACME-2026-000101",
  "customerId": "cus_01jacq4m3xf0v8w9zq2y7k5n6k",
  "country": "HR",
  "transactionType": "b2b",
  "provider": "fake",
  "format": "UBL_2_1_PEPPOL_BIS_3",
  "status": "failed",
  "externalId": null,
  "buyerEndpoint": null,
  "sellerEndpoint": null,
  "buyerReference": null,
  "file": null,
  "error": {
    "code": "einvoice_endpoint_missing",
    "message": "The buyer has no electronic address: set the customer's `einvoice_endpoint` metadata (<scheme>:<identifier>).",
    "at": "2026-10-14T09:31:02.000Z"
  },
  "attempts": 1,
  "sentAt": null,
  "lastCheckedAt": null,
  "history": [
    {
      "status": "pending",
      "at": "2026-10-14T09:30:05.000Z",
      "reason": null
    },
    {
      "status": "failed",
      "at": "2026-10-14T09:31:02.000Z",
      "reason": "The buyer has no electronic address: set the customer's `einvoice_endpoint` metadata (<scheme>:<identifier>)."
    }
  ],
  "createdAt": "2026-10-14T09:30:05.000Z",
  "updatedAt": "2026-10-14T09:31:02.000Z"
}
```

## `einvoices_list`

**List e-invoices.** Operation [`einvoices.list`](https://ownrecord.io/docs/reference/einvoices-list.md) · Brand level · permission `invoices:read` · risk tier `read` · since M13

Lists the brand's e-invoices in the mode of the request, newest first: one per invoice or credit note whose case
(the buyer's country and transaction type) the entity's e-invoicing settings route to a provider, with its
status (`pending`, `queued`, `delivered`, `accepted`, `rejected`, `failed`), the provider's ID and the stored
document. Filter by `documentId` (an invoice's or credit note's e-invoice) or `status`. Paginate with `limit`
(1–100, default 10) and `starting_after`.

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

### Arguments

| Argument         | Type                                                                      | Required | Description                                                                                                                              |
| ---------------- | ------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `documentId`     | string                                                                    | no       | The e-invoice of one invoice (`inv_…`) or credit note (`cn_…`).                                                                          |
| `status`         | one of `pending`, `queued`, `delivered`, `accepted`, `rejected`, `failed` | no       | Only e-invoices in this status.                                                                                                          |
| `limit`          | integer                                                                   | no       | Page size, 1 to 100 (default 10). (1–100)                                                                                                |
| `starting_after` | ID (`einv_…`)                                                             | no       | The `next_cursor` of the previous page.                                                                                                  |
| `entity_id`      | ID (`ent_…`)                                                              | no       | Optional: the brand's legal entity (ent\_…); `brand_id` alone is enough.                                                                 |
| `brand_id`       | ID (`brd_…`)                                                              | no       | The brand to act on (brd\_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand. |

- **Brand:** pass `brand_id` with an organization or entity key; a brand key acts on its own brand.
- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A filter is malformed.
- [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no brand.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see this brand's invoices.

### Example

**The e-invoice of an invoice**

Arguments:

```json
{
  "documentId": "inv_01jacq4m3xf0v8w9zq2y7k5n70",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz"
}
```

Result `output`:

```json
{
  "object": "list",
  "data": [
    {
      "id": "einv_01jbxa6qk3f0v8w9zq2y7k5n70",
      "object": "einvoice",
      "livemode": false,
      "orgId": "org_01jacq4m3xf0v8w9zq2y7k5n6a",
      "entityId": "ent_01jacq4m3xf0v8w9zq2y7k5n6h",
      "brandId": "brd_01jacq4m3xf0v8w9zq2y7k5n6j",
      "documentKind": "invoice",
      "documentId": "inv_01jacq4m3xf0v8w9zq2y7k5n70",
      "documentNumber": "ACME-2026-000101",
      "customerId": "cus_01jacq4m3xf0v8w9zq2y7k5n6k",
      "country": "HR",
      "transactionType": "b2b",
      "provider": "fake",
      "format": "UBL_2_1_PEPPOL_BIS_3",
      "status": "accepted",
      "externalId": "fake_einv_000001_inv_01jacq4m3xf0v8w9zq2y7k5n70",
      "buyerEndpoint": null,
      "sellerEndpoint": null,
      "buyerReference": null,
      "file": {
        "fileId": "file_01jbxa6qk3f0v8w9zq2y7k5n71",
        "sha256": "3f0c1e9b7a2d4c6e8f0a1b3c5d7e9f1a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e",
        "size": 4211,
        "generator": "ubl_peppol_bis_3@1"
      },
      "error": null,
      "attempts": 1,
      "sentAt": "2026-10-14T09:31:02.000Z",
      "lastCheckedAt": "2026-10-14T09:45:00.000Z",
      "history": [
        {
          "status": "pending",
          "at": "2026-10-14T09:30:05.000Z",
          "reason": null
        },
        {
          "status": "queued",
          "at": "2026-10-14T09:31:02.000Z",
          "reason": null
        },
        {
          "status": "accepted",
          "at": "2026-10-14T09:45:00.000Z",
          "reason": null
        }
      ],
      "createdAt": "2026-10-14T09:30:05.000Z",
      "updatedAt": "2026-10-14T09:45:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## `einvoices_retry`

**Retry an e-invoice.** Operation [`einvoices.retry`](https://ownrecord.io/docs/reference/einvoices-retry.md) · Brand level · permission `invoices:write` · risk tier `write` · since M13

Sends a `failed` or `rejected` e-invoice again, once its cause is fixed: for example after setting the customer's
`einvoice_endpoint` metadata (its electronic address). The e-invoice goes back to `pending` with the customer's
and the entity's current e-invoicing details, one attempt more, and is generated and handed to its provider after
the call returns (`einvoice.sent`, or `einvoice.failed` again). The document itself never changes: correct a wrong
invoice with a credit note.

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

### Arguments

| Argument          | Type          | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`einv_…`) | yes      | –                                                                                                                                                                                                        |
| `entity_id`       | ID (`ent_…`)  | no       | Optional: the brand's legal entity (ent\_…); `brand_id` alone is enough.                                                                                                                                 |
| `brand_id`        | ID (`brd_…`)  | no       | The brand to act on (brd\_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand.                                                                 |
| `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`)                                                                                 |

- **Brand:** pass `brand_id` with an organization or entity key; a brand key acts on its own brand.
- **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.

### Errors

- [`einvoice_not_retryable`](https://ownrecord.io/docs/reference/errors.md#einvoice_not_retryable): The e-invoice is pending, on its way or done.
- [`einvoice_provider_unavailable`](https://ownrecord.io/docs/reference/errors.md#einvoice_provider_unavailable): Its provider can't be used here any more; change the entity's route and contact support.
- [`einvoice_endpoint_invalid`](https://ownrecord.io/docs/reference/errors.md#einvoice_endpoint_invalid): The customer's `einvoice_endpoint` metadata is malformed.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No such e-invoice for this brand in this mode.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The e-invoice changed at the same moment; try again.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't change this brand's invoices.

### Example

**Send a failed e-invoice again**

Arguments:

```json
{
  "id": "einv_01jbxa6qk3f0v8w9zq2y7k5n70",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "einv_01jbxa6qk3f0v8w9zq2y7k5n70",
  "object": "einvoice",
  "livemode": false,
  "orgId": "org_01jacq4m3xf0v8w9zq2y7k5n6a",
  "entityId": "ent_01jacq4m3xf0v8w9zq2y7k5n6h",
  "brandId": "brd_01jacq4m3xf0v8w9zq2y7k5n6j",
  "documentKind": "invoice",
  "documentId": "inv_01jacq4m3xf0v8w9zq2y7k5n70",
  "documentNumber": "ACME-2026-000101",
  "customerId": "cus_01jacq4m3xf0v8w9zq2y7k5n6k",
  "country": "HR",
  "transactionType": "b2b",
  "provider": "fake",
  "format": "UBL_2_1_PEPPOL_BIS_3",
  "status": "pending",
  "externalId": null,
  "buyerEndpoint": "0208:0123456789",
  "sellerEndpoint": null,
  "buyerReference": null,
  "file": null,
  "error": null,
  "attempts": 2,
  "sentAt": null,
  "lastCheckedAt": null,
  "history": [
    {
      "status": "pending",
      "at": "2026-10-14T09:30:05.000Z",
      "reason": null
    },
    {
      "status": "failed",
      "at": "2026-10-14T09:31:02.000Z",
      "reason": "The buyer has no electronic address: set the customer's `einvoice_endpoint` metadata (<scheme>:<identifier>)."
    },
    {
      "status": "pending",
      "at": "2026-10-15T08:00:00.000Z",
      "reason": null
    }
  ],
  "createdAt": "2026-10-14T09:30:05.000Z",
  "updatedAt": "2026-10-15T08:00:00.000Z"
}
```