*MCP › Reference › Finance › Invoices*

# Void an invoice

> Voids a VALIDATED invoice with a reason, which is required and is kept.

> **Not reversible:** Voiding takes the document to `voided`, and no operation undoes it.

> **Requires human confirmation:** Put this tool on your client's “ask before running” list. The annotations are hints that the server declares, not guarantees: do not decide the approval from `destructiveHint` alone. The server flags this tool with `_meta["anthropic/requiresUserInteraction"]`, which clients that honor it use to ask a person before every call.

The invoice keeps its number —voiding does not release the numbering, which is what keeps the series continuous— and moves to `voided`. Only from `validated`: a draft is deleted from the application, not voided. It does NOT issue any credit note: if money has to be refunded, that is another document. Returns the full invoice, the same projection as its GET.

TOOL `filmo_invoices_void` · `invoices:write` · 120/min · Server annotation: Destructive · Requires human confirmation · Not reversible

## Arguments

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `invoiceId` | string | Yes | Invoice identifier. |
| `reason` | string | Yes | Reason for voiding. It is stored on the invoice and in its history. |
| `idempotencyKey` | string | No | Idempotency key chosen by the client (a UUID is recommended). Repeating the same key with the same arguments within 24 h returns the stored response without executing again; with different arguments it responds 422. It is the safe way to retry after a network failure. |
| `ifMatch` | string | No | Optimistic locking: the meta.etag you got from the detail read of this resource (or "*"). If the resource changed since, the call fails with 412 precondition_failed before writing anything; read it again and retry. Omit it to write unconditionally. |

## Result

On success the result carries `structuredContent` with `data` and `meta`. These are the attributes of `data`.

| Name | Type | Description |
| --- | --- | --- |
| `id` | string | Unique invoice identifier. |
| `invoiceNumber` | string | Invoice number; null while it is a draft (the number is assigned on validation). |
| `status` | string | Document lifecycle status: draft, validated (validated and numbered) or voided. `draft`, `validated`, `voided` |
| `isRectification` | boolean | Whether the invoice rectifies a previous one. Invoices created in Filmo are never rectifications, and credit notes are served by `/api/v1/credit-notes`; but `/api/v1/invoices` can still return imported rectifying documents (for example from a Rentman import) with this set to true, so deduplicate them against the credit notes by number. |
| `invoiceDate` | string<date-time> | Issue date in ISO 8601 with offset; null while it is a draft. |
| `dueDate` | string<date-time> | Due date in ISO 8601 with offset; null if not set. |
| `currency` | string | Invoice currency as an ISO 4217 code (for example "EUR"). |
| `contact` | object | Compact reference to the invoiced contact; null if none. |
| `contact.id` | string | Unique contact identifier. |
| `contact.name` | string | Contact name. |
| `orderId` | string | Identifier of the source order; null if the invoice does not come from an order. |
| `orderNumber` | string | Number of the source order; null if the invoice does not come from an order. |
| `projectId` | string | Identifier of the linked project; null if not linked. |
| `subTotal` | string | Subtotal before discounts and taxes, as a decimal string "1234.50" (ROUND_HALF_UP). |
| `discountTotal` | string | Total discounts as a decimal string "1234.50" (ROUND_HALF_UP). |
| `taxesPrice` | string | Tax total as a decimal string "1234.50" (ROUND_HALF_UP). |
| `netPrice` | string | Taxable base (net before taxes) as a decimal string "1234.50" (ROUND_HALF_UP). |
| `grossPrice` | string | Total including taxes, as a decimal string "1234.50" (ROUND_HALF_UP). |
| `totalPaid` | string | Amount collected to date as a decimal string "1234.50" (ROUND_HALF_UP); null if not recorded. |
| `paymentStatus` | string | Payment status: unpaid (nothing collected yet, also for invoices without a recorded collection), partially_paid, paid, overpaid (collected above the total), overdue (past due and unpaid) or voided (the document is voided, whatever was collected before). The `paymentStatus` filter uses the same values. `unpaid`, `partially_paid`, `paid`, `overpaid`, `overdue`, `voided` |
| `paymentMethod` | string | Payment method of the invoice; null if not recorded. |
| `tags` | object[] | Tags attached to the invoice, with their identifier and name. |
| `tags.id` | string | Unique identifier of the tag. |
| `tags.name` | string | Tag name. |
| `createdAt` | string<date-time> | Creation date in ISO 8601 with offset. |
| `updatedAt` | string<date-time> | Last update date in ISO 8601 with offset. |
| `projectName` | string | Name of the linked project; null if not linked. |
| `taxBreakdown` | object[] | Tax breakdown by type; null if not calculated. |
| `taxBreakdown.taxType` | string | Tax type key (for example "IVA_21"). |
| `taxBreakdown.label` | string | Human-readable tax label. |
| `taxBreakdown.rate` | number | Tax rate applied, as a percentage (for example 21 for 21%). |
| `taxBreakdown.baseAmount` | string | Taxable base the tax is applied to, as a decimal string "1234.50" (ROUND_HALF_UP). |
| `taxBreakdown.amount` | string | Tax amount as a decimal string "1234.50" (ROUND_HALF_UP). |
| `productDiscountTotal` | string | Total discounts applied at product level, as a decimal string "1234.50" (ROUND_HALF_UP). productDiscountTotal + globalDiscountTotal = discountTotal. |
| `globalDiscountTotal` | string | Global discount total of the document, as a decimal string "1234.50" (ROUND_HALF_UP). productDiscountTotal + globalDiscountTotal = discountTotal. |
| `insuranceTotal` | string | Insurance total as a decimal string "1234.50" (ROUND_HALF_UP). |
| `depositTotal` | string | Deposit total as a decimal string "1234.50" (ROUND_HALF_UP). |
| `exchangeRate` | number | Exchange rate applied when the currency differs from the base currency; null if not applicable. |
| `billingAddress` | object | Billing address; null if not recorded. |
| `billingAddress.label` | string | Descriptive label of the address; null if not recorded. |
| `billingAddress.addressLine1` | string | First address line; null if not recorded. |
| `billingAddress.addressLine2` | string | Second address line; null if not recorded. |
| `billingAddress.city` | string | City; null if not recorded. |
| `billingAddress.province` | string | Province or region; null if not recorded. |
| `billingAddress.postcode` | string | Postal code; null if not recorded. |
| `billingAddress.country` | string | Country; null if not recorded. |
| `sourceQuoteIds` | string[] | Identifiers of the source quotes; null if the invoice does not come from quotes. |
| `sourceProformaIds` | string[] | Identifiers of the source proformas; null if the invoice does not come from proformas. |

