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

# Orders

Retrieve and view orders in Teamleader Focus.

```php
Teamleader::orders()
```

|                          |                                                                       |
| ------------------------ | --------------------------------------------------------------------- |
| Class                    | `McoreServices\TeamleaderSDK\Resources\Deals\Orders`                  |
| Create / update / delete | — / — / —                                                             |
| Pagination               | `page_size` / `page_number`; no totals — a short page is the last one |

## Endpoints

* `orders.info`
* `orders.list`

## Filters

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

| Filter | Description                       |
| ------ | --------------------------------- |
| `ids`  | Array of order UUIDs to filter by |

## Includes

`list()` and `info()` accept the same includes:

`custom_fields`

## Methods

### `list()`

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

List orders with optional filtering and pagination

Passing neither page option sends no `page` key and returns the API default of 20 records. all() walks every page.

Filtering is `ids` only. The API accepts any other filter key, ignores it, and answers 200 with the full unfiltered first page — `department_id`, `updated_since`, `order_date_after`, `term` and `status` were each confirmed to have no effect. Unknown keys therefore throw rather than being sent; see buildFilters().

Sorting is not supported. A sort passed here is rejected, because the API accepts one and discards it — sorting by `order_date` returns the same first record as no sort at all.

* `$filters` — Filters to apply — `ids` only
* `$options` — page\_size, page\_number, include

**Throws** `InvalidArgumentException` When a sort or an unknown filter key is passed

### `info()`

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

Get order information

* `$id` — Order UUID
* `$includes` — Includes to load (e.g., 'custom\_fields')

### `byIds()`

```php
byIds(array $ids): array
```

Get orders by specific IDs

* `$ids` — Array of order UUIDs

### `all()`

```php
all(array $filters = [], array $options = [], int $maxPages = 100): array
```

Retrieve every order, walking the endpoint's pages

orders.list returns no total count, so the end of the list is inferred from a page shorter than the one requested — which means a complete final page costs one extra empty request, and the number of requests a full pass needs cannot be known in advance.

$maxPages is a runaway guard, not a limit: reaching it with a full page still coming throws, rather than returning a partial set that looks complete. Silently returning 10,000 of 11,000 orders is the failure this method exists to prevent, so it is not repeated here.

The signature differs from PaymentMethods::all() and TaxRates::all(), which take (array $filters, int $maxPages). $options sits in the middle because custom\_fields is worth sideloading during a full pass, and because applyPendingIncludes() consumes the fluent state after the first request — so with('custom\_fields')->all() would otherwise sideload page 1 and nothing after it. The sideload is resolved once here and replayed on every page.

* `$filters` — Filters to apply — `ids` only
* `$options` — include (applied to every page)
* `$maxPages` — Safety cap — 100 pages of 100 is 10,000 orders

**Throws** `TeamleaderException` When $maxPages is reached with records still pending

### `getResponseStructure()`

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

Get response structure documentation

### `getPaymentTermTypes()`

```php
getPaymentTermTypes(): array
```

Get payment term types

### `getSupplierTypes()`

```php
getSupplierTypes(): array
```

Get supplier types

## Examples

Get the first page of orders (20 records — the API default):

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

Get orders with an explicit page size and number:

```php
$orders = Teamleader::orders()->list([], ['page_size' => 100, 'page_number' => 1]);
```

Get every order in the account, walking all pages:

```php
$orders = Teamleader::orders()->all();
```

Get specific orders by ID:

```php
$orders = Teamleader::orders()->list(['ids' => ['uuid1', 'uuid2']]);
```

Get a single order with custom fields:

```php
$order = Teamleader::orders()->with('custom_fields')->info('order-uuid');
```

Get orders by IDs using convenience method:

```php
$orders = Teamleader::orders()->byIds(['uuid1', 'uuid2']);
```