*REST API › Endpoint reference › Finance › Supplier invoices*

# List supplier invoices

> Returns the invoices received from suppliers, cursor-paginated, with the same compact card as the detail read.

Filter by status within the purchasing cycle, supplier contact, linked sales order, project, invoice date and due date. Sorted by invoice date, most recent first.

`GET /api/v1/supplier-invoices` — scope `supplier-invoices:read`

Scope: `supplier-invoices:read` · 120/min · Add-on (402) · MCP: `filmo_supplier_invoices_list`

## Authorizations

Bearer API key with the scope below. `supplier-invoices:read`

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | Page size (1-500). Defaults to 50. = `50` |
| `cursor` | string | No | Opaque cursor of the page to return. Pass the value of `pagination.nextCursor` from the previous response; treat it as opaque. |
| `createdOn` | string | No | The creation date of the resource falls on this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `createdAfter` | string | No | The creation date of the resource is after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `createdBefore` | string | No | The creation date of the resource is before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `createdFrom` | string | No | The creation date of the resource is on or after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `createdTo` | string | No | The creation date of the resource is on or before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedOn` | string | No | The last update date of the resource falls on this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedAfter` | string | No | The last update date of the resource is after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedBefore` | string | No | The last update date of the resource is before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedFrom` | string | No | The last update date of the resource is on or after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedTo` | string | No | The last update date of the resource is on or before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `sort` | string | No | Sort order: up to 3 comma-separated fields, each with a leading "-" for descending (e.g. "-updatedAt,name"). Sortable fields: createdAt, updatedAt, invoiceDate, dueDate. Defaults to "-invoiceDate". Ties are broken by id, so the order is stable across pages, and a cursor is bound to the sort it was issued with. |
| `status` | string | No | Filter by status within the purchasing cycle: draft, validated or voided. `draft`, `validated`, `voided` |
| `statuses` | string[] | No | Filter by status, as a list: repeat the parameter or separate the values with commas. Accepts up to 50 values and returns whatever matches any of them. `draft`, `validated`, `voided` |
| `contactId` | string | No | Filter by identifier of the supplier contact that issued the invoice. |
| `contactIds` | string[] | No | Filter by contactId, as a list: repeat the parameter or separate the values with commas. Accepts up to 50 values and returns whatever matches any of them. |
| `orderId` | string | No | Filter by identifier of the sales order the invoice is linked to. |
| `orderIds` | string[] | No | Filter by orderId, as a list: repeat the parameter or separate the values with commas. Accepts up to 50 values and returns whatever matches any of them. |
| `projectId` | string | No | Filter by identifier of the project linked to the invoice, directly or through its order. |
| `projectIds` | string[] | No | Filter by projectId, as a list: repeat the parameter or separate the values with commas. Accepts up to 50 values and returns whatever matches any of them. |
| `invoiceDateOn` | string | No | The date the supplier put on the invoice falls on this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `invoiceDateAfter` | string | No | The date the supplier put on the invoice is after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `invoiceDateBefore` | string | No | The date the supplier put on the invoice is before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `invoiceDateFrom` | string | No | The date the supplier put on the invoice is on or after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `invoiceDateTo` | string | No | The date the supplier put on the invoice is on or before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `dueOn` | string | No | The supplier invoice due date falls on this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `dueAfter` | string | No | The supplier invoice due date is after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `dueBefore` | string | No | The supplier invoice due date is before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `dueFrom` | string | No | The supplier invoice due date is on or after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `dueTo` | string | No | The supplier invoice due date is on or before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `includeTotal` | boolean | No | Set it to true to include `pagination.total`, the number of results that match the filters across all pages. Off by default. = `false` |

## Request examples

*List supplier invoices*

**cURL**

```bash
curl https://app.filmo.io/api/v1/supplier-invoices \
  --header "Authorization: Bearer $FILMO_API_KEY"
```

**Node.js**

```javascript
fetch('https://app.filmo.io/api/v1/supplier-invoices', {
  headers: {
    Authorization: 'Bearer YOUR_FILMO_API_KEY'
  }
})
```

**Python**

```python
import requests

requests.get(
    "https://app.filmo.io/api/v1/supplier-invoices",
    headers={
      "Authorization": "Bearer YOUR_FILMO_API_KEY"
    }
)
```

## Response

Response schema: `SupplierInvoiceDto`

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 400 | Invalid request (validation_error): malformed query or body. `errors[]` lists every offending field with its stable code. |
| 401 | Authentication failed (unauthorized, api_key_invalid, api_key_revoked, api_key_expired, api_key_owner_inactive, api_key_owner_not_admin). |
| 402 | Add-on required (addon_required): the account plan does not include the add-on this operation needs; `requiredAddon` names it. |
| 403 | Not allowed (insufficient_scope: the API key does not have the required scope, named in `requiredScope`; forbidden: the owner of the key lacks the permission the operation requires). `insufficient_scope` is answered before the request counts against the rate limit, so it carries no `RateLimit-*` headers; `forbidden` does. |
| 429 | Rate limit exceeded (rate_limited): retry after `Retry-After` seconds; `RateLimit-*` says which quota ran out. |
| 500 | Internal error (internal_error). |

**200**

| Name | Type | Description |
| --- | --- | --- |
| `data` | object[] |  |
| `data.id` | string | Supplier invoice identifier. |
| `data.supplierInvoiceNumber` | string | Number the supplier put on the invoice; null if it was not recorded. |
| `data.status` | string | Status of the invoice within the purchasing cycle. |
| `data.createdAt` | string<date-time> | Creation date in ISO 8601 UTC. |
| `data.updatedAt` | string<date-time> | Last modification date in ISO 8601 UTC. |
| `pagination` | object | Opaque-cursor pagination metadata. |
| `pagination.nextCursor` | string | Opaque cursor of the next page; null when there are no more results. Pass it as `cursor` in the next request. |
| `pagination.hasMore` | boolean | Whether more results exist beyond this page. |
| `pagination.total` | integer | Number of results matching the filters across all pages. Present only when the request sets `includeTotal=true`. |
| `meta` | object | Additional information about the response. |
| `meta.warnings` | object[] | Lifecycle warnings; present only when the operation is deprecated. |
| `meta.warnings.code` | string | Stable warning code. `deprecated` |
| `meta.warnings.message` | string | For people: what is deprecated, until when, and what to use. |
| `meta.warnings.sunset` | string | Day (YYYY-MM-DD) the operation stops being served. |
| `meta.warnings.replacement` | string | `operationId` of the operation to use instead, or null if there is none. |
| `meta.warnings.link` | string | Where the deprecation is documented (the changelog). |

*Example response · 200*

```json
{
  "data": [
    {
      "id": "supplier_invoice_9f3a2b",
      "supplierInvoiceNumber": "2026-0001",
      "status": "Example status",
      "createdAt": "2026-09-01T08:00:00.000Z",
      "updatedAt": "2026-09-01T08:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJvIjoyMH0",
    "hasMore": true,
    "total": 1
  }
}
```

## Errors

| Status | Codes | Meaning |
| --- | --- | --- |
| 400 | `validation_error` | Malformed query or body. `errors[]` lists every offending field with its stable code. |
| 402 | `addon_required` | The account plan does not include the add-on this operation needs; `requiredAddon` names it. |

## Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date.

---

Canonical URL: https://docs.filmo.io/rest-api/endpoint-reference/supplier-invoices/list-supplier-invoices  
Last updated: 2026-10-25