*REST API › Endpoint 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.

`GET /api/v1/credit-notes` — scope `invoices:read`

Scope: `invoices:read` · 120/min · MCP: `filmo_credit_notes_list`

## Authorizations

Bearer API key with the scope below. `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, 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. |
| `issueDateOn` | string | No | The credit note issue date falls on this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `issueDateAfter` | string | No | The credit note issue date is after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `issueDateBefore` | string | No | The credit note issue date is before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `issueDateFrom` | string | No | The credit note issue 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. |
| `issueDateTo` | string | No | The credit note issue 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 credit notes*

**cURL**

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

**Node.js**

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

**Python**

```python
import requests

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

## Response

Response schema: `CreditNoteDto`

| 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). |
| 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 | Credit note identifier. |
| `data.creditNoteNumber` | string | Credit note number; null while it is a draft. |
| `data.status` | string | Document lifecycle status: draft, validated or voided (the same values the `status` filter takes). `draft`, `validated`, `voided` |
| `data.issueDate` | string<date-time> | Issue date in ISO 8601 UTC; null if not recorded. |
| `data.currency` | string | Currency, as an ISO 4217 code. |
| `data.contactId` | string | Contact the credit note is issued to; null if not recorded. |
| `data.invoiceId` | string | Invoice this credit note rectifies; null if it is not attached to any. |
| `data.subTotal` | string | Subtotal before discounts and taxes, as a decimal string. |
| `data.taxesPrice` | string | Tax total, as a decimal string. |
| `data.netPrice` | string | Taxable base, as a decimal string. |
| `data.grossPrice` | string | Total including taxes, as a decimal string. |
| `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": "credit_note_9f3a2b",
      "creditNoteNumber": "2026-0001",
      "status": "draft",
      "issueDate": "2026-09-01T08:00:00.000Z",
      "currency": "EUR",
      "contactId": "contact_9f3a2b",
      "invoiceId": "invoice_9f3a2b",
      "subTotal": "120.00",
      "taxesPrice": "120.00",
      "netPrice": "120.00",
      "grossPrice": "120.00",
      "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. |

## 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/credit-notes/list-credit-notes  
Last updated: 2026-10-25