> For the complete documentation index, see [llms.txt](https://teamleader-sdk.mcore-services.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://teamleader-sdk.mcore-services.dev/api-reference/invoicing/credit-notes.md).

# Credit Notes

Manage credit notes in Teamleader Focus.

```php
Teamleader::creditNotes()
```

|                          |                                                                       |
| ------------------------ | --------------------------------------------------------------------- |
| Class                    | `McoreServices\TeamleaderSDK\Resources\Invoicing\Creditnotes`         |
| Also available as        | `creditnotes()`                                                       |
| Create / update / delete | — / — / —                                                             |
| Pagination               | `page_size` / `page_number`; no totals — a short page is the last one |

## Endpoints

* `creditNotes.download`
* `creditNotes.info`
* `creditNotes.list`
* `creditNotes.sendViaPeppol`

## Filters

Passed as the first argument to `list()`. Any other key throws.

| Filter                    | Description                           |
| ------------------------- | ------------------------------------- |
| `credit_note_date_after`  | Date (inclusive, YYYY-MM-DD)          |
| `credit_note_date_before` | Date (exclusive, YYYY-MM-DD)          |
| `customer`                | Customer object with type and id      |
| `department_id`           | Filter on department (company entity) |
| `ids`                     | Array of credit note UUIDs            |
| `invoice_id`              | Filter on invoice UUID                |
| `project_id`              | Filter on project UUID                |
| `updated_since`           | ISO 8601 datetime                     |

## Methods

### `list()`

```php
list(array $filters = [], array $options = []): array
```

List credit notes with filtering and pagination

* `$filters` — Filter parameters
* `$options` — Pagination options

### `info()`

```php
info($id, $includes = null): array
```

Get detailed information about a specific credit note

Response includes:

* id, department, credit\_note\_number, credit\_note\_date, status
* invoice (object|null): related invoice {id, type}
* paid (bool), paid\_at (string|null)
* invoicee: name, vat\_number, customer {email, national\_identification\_number}
* discounts, total, taxes, grouped\_lines
* currency, currency\_exchange\_rate
* created\_at, updated\_at
* document\_template: {id, type}
* peppol\_status (string|null): Peppol submission status, populated after sendViaPeppol()
* `$id` — Credit note UUID
* `$includes` — Optional includes (not used for credit notes)

### `download()`

```php
download(string $id, string $format = 'pdf'): array
```

Download a credit note in a specific format

* `$id` — Credit note UUID
* `$format` — Format (pdf, ubl/e-fff)

### `sendViaPeppol()`

```php
sendViaPeppol(string $id): array
```

Send a credit note via the Peppol network

After calling this method, use info() to poll peppol\_status until it transitions from 'sending' to a final state (e.g. 'sent', 'sending\_failed').

* `$id` — Credit note UUID

### `booked()`

```php
booked(array $additionalFilters = [], array $options = []): array
```

Get booked credit notes (convenience method)

* `$additionalFilters` — Additional filters to apply
* `$options` — Pagination options

### `paid()`

> **Deprecated** since v2.2.7 — creditNotes.list has no paid filter. This method set an internal `_paid` flag that buildFilters() then stripped, so it returned every credit note, paid or not. Filter client-side on `data[].paid`. Removed in v3.0.

```php
paid(array $additionalFilters = [], array $options = []): array
```

Get paid credit notes

**Throws** `InvalidArgumentException` Always

### `unpaid()`

> **Deprecated** since v2.2.7 — see paid(). Removed in v3.0.

```php
unpaid(array $additionalFilters = [], array $options = []): array
```

Get unpaid credit notes

**Throws** `InvalidArgumentException` Always

### `forInvoice()`

```php
forInvoice(string $invoiceId, array $additionalFilters = [], array $options = []): array
```

Get credit notes for a specific invoice

* `$invoiceId` — Invoice UUID
* `$additionalFilters` — Additional filters to apply
* `$options` — Pagination options

### `forCustomer()`

```php
forCustomer(string $customerType, string $customerId, array $additionalFilters = [], array $options = []): array
```

Get credit notes for a specific customer

* `$customerType` — Customer type (contact or company)
* `$customerId` — Customer UUID
* `$additionalFilters` — Additional filters to apply
* `$options` — Pagination options

### `forProject()`

```php
forProject(string $projectId, array $additionalFilters = [], array $options = []): array
```

Get credit notes for a specific project

* `$projectId` — Project UUID
* `$additionalFilters` — Additional filters to apply
* `$options` — Pagination options

### `forDepartment()`

```php
forDepartment(string $departmentId, array $additionalFilters = [], array $options = []): array
```

Get credit notes for a specific department

* `$departmentId` — Department UUID
* `$additionalFilters` — Additional filters to apply
* `$options` — Pagination options

### `betweenDates()`

```php
betweenDates(string $dateAfter, string $dateBefore, array $additionalFilters = [], array $options = []): array
```

Get credit notes between specific dates

* `$dateAfter` — Start date (inclusive, YYYY-MM-DD)
* `$dateBefore` — End date (exclusive, YYYY-MM-DD)
* `$additionalFilters` — Additional filters to apply
* `$options` — Pagination options

### `updatedSince()`

```php
updatedSince(string $since, array $additionalFilters = [], array $options = []): array
```

Get credit notes created/updated since a specific date

* `$since` — ISO 8601 datetime
* `$additionalFilters` — Additional filters to apply
* `$options` — Pagination options

### `getResponseStructure()`

```php
getResponseStructure(): array
```

Get response structure documentation

## Examples

Get all credit notes:

```php
$creditNotes = Teamleader::creditNotes()->list();
```

Get credit notes for a specific invoice:

```php
$creditNotes = Teamleader::creditNotes()->forInvoice('invoice-uuid');
```

Get credit notes for a specific customer:

```php
$creditNotes = Teamleader::creditNotes()->forCustomer('company', 'customer-uuid');
```

Get credit notes for a specific project:

```php
$creditNotes = Teamleader::creditNotes()->forProject('project-uuid');
```

Get credit notes within a date range:

```php
$creditNotes = Teamleader::creditNotes()->betweenDates('2022-01-01', '2023-01-01');
```

Get detailed credit note information:

```php
$creditNote = Teamleader::creditNotes()->info('credit-note-uuid');
```

Download credit note as PDF:

```php
$download = Teamleader::creditNotes()->download('credit-note-uuid', 'pdf');
```

Download credit note as UBL e-fff format:

```php
$download = Teamleader::creditNotes()->download('credit-note-uuid', 'ubl/e-fff');
```

Send credit note via Peppol network:

```php
$result = Teamleader::creditNotes()->sendViaPeppol('credit-note-uuid');
```

Send via Peppol and check submission status:

```php
Teamleader::creditNotes()->sendViaPeppol('credit-note-uuid');

// Poll info() until peppol_status is no longer 'sending'
$creditNote = Teamleader::creditNotes()->info('credit-note-uuid');
$peppolStatus = $creditNote['data']['peppol_status'] ?? null;
// e.g. 'sent', 'sending_failed', 'receiver_accepted', etc.
```

Get only booked credit notes:

```php
$creditNotes = Teamleader::creditNotes()->booked();
```

Get unpaid credit notes (client-side — creditNotes.list has no paid filter):

```php
$unpaid = array_filter(Teamleader::creditNotes()->list()['data'], fn ($note) => $note['paid'] === false);
```