*MCP › Reference › Finance › Credit notes*

# List credit notes

> Returns the credit notes issued to customers, cursor-paginated: what is refunded and against which invoice.

Filter by lifecycle status, contact, source order, project, rectified invoice and issue date. The signed tax document, the tax breakdown, the lines and the reason for the correction are not published. Sorted by issue date, most recent first.

TOOL `filmo_credit_notes_list` · `invoices:read` · 120/min · Server annotation: Read-only · Server annotation: Idempotent

## Arguments

| 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. |
| `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, issueDate, grossPrice. Defaults to "-issueDate". 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 document lifecycle status: 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 contact the credit note is issued to. |
| `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 source order of the credit note. |
| `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 credit note. |
| `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. |
| `invoiceId` | string | No | Filter by identifier of the invoice the credit note rectifies. |
| `invoiceIds` | string[] | No | Filter by invoiceId, as a list: repeat the parameter or separate the values with commas. Accepts up to 50 values and returns whatever matches any of them. |
| `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` |
| `dateFilters` | object | No | Date filters by field. A bare day (YYYY-MM-DD) is read in the business timezone; an ISO 8601 instant with offset is applied as is by gte, lte, gt and lt, while on widens it to the whole business day that contains it. Fields: created, issueDate, updated. |
| `dateFilters.created` | object | No |  |
| `dateFilters.created.gte` | string | No | From this day or instant, inclusive. |
| `dateFilters.created.lte` | string | No | Up to this day or instant, inclusive. |
| `dateFilters.created.gt` | string | No | Strictly after; a bare day means after the end of that day. |
| `dateFilters.created.lt` | string | No | Strictly before; a bare day means before the start of that day. |
| `dateFilters.created.on` | string | No | Exactly that day; an instant means the whole business day that contains it. |
| `dateFilters.issueDate` | object | No |  |
| `dateFilters.issueDate.gte` | string | No | From this day or instant, inclusive. |
| `dateFilters.issueDate.lte` | string | No | Up to this day or instant, inclusive. |
| `dateFilters.issueDate.gt` | string | No | Strictly after; a bare day means after the end of that day. |
| `dateFilters.issueDate.lt` | string | No | Strictly before; a bare day means before the start of that day. |
| `dateFilters.issueDate.on` | string | No | Exactly that day; an instant means the whole business day that contains it. |
| `dateFilters.updated` | object | No |  |
| `dateFilters.updated.gte` | string | No | From this day or instant, inclusive. |
| `dateFilters.updated.lte` | string | No | Up to this day or instant, inclusive. |
| `dateFilters.updated.gt` | string | No | Strictly after; a bare day means after the end of that day. |
| `dateFilters.updated.lt` | string | No | Strictly before; a bare day means before the start of that day. |
| `dateFilters.updated.on` | string | No | Exactly that day; an instant means the whole business day that contains it. |

## Result

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

| Name | Type | Description |
| --- | --- | --- |
| `id` | string | Credit note identifier. |
| `creditNoteNumber` | string | Credit note number; null while it is a draft. |
| `status` | string | Document lifecycle status: draft, validated or voided (the same values the `status` filter takes). `draft`, `validated`, `voided` |
| `issueDate` | string<date-time> | Issue date in ISO 8601 UTC; null if not recorded. |
| `currency` | string | Currency, as an ISO 4217 code. |
| `contactId` | string | Contact the credit note is issued to; null if not recorded. |
| `invoiceId` | string | Invoice this credit note rectifies; null if it is not attached to any. |
| `subTotal` | string | Subtotal before discounts and taxes, as a decimal string. |
| `taxesPrice` | string | Tax total, as a decimal string. |
| `netPrice` | string | Taxable base, as a decimal string. |
| `grossPrice` | string | Total including taxes, as a decimal string. |
| `createdAt` | string<date-time> | Creation date in ISO 8601 UTC. |
| `updatedAt` | string<date-time> | Last modification date in ISO 8601 UTC. |

*Call · filmo_credit_notes_list*

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_credit_notes_list",
    "arguments": {
      "limit": 20
    }
  }
}
```

*Result (generated from the schema)*

```json
{
  "structuredContent": {
    "data": [
      {
        "id": "id_8f2a1c",
        "creditNoteNumber": "<creditNoteNumber>",
        "status": "draft",
        "issueDate": "2026-09-01T08:00:00Z",
        "currency": "EUR",
        "contactId": "cont_8f2a1c",
        "invoiceId": "invo_8f2a1c",
        "subTotal": "1234.50",
        "taxesPrice": "1234.50",
        "netPrice": "1234.50",
        "grossPrice": "1234.50",
        "createdAt": "2026-09-01T08:00:00Z",
        "updatedAt": "2026-09-01T08:00:00Z"
      }
    ],
    "pagination": {
      "nextCursor": "eyJvIjo1MH0",
      "hasMore": true,
      "total": 1
    },
    "meta": {
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "reset": 42
      }
    }
  }
}
```

## The same operation by REST

This tool runs [`GET /api/v1/credit-notes`](https://docs.filmo.io/rest-api/endpoint-reference/credit-notes/list-credit-notes).

---

Canonical URL: https://docs.filmo.io/mcp/tools/credit-notes/filmo-credit-notes-list  
Last updated: 2026-10-25