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

# Subscriptions

Manage subscriptions in Teamleader Focus.

```php
Teamleader::subscriptions()
```

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

## Endpoints

* `subscriptions.create`
* `subscriptions.deactivate`
* `subscriptions.info`
* `subscriptions.list`
* `subscriptions.update`

## Filters

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

| Filter          | Description                                                       |
| --------------- | ----------------------------------------------------------------- |
| `customer`      | Customer object: \["type" => "contact"\|"company", "id" => "..."] |
| `deal_id`       | Filter on subscriptions created from a deal                       |
| `department_id` | Filter on subscriptions of a specific department                  |
| `ids`           | Array of subscription UUIDs                                       |
| `invoice_id`    | Find subscriptions that generated the given invoice               |
| `status`        | Array of statuses (active, deactivated)                           |

## Sorting

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

| Field        | Description        |
| ------------ | ------------------ |
| `created_at` | Creation date      |
| `status`     | Status             |
| `title`      | Subscription title |

## Accepted values

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

| Constant                  | Values                                                                                                                                                                                                                                                                             |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DAYS_IN_ADVANCE`         | `0`, `7`, `14`, `21`, `28`                                                                                                                                                                                                                                                         |
| `DELIVERY_TYPES`          | `set_days_after_invoice_date`                                                                                                                                                                                                                                                      |
| `INVOICE_CONTENT`         | `goods`, `services`, `goods_and_services`                                                                                                                                                                                                                                          |
| `INVOICE_PAYMENT_METHODS` | `direct_debit`                                                                                                                                                                                                                                                                     |
| `REQUIRED_ON_CREATE`      | `invoicee`, `department_id`, `starts_on`, `billing_cycle`, `title`, `grouped_lines`, `payment_term`, `invoice_generation`                                                                                                                                                          |
| `WRITE_FIELDS`            | `invoicee`, `department_id`, `deal_id`, `project_id`, `purchase_order_number`, `title`, `note`, `starts_on`, `ends_on`, `billing_cycle`, `payment_term`, `grouped_lines`, `invoice_generation`, `custom_fields`, `document_template_id`, `invoice_content`, `delivery_information` |

## Methods

### `info()`

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

Get detailed information about a subscription

Response includes:

* id, title, note (nullable), status, department, invoicee, project (nullable)
* starts\_on, ends\_on (nullable), next\_renewal\_date (nullable)
* billing\_cycle (periodicity, days\_in\_advance, payment\_term)
* total (tax\_exclusive, tax\_inclusive, taxes)
* grouped\_lines, invoice\_generation (action, sending\_methods, payment\_method)
* custom\_fields, document\_template, currency
* web\_url
* created\_at (string|null): ISO 8601 creation timestamp
* purchase\_order\_number (string|null): PO number on the subscription
* delivery\_information (object|null): Delivery details (name, address, etc.)

### `create()`

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

Create a new subscription

Required fields:

* invoicee (object): customer {type, id}, optional for\_attention\_of
* department\_id (string): department UUID
* starts\_on (string): YYYY-MM-DD
* billing\_cycle (object): periodicity {unit, period}, days\_in\_advance
* title (string)
* grouped\_lines (array): sections with line\_items
* payment\_term (object): type (cash|end\_of\_month|after\_invoice\_date), days
* invoice\_generation (object): action (draft|book|book\_and\_send)
  * sending\_methods: required when action is 'book\_and\_send'
    * method: email|peppol|postal\_service

Optional fields:

* ends\_on (string|null): YYYY-MM-DD
* deal\_id (string|null)
* project\_id (string|null)
* note (string|null)
* payment\_method: direct\_debit
* custom\_fields (array)
* document\_template\_id (string)
* purchase\_order\_number (string|null): PO number to include on generated invoices
* delivery\_information (object|null): Delivery details passed to generated invoices

Returns HTTP 201 with data.{id, type}

### `update()`

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

Update an existing subscription

All fields except id are optional. Note:

* starts\_on and billing\_cycle can only be updated if no invoices have been generated yet

Updatable fields:

* starts\_on (string): YYYY-MM-DD (only if no invoices created yet)
* billing\_cycle (object): only if no invoices created yet
* ends\_on (string|null): YYYY-MM-DD
* title (string)
* invoicee (object)
* department\_id (string)
* payment\_term (object|null)
* project\_id (string|null)
* deal\_id (string|null)
* note (string|null)
* grouped\_lines (array)
* invoice\_generation (object): action (draft|book|book\_and\_send)
  * sending\_methods: required when action is 'book\_and\_send'
    * method: email|peppol|postal\_service
* payment\_method: direct\_debit
* custom\_fields (array)
* document\_template\_id (string)
* purchase\_order\_number (string|null): PO number to include on generated invoices
* delivery\_information (object|null): Delivery details passed to generated invoices

Returns HTTP 204 (no body)

### `deactivate()`

```php
deactivate($id): array
```

Deactivate a subscription

### `active()`

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

Get active subscriptions

### `list()`

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

List subscriptions with filtering, sorting, and pagination

Response includes per item:

* id, title, note, status, department, invoicee, project
* starts\_on, ends\_on (nullable), next\_renewal\_date (nullable)
* billing\_cycle, total, taxes, web\_url
* created\_at (string|null): ISO 8601 creation timestamp
* purchase\_order\_number (string|null): PO number on the subscription
* delivery\_information (object|null): Delivery details (name, address, etc.)

### `deactivated()`

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

Get deactivated subscriptions

### `forCustomer()`

```php
forCustomer(string $type, string $id, array $options = []): array
```

Get subscriptions for a specific customer

### `forDepartment()`

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

Get subscriptions for a specific department

### `forDeal()`

```php
forDeal(string $dealId, array $options = []): array
```

Get subscriptions for a specific deal

### `forInvoice()`

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

Get subscriptions that generated a specific invoice

### `byIds()`

```php
byIds(array $ids, array $options = []): array
```

Get subscriptions by specific IDs

### `getResponseStructure()`

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

Get response structure documentation

## Examples

Get all subscriptions:

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

Get active subscriptions:

```php
$subscriptions = Teamleader::subscriptions()->active();
```

Get subscriptions for a specific customer:

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

Get subscriptions for a specific department:

```php
$subscriptions = Teamleader::subscriptions()->forDepartment('department-uuid');
```

Create a new subscription:

```php
$subscription = Teamleader::subscriptions()->create([...]);
```

Create a subscription that sends invoices via Peppol:

```php
$subscription = Teamleader::subscriptions()->create([
    'invoicee' => [
        'customer' => ['type' => 'company', 'id' => 'company-uuid'],
    ],
    'department_id' => 'dept-uuid',
    'starts_on' => '2024-01-01',
    'billing_cycle' => [
        'periodicity' => ['unit' => 'month', 'period' => 1],
        'days_in_advance' => 7,
    ],
    'title' => 'Monthly support',
    'grouped_lines' => [[
        'section' => ['title' => 'Support'],
        'line_items' => [[
            'quantity' => 1,
            'description' => 'Monthly support fee',
            'unit_price' => ['amount' => 500.00, 'tax' => 'excluding'],
            'tax_rate_id' => 'tax-rate-uuid',
        ]],
    ]],
    'payment_term' => ['type' => 'cash'],
    'invoice_generation' => [
        'action' => 'book_and_send',
        'sending_methods' => [
            ['method' => 'peppol'],
        ],
    ],
]);
```

Update an existing subscription:

```php
$subscription = Teamleader::subscriptions()->update('subscription-uuid', [...]);
```

Deactivate a subscription:

```php
$result = Teamleader::subscriptions()->deactivate('subscription-uuid');
```

Get detailed information about a subscription:

```php
$subscription = Teamleader::subscriptions()->info('subscription-uuid');
```