> 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/expenses/expenses.md).

# Expenses

Manage expenses in Teamleader Focus.

```php
Teamleader::expenses()
```

|                          |                                                                       |
| ------------------------ | --------------------------------------------------------------------- |
| Class                    | `McoreServices\TeamleaderSDK\Resources\Expenses\Expenses`             |
| Create / update / delete | — / — / —                                                             |
| Pagination               | `page_size` / `page_number`; the response includes `meta` with totals |

## Endpoints

* `expenses.list`

## Filters

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

| Filter                 | Description                                                                       |
| ---------------------- | --------------------------------------------------------------------------------- |
| `bookkeeping_statuses` | Filter by bookkeeping status(es): sent, not\_sent                                 |
| `department_ids`       | Filter by one or more department UUIDs                                            |
| `document_date`        | Filter by document date with operators: is\_empty, between, equals, before, after |
| `paid_at`              | Filter by payment date with operators: is\_empty, between, equals, before, after  |
| `payment_statuses`     | Filter by payment status(es): unknown, paid, partially\_paid, credited, not\_paid |
| `review_statuses`      | Filter by review status(es): pending, approved, refused                           |
| `source_types`         | Filter by expense source type(s): incomingInvoice, incomingCreditNote, receipt    |
| `supplier`             | Filter by a specific supplier (object with type and id)                           |
| `term`                 | Search by document number, title and supplier name (case-insensitive)             |

## Sorting

Pass `sort` (and optionally `sort_order`) in the options. Any other field throws.

| Field           | Description   |
| --------------- | ------------- |
| `document_date` | Document date |
| `due_date`      | Due date      |
| `supplier_name` | Supplier name |

## Accepted values

Public constants on the class. Body fields and enum values outside these lists throw before the request is sent.

| Constant               | Values                                                      |
| ---------------------- | ----------------------------------------------------------- |
| `BOOKKEEPING_STATUSES` | `sent`, `not_sent`                                          |
| `DATE_OPERATORS`       | `is_empty`, `between`, `equals`, `before`, `after`          |
| `PAYMENT_STATUSES`     | `unknown`, `paid`, `partially_paid`, `credited`, `not_paid` |
| `REVIEW_STATUSES`      | `pending`, `approved`, `refused`                            |
| `SOURCE_TYPES`         | `incomingInvoice`, `incomingCreditNote`, `receipt`          |
| `SUPPLIER_TYPES`       | `company`, `contact`                                        |

## Methods

### `list()`

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

List expenses with filtering, sorting, and pagination

* `$filters` — Filters to apply
* `$options` — Additional options (pagination, sort)

### `pending()`

```php
pending(): array
```

Get expenses with pending review status

### `approved()`

```php
approved(): array
```

Get expenses with approved review status

### `refused()`

```php
refused(): array
```

Get expenses with refused review status

### `paid()`

```php
paid(): array
```

Get expenses with paid payment status

### `unpaid()`

```php
unpaid(): array
```

Get expenses not (fully) paid: not\_paid and partially\_paid

Before v2.2.8 this sent `unpaid`, which is not a payment status the API knows.

### `bySourceType()`

```php
bySourceType($sourceTypes, array $additionalFilters = []): array
```

Get expenses by source type

* `$sourceTypes` — Source type(s): incomingInvoice, incomingCreditNote, receipt
* `$additionalFilters` — Additional filters to apply

### `bySupplier()`

```php
bySupplier(string $type, string $id, array $additionalFilters = []): array
```

Get expenses for a specific supplier

* `$type` — Supplier type: company or contact
* `$id` — Supplier UUID
* `$additionalFilters` — Additional filters to apply

### `byDepartment()`

```php
byDepartment($departmentIds, array $additionalFilters = []): array
```

Get expenses for one or more departments

* `$departmentIds` — Department UUID or array of UUIDs
* `$additionalFilters` — Additional filters to apply

### `searchByTerm()`

```php
searchByTerm(string $term, array $additionalFilters = []): array
```

Search expenses by term (document number or supplier name)

* `$term` — Search term (case-insensitive)
* `$additionalFilters` — Additional filters to apply

### `byDateRange()`

```php
byDateRange(string $startDate, string $endDate, array $additionalFilters = []): array
```

Get expenses within a document date range

* `$startDate` — Start date (ISO format: YYYY-MM-DD)
* `$endDate` — End date (ISO format: YYYY-MM-DD)
* `$additionalFilters` — Additional filters to apply

### `byPaidAtRange()`

```php
byPaidAtRange(string $startDate, string $endDate, array $additionalFilters = []): array
```

Get expenses paid within a date range

* `$startDate` — Start date (ISO format: YYYY-MM-DD)
* `$endDate` — End date (ISO format: YYYY-MM-DD)
* `$additionalFilters` — Additional filters to apply

### `sent()`

```php
sent(): array
```

Get expenses sent to bookkeeping

### `notSent()`

```php
notSent(): array
```

Get expenses not sent to bookkeeping

### `getValidPaymentStatuses()`

```php
getValidPaymentStatuses(): array
```

Get valid payment statuses for expenses

### `getValidSortFields()`

```php
getValidSortFields(): array
```

Get valid sort fields for expenses

## Examples

Get all expenses:

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

Get pending expenses:

```php
$expenses = Teamleader::expenses()->pending();
```

Get approved expenses:

```php
$expenses = Teamleader::expenses()->approved();
```

Get unpaid expenses:

```php
$expenses = Teamleader::expenses()->unpaid();
```

Search expenses by document number or supplier name:

```php
$expenses = Teamleader::expenses()->searchByTerm("Office Supplies Inc");
```

Get incoming invoices only:

```php
$expenses = Teamleader::expenses()->bySourceType("incomingInvoice");
```

Get expenses from a specific supplier:

```php
$expenses = Teamleader::expenses()->bySupplier("company", "company-uuid");
```

Get expenses for a specific department:

```php
$expenses = Teamleader::expenses()->byDepartment("department-uuid");
```

Get expenses within document date range:

```php
$expenses = Teamleader::expenses()->byDateRange("2024-01-01", "2024-12-31");
```

Get expenses paid within a date range:

```php
$expenses = Teamleader::expenses()->byPaidAtRange("2024-01-01", "2024-12-31");
```

Get expenses not sent to bookkeeping:

```php
$expenses = Teamleader::expenses()->notSent();
```

Get expenses sorted by document date descending:

```php
$expenses = Teamleader::expenses()->list([], ["sort" => "document_date", "sort_order" => "desc"]);
```