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

# Deal Phases

Manage deal phases in Teamleader Focus.

```php
Teamleader::dealPhases()
```

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

## Endpoints

* `dealPhases.create`
* `dealPhases.delete`
* `dealPhases.duplicate`
* `dealPhases.list`
* `dealPhases.move`
* `dealPhases.update`

## Filters

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

| Filter             | Description                             |
| ------------------ | --------------------------------------- |
| `deal_pipeline_id` | Filter phases by specific pipeline UUID |
| `ids`              | Array of deal phase UUIDs to filter by  |

## Accepted values

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

| Constant            | Values                                                                                               |
| ------------------- | ---------------------------------------------------------------------------------------------------- |
| `ATTENTION_UNITS`   | `days`, `weeks`                                                                                      |
| `CREATE_FIELDS`     | `name`, `deal_pipeline_id`, `estimated_probability`, `follow_up_actions`, `requires_attention_after` |
| `FOLLOW_UP_ACTIONS` | `create_event`, `create_call`, `create_task`                                                         |
| `UPDATE_FIELDS`     | `id`, `name`, `estimated_probability`, `follow_up_actions`, `requires_attention_after`               |

## Methods

### `list()`

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

List deal phases with enhanced filtering and pagination

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

### `create()`

```php
create(array $data): array
```

Create a new deal phase

dealPhases.create requires name, deal\_pipeline\_id and requires\_attention\_after.

* `$data` — Phase data

**Throws** `InvalidArgumentException`

### `update()`

```php
update($id, array $data): array
```

Update a deal phase

dealPhases.update requires requires\_attention\_after on every call, not only when it changes. Before v2.2.5 the SDK treated it as optional, so an update without it passed client-side and was rejected by the API.

* `$id` — Phase UUID
* `$data` — Update data

**Throws** `InvalidArgumentException`

### `delete()`

```php
delete($id, ...$additionalParams): array
```

Delete a deal phase, moving its deals to another phase

`new_phase_id` is optional in the specification. Before v2.2.5 this method required it and then called parent::delete(), which does not exist — so every call was a fatal "Call to undefined method", and dealPhases.delete could not be reached at all. The same defect was fixed on Pipelines in v2.2.2.

* `$id` — Phase UUID to delete
* `$additionalParams` — Optional UUID of the phase that takes over the deals

### `duplicate()`

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

Duplicate an existing deal phase

* `$id` — Source phase UUID

### `move()`

```php
move(string $id, string $afterPhaseId): array
```

Move a phase to a new position in the pipeline

* `$id` — Phase UUID to move
* `$afterPhaseId` — Phase UUID to place this phase after

### `forPipeline()`

```php
forPipeline(string $pipelineId): array
```

Get phases for a specific pipeline

* `$pipelineId` — Pipeline UUID

### `byIds()`

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

Get phases by specific IDs

* `$ids` — Array of phase UUIDs

### `getAvailableFollowUpActions()`

```php
getAvailableFollowUpActions(): array
```

Get available follow-up actions

### `getAvailableAttentionAfterUnits()`

```php
getAvailableAttentionAfterUnits(): array
```

Get available attention after units

## Examples

Get all phases across all pipelines:

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

Get phases for specific pipeline:

```php
$phases = Teamleader::dealPhases()->list(['deal_pipeline_id' => 'pipeline-uuid']);
```

Delete a phase, moving its deals to another phase:

```php
Teamleader::dealPhases()->delete('phase-uuid', 'new-phase-uuid');
```

Create a new phase:

```php
$phase = Teamleader::dealPhases()->create(['name' => 'New Phase', 'deal_pipeline_id' => 'uuid', 'requires_attention_after' => ['amount' => 7, 'unit' => 'days']]);
```

Duplicate an existing phase:

```php
$newPhase = Teamleader::dealPhases()->duplicate('source-phase-uuid');
```

Move phase to new position:

```php
Teamleader::dealPhases()->move('phase-uuid', 'after-phase-uuid');
```