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

# Receipts

Manage expense receipts in Teamleader Focus.

```php
Teamleader::receipts()
```

|                          |                                                           |
| ------------------------ | --------------------------------------------------------- |
| Class                    | `McoreServices\TeamleaderSDK\Resources\Expenses\Receipts` |
| Create / update / delete | ✓ / ✓ / ✓                                                 |
| Pagination               | No                                                        |

## Endpoints

* `receipts.add`
* `receipts.approve`
* `receipts.delete`
* `receipts.info`
* `receipts.listPayments`
* `receipts.markAsPendingReview`
* `receipts.refuse`
* `receipts.registerPayment`
* `receipts.removePayment`
* `receipts.sendToBookkeeping`
* `receipts.update`
* `receipts.updatePayment`

## Filters

`list()` takes no filters.

## Accepted values

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

| Constant                  | Values                                                                                                                                                          |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CURRENCIES`              | `BAM`, `CAD`, `CHF`, `CLP`, `CNY`, `COP`, `CZK`, `DKK`, `EUR`, `GBP`, `INR`, `ISK`, `JPY`, `MAD`, `MXN`, `NOK`, `PEN`, `PLN`, `RON`, `SEK`, `TRY`, `USD`, `ZAR` |
| `PAYMENT_STATUSES`        | `unknown`, `paid`, `not_paid`                                                                                                                                   |
| `REGISTER_PAYMENT_FIELDS` | `payment`, `paid_at`, `payment_method_id`, `remark`                                                                                                             |
| `REVIEW_STATUSES`         | `pending`, `approved`, `refused`                                                                                                                                |
| `TOTAL_KEYS`              | `tax_inclusive`                                                                                                                                                 |
| `UPDATE_PAYMENT_FIELDS`   | `payment_id`, `payment`, `paid_at`, `payment_method_id`, `remark`                                                                                               |
| `WRITE_FIELDS`            | `title`, `supplier_id`, `document_number`, `receipt_date`, `currency`, `total`, `company_entity_id`, `file_id`                                                  |

## Methods

### `add()`

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

Create a new expense document

`{base}.add` requires `title` and `currency.code`. Everything else — including `total` — is optional.

* `$data` — Document data

**Throws** `InvalidArgumentException` When a required field is missing, or a field or value is not accepted

### `create()`

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

Alias for add()

* `$data` — Document data

### `update()`

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

Update an expense document

* `$id` — Document UUID
* `$data` — Fields to update; null clears a nullable field

**Throws** `InvalidArgumentException` When the ID is empty, or a field or value is not accepted

### `info()`

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

Get one expense document

* `$id` — Document UUID
* `$includes` — Not supported — the info endpoint takes no includes

**Throws** `InvalidArgumentException` When the ID is empty or includes are requested

### `delete()`

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

Delete an expense document

### `approve()`

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

Approve an expense document

### `refuse()`

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

Refuse an expense document

### `markAsPendingReview()`

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

Put an expense document back to pending review

### `sendToBookkeeping()`

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

Send an expense document to bookkeeping

### `listPayments()`

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

List the payments registered on an expense document

Returns `data[]` — id, payment {amount, currency}, paid\_at, payment\_method, remark — and `meta.total` with the amount paid and, since specification 1.221.0, its currency.

### `registerPayment()`

```php
registerPayment(string $id, array $payment, string $paidAt, ?string $paymentMethodId = null, ?string $remark = null): array
```

Register a payment

* `$id` — Document UUID
* `$payment` — \['amount' => float, 'currency' => 'EUR']
* `$paidAt` — ISO 8601 date-time
* `$paymentMethodId` — Payment method UUID
* `$remark` — Free text

**Throws** `InvalidArgumentException` When a required value is missing or invalid

### `removePayment()`

```php
removePayment(string $id, string $paymentId): array
```

Remove one payment

**Throws** `InvalidArgumentException` When either ID is empty

### `updatePayment()`

```php
updatePayment(string $id, string $paymentId, ?array $payment = null, ?string $paidAt = null, ?string $paymentMethodId = null, ?string $remark = null): array
```

Update one payment

Only the document and payment IDs are required: pass null for $payment to change only the date, method or remark. Before v2.2.8 the payment amount was required on every update.

* `$id` — Document UUID
* `$paymentId` — Payment UUID
* `$payment` — \['amount' => float, 'currency' => 'EUR'], or null to leave it
* `$paidAt` — ISO 8601 date-time
* `$paymentMethodId` — Payment method UUID
* `$remark` — Free text

**Throws** `InvalidArgumentException` When an ID is empty or the payment is invalid

### `list()`

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

Not available — there is no list endpoint for a single expense type

**Throws** `InvalidArgumentException` Always

### `getValidCurrencyCodes()`

```php
getValidCurrencyCodes(): array
```

### `getValidReviewStatuses()`

```php
getValidReviewStatuses(): array
```

### `getValidPaymentStatuses()`

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

## Examples

Create a basic receipt:

```php
$receipt = Teamleader::receipts()->add(['title' => 'Office Lunch', 'currency' => ['code' => 'EUR'], 'total' => ['tax_inclusive' => ['amount' => 45.50]]]);
```

Create a complete receipt with all details:

```php
$receipt = Teamleader::receipts()->add(['title' => 'Business Dinner', 'supplier_id' => 'uuid', 'document_number' => 'REC-001', 'receipt_date' => '2024-01-15', 'currency' => ['code' => 'EUR'], 'total' => ['tax_inclusive' => ['amount' => 125.00]]]);
```

Get receipt details:

```php
$receipt = Teamleader::receipts()->info('receipt-uuid');
```

Update an existing receipt:

```php
Teamleader::receipts()->update('receipt-uuid', ['title' => 'Updated Title', 'receipt_date' => '2024-01-16']);
```

Approve a receipt:

```php
Teamleader::receipts()->approve('receipt-uuid');
```

Refuse a receipt:

```php
Teamleader::receipts()->refuse('receipt-uuid');
```

Mark a receipt as pending review:

```php
Teamleader::receipts()->markAsPendingReview('receipt-uuid');
```

Send receipt to bookkeeping:

```php
Teamleader::receipts()->sendToBookkeeping('receipt-uuid');
```

List payments for a receipt:

```php
$payments = Teamleader::receipts()->listPayments('receipt-uuid');
```

Register a payment for a receipt:

```php
Teamleader::receipts()->registerPayment('receipt-uuid', ['amount' => 45.50, 'currency' => 'EUR'], '2024-01-15T10:00:00Z');
```

Remove a payment from a receipt:

```php
Teamleader::receipts()->removePayment('receipt-uuid', 'payment-uuid');
```

Update a payment on a receipt:

```php
Teamleader::receipts()->updatePayment('receipt-uuid', 'payment-uuid', ['amount' => 50.00, 'currency' => 'EUR']);
```

Delete a receipt:

```php
Teamleader::receipts()->delete('receipt-uuid');
```