*Call · filmo_invoices_void*

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_invoices_void",
    "arguments": {
      "invoiceId": "invo_8f2a1c",
      "reason": "<reason>"
    }
  }
}
```

*Result (generated from the schema)*

```json
{
  "structuredContent": {
    "data": {
      "id": "id_8f2a1c",
      "invoiceNumber": "<invoiceNumber>",
      "status": "draft",
      "isRectification": true,
      "invoiceDate": "2026-09-01T08:00:00Z",
      "dueDate": "2026-09-01T08:00:00Z",
      "currency": "EUR",
      "contact": {
        "id": "id_8f2a1c",
        "name": "Example"
      },
      "orderId": "orde_8f2a1c",
      "orderNumber": "<orderNumber>",
      "projectId": "proj_8f2a1c",
      "subTotal": "1234.50",
      "discountTotal": "1234.50",
      "taxesPrice": "1234.50",
      "netPrice": "1234.50",
      "grossPrice": "1234.50",
      "totalPaid": "1234.50",
      "paymentStatus": "unpaid",
      "paymentMethod": "<paymentMethod>",
      "tags": [
        {
          "id": "id_8f2a1c",
          "name": "Example"
        }
      ],
      "createdAt": "2026-09-01T08:00:00Z",
      "updatedAt": "2026-09-01T08:00:00Z",
      "projectName": "Example",
      "taxBreakdown": [
        {
          "taxType": "1234.50",
          "label": "Example",
          "rate": 1,
          "baseAmount": "1234.50",
          "amount": "1234.50"
        }
      ],
      "productDiscountTotal": "1234.50",
      "globalDiscountTotal": "1234.50",
      "insuranceTotal": "1234.50",
      "depositTotal": "1234.50",
      "exchangeRate": 1,
      "billingAddress": {
        "label": "Example",
        "addressLine1": "<addressLine1>",
        "addressLine2": "<addressLine2>",
        "city": "<city>",
        "province": "<province>",
        "postcode": "<postcode>",
        "country": "ES"
      },
      "sourceQuoteIds": [
        "sour_8f2a1c"
      ],
      "sourceProformaIds": [
        "sour_8f2a1c"
      ]
    },
    "meta": {
      "idempotencyKey": "<the key you sent, or the one the server generated>",
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "reset": 42
      }
    }
  }
}
```

## The same operation by REST

This tool runs [`POST /api/v1/invoices/{invoiceId}/void`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/void-an-invoice).

---

Canonical URL: https://docs.filmo.io/mcp/tools/invoices/filmo-invoices-void  
Last updated: 2026-10-25