*REST API › Objects › Finance*

# Invoice

> The invoice, as returned by the API.

An issued invoice. `status` is the document lifecycle (draft, validated or voided) and `paymentStatus` says how much has been collected. It points to its contact, order and project, and the list returns only documents of type invoice. Invoices are bounded to the subscription that owns the key. Invoices have no series field. Only the detail read, [`GET /api/v1/invoices/{invoiceId}`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/get-an-invoice), carries the tax breakdown ([`taxBreakdown`](https://docs.filmo.io/rest-api/objects/invoice#response-taxBreakdown): tax type, label, rate, base and amount). It also adds the totals of discounts, insurance and deposit, the exchange rate, the billing address, the project name and the quotes and proformas the invoice came from.

Schemas: `InvoiceDto`, `InvoiceDetailDto`

## Attributes

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

## Values

| Field | Values |
| --- | --- |
| `status` | `draft`, `validated`, `voided` |
| `paymentStatus` | `unpaid`, `partially_paid`, `paid`, `overpaid`, `overdue`, `voided` |

## Example

*Invoice · Generated from the schema*

```json
{
  "id": "id_8f2a1c",
  "invoiceNumber": "string",
  "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": "string",
  "orderNumber": "string",
  "projectId": "string",
  "subTotal": "1234.50",
  "discountTotal": "1234.50",
  "taxesPrice": "1234.50",
  "netPrice": "1234.50",
  "grossPrice": "1234.50",
  "totalPaid": "1234.50",
  "paymentStatus": "unpaid",
  "paymentMethod": "string",
  "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": "string",
    "addressLine2": "string",
    "city": "string",
    "province": "string",
    "postcode": "string",
    "country": "ES"
  },
  "sourceQuoteIds": [
    "string"
  ],
  "sourceProformaIds": [
    "string"
  ]
}
```

## Returned by

- [`GET /api/v1/invoices`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/list-invoices) — List invoices
- [`GET /api/v1/invoices/{invoiceId}`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/get-an-invoice) — Get an invoice

## Modified by

- [`POST /api/v1/invoices/{invoiceId}/validate`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/validate-an-invoice) — Validate an invoice
- [`POST /api/v1/invoices/{invoiceId}/void`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/void-an-invoice) — Void an invoice
- [`PUT /api/v1/invoices/external/{originSystem}/{originExternalId}`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/create-or-update-the-mirror-of-an-externally-issued-invoice) — Create or update the mirror of an externally issued invoice

---

Canonical URL: https://docs.filmo.io/rest-api/objects/invoice  
Last updated: 2026-10-25