> ## Documentation Index
> Fetch the complete documentation index at: https://docs.partners.api.cobee.io/llms.txt
> Use this file to discover all available pages before exploring further.

# [DRAFT] List employee committed expenses

> Retrieves the committed expenses of a specific employee, optionally filtered by fiscal year, category and status.

> [!NOTE]
>
> **Coming soon**: this endpoint is still under review and may change before release.

## Overview

This endpoint returns the committed expenses of a specific employee: the amounts the employee has committed to spend over several payroll cycles, such as nursery. A committed expense counts against the employee's flexible-benefit limit from the moment it is committed, so use this endpoint to know how much of the limit is already taken.

Each committed expense belongs to a single fiscal year and benefit category. Nursery has an annual limit, so its committed expenses are reported per fiscal year.

You can narrow the response with the following query parameters:

* **`fiscalYear`**: a single fiscal year (e.g. `2026`). If omitted, all fiscal years are returned.
* **`categories`**: a comma-separated list of benefit categories. Currently only `nursery-benefit` is supported.
* **`status`**: a comma-separated list of statuses (e.g. `active,finished`). If omitted, committed expenses in any status are returned.

### Status

* **`active`**: the committed expense has payments still to be charged. Cancelling a single payment does not change the status.
* **`finished`**: the last payment has been charged and nothing remains pending.
* **`cancelled`**: the committed expense, or its remaining future payments, has been cancelled. Its `pendingPayments` will never be charged.

### Amounts and payments

`committedAmountInCents` is the total committed and `paidAmountInCents` is the part already charged. The committed expense is split into `numberOfPayments` monthly payments, of which `pendingPayments` are still to be charged.

Each payment is charged at the start of its payroll cycle and is also reported as a regular consumption by the [consumptions](https://docs.partners.api.cobee.io/publicApi/en/api-reference/consumptions/endpoint/get_employee_consumptions.md) endpoints and the [`employee.consumption.generated`](https://docs.partners.api.cobee.io/en/api-reference/webhooks/events/employee_consumption_generated) webhook event.

### Recipient

`recipient` identifies the person the committed expense applies to when it is not the employee, for example a child for nursery. It is omitted when the committed expense applies to the employee. `recipient.id` is the same identifier returned as `FamilyMember.id` by the [Family Members](https://docs.partners.api.cobee.io/en/api-reference/family-members/endpoint/get_family_members.md) endpoints, and can be used with the [Get family member](https://docs.partners.api.cobee.io/en/api-reference/family-members/endpoint/get_family_member.md) endpoint.

### Webhooks

The `employee.committed-expense.*` and `employee.committed-expense.payment.*` [webhook events](https://docs.partners.api.cobee.io/en/api-reference/webhooks/events) notify you when a committed expense is created, finished or cancelled, as a whole or one payment at a time. Events only identify what changed: call this endpoint after receiving one to get the current amounts. The `id` of each committed expense is the same `committedExpense.id` sent in those events.

**Examples**

#### application/json

**default**

```json theme={null}
{
  "company": {
    "id": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
    "legalId": "B12345678",
    "currency": "EUR",
    "employee": {
      "employeeId": "dd3de3a0-f903-42a0-b729-4cb16f185bc6",
      "internalId": "12345",
      "legalId": "129387655X",
      "committedExpenses": [
        {
          "id": "3c9a1e72-5b4d-4f08-9e6a-1d2c3b4a5f60",
          "category": "nursery-benefit",
          "fiscalYear": "2025",
          "status": "finished",
          "recipient": { "id": "8a1b2c3d-4e5f-6789-a0b1-c2d3e4f56789" },
          "committedAmountInCents": 120000,
          "paidAmountInCents": 120000,
          "numberOfPayments": 4,
          "pendingPayments": 0
        },
        {
          "id": "f235bb3a-204a-47cf-ad22-2e48a590cdce",
          "category": "nursery-benefit",
          "fiscalYear": "2026",
          "status": "active",
          "recipient": { "id": "8a1b2c3d-4e5f-6789-a0b1-c2d3e4f56789" },
          "committedAmountInCents": 30000,
          "paidAmountInCents": 10000,
          "numberOfPayments": 3,
          "pendingPayments": 2
        },
        {
          "id": "b7e4d2a1-6c3f-4a58-8d9e-0f1a2b3c4d5e",
          "category": "nursery-benefit",
          "fiscalYear": "2026",
          "status": "cancelled",
          "recipient": { "id": "4f6e8d0c-2b1a-4c3d-9e8f-7a6b5c4d3e2f" },
          "committedAmountInCents": 40000,
          "paidAmountInCents": 20000,
          "numberOfPayments": 4,
          "pendingPayments": 2
        }
      ]
    }
  }
}
```

**status=active**

```json theme={null}
{
  "company": {
    "id": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
    "legalId": "B12345678",
    "currency": "EUR",
    "employee": {
      "employeeId": "dd3de3a0-f903-42a0-b729-4cb16f185bc6",
      "internalId": "12345",
      "legalId": "129387655X",
      "committedExpenses": [
        {
          "id": "f235bb3a-204a-47cf-ad22-2e48a590cdce",
          "category": "nursery-benefit",
          "fiscalYear": "2026",
          "status": "active",
          "recipient": { "id": "8a1b2c3d-4e5f-6789-a0b1-c2d3e4f56789" },
          "committedAmountInCents": 30000,
          "paidAmountInCents": 10000,
          "numberOfPayments": 3,
          "pendingPayments": 2
        }
      ]
    }
  }
}
```

**fiscalYear=2025 & categories=nursery-benefit**

```json theme={null}
{
  "company": {
    "id": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
    "legalId": "B12345678",
    "currency": "EUR",
    "employee": {
      "employeeId": "dd3de3a0-f903-42a0-b729-4cb16f185bc6",
      "internalId": "12345",
      "legalId": "129387655X",
      "committedExpenses": [
        {
          "id": "3c9a1e72-5b4d-4f08-9e6a-1d2c3b4a5f60",
          "category": "nursery-benefit",
          "fiscalYear": "2025",
          "status": "finished",
          "recipient": { "id": "8a1b2c3d-4e5f-6789-a0b1-c2d3e4f56789" },
          "committedAmountInCents": 120000,
          "paidAmountInCents": 120000,
          "numberOfPayments": 4,
          "pendingPayments": 0
        }
      ]
    }
  }
}
```


## OpenAPI

````yaml GET /companies/{companyId}/employees/{employeeId}/committed-expenses
openapi: 3.0.1
info:
  title: Partners API
  description: >-
    Partners API definition where you can check the documentation for the
    different available operations to integrate with the platform.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://pre-partners-api.cobee.io/api/v3
  - url: https://partners-api.cobee.io/api/v3
security:
  - bearerAuth: []
paths:
  /companies/{companyId}/employees/{employeeId}/committed-expenses:
    get:
      summary: Get employee committed expenses
      description: >-
        Retrieves the committed expenses of a specific employee, optionally
        filtered by fiscal year, category and status.
      parameters:
        - name: companyId
          in: path
          required: true
          description: The unique identifier of the company
          schema:
            type: string
            format: uuid
          example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
        - name: employeeId
          in: path
          required: true
          description: The unique identifier of the employee
          schema:
            type: string
          example: dd3de3a0-f903-42a0-b729-4cb16f185bc6
        - name: fiscalYear
          in: query
          required: false
          description: >-
            Restrict the results to a single fiscal year (e.g. `2026`). If not
            provided, all fiscal years with committed expenses are returned.
          schema:
            type: string
            pattern: ^[0-9]{4}$
            example: '2026'
        - name: categories
          in: query
          required: false
          description: >-
            Comma-separated list of benefit categories to include in the
            response. Currently only `nursery-benefit` is supported. If not
            provided, all categories are returned.
          schema:
            type: string
            example: nursery-benefit
        - name: status
          in: query
          required: false
          description: >-
            Comma-separated list of statuses to include in the response:
            `active`, `finished` and/or `cancelled` (e.g. `active,finished`). If
            not provided, committed expenses in any status are returned.
          schema:
            type: string
            example: active,finished
      responses:
        '200':
          description: Employee committed expenses successfully retrieved
          content:
            application/json:
              schema:
                type: object
                required:
                  - company
                properties:
                  company:
                    type: object
                    required:
                      - id
                      - legalId
                      - currency
                      - employee
                    properties:
                      id:
                        type: string
                        description: The unique identifier of the company.
                        format: uuid
                        example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
                      legalId:
                        type: string
                        description: The company's legal id
                        example: B12345678
                      currency:
                        type: string
                        description: The currency code (e.g., EUR)
                        example: EUR
                      employee:
                        type: object
                        description: Employee
                        required:
                          - employeeId
                          - internalId
                          - legalId
                          - committedExpenses
                        properties:
                          employeeId:
                            type: string
                            format: uuid
                            description: The unique identifier of the employee
                            example: dd3de3a0-f903-42a0-b729-4cb16f185bc6
                          internalId:
                            type: string
                            description: >-
                              The unique identifier of the employee in the
                              client's system
                            example: '12345'
                          legalId:
                            type: string
                            description: The employee's legal id
                            example: 129387655X
                          committedExpenses:
                            type: array
                            description: List of employee committed expenses
                            items:
                              type: object
                              required:
                                - id
                                - category
                                - fiscalYear
                                - status
                                - committedAmountInCents
                                - paidAmountInCents
                                - numberOfPayments
                                - pendingPayments
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                  description: >-
                                    The unique identifier of the committed
                                    expense. It is the same
                                    `committedExpense.id` sent by the committed
                                    expense webhook events.
                                  example: f235bb3a-204a-47cf-ad22-2e48a590cdce
                                category:
                                  type: string
                                  description: >-
                                    The benefit category of the committed
                                    expense.
                                  enum:
                                    - nursery-benefit
                                  example: nursery-benefit
                                fiscalYear:
                                  type: string
                                  description: >-
                                    The fiscal year the committed expense
                                    belongs to.
                                  example: '2026'
                                status:
                                  type: string
                                  description: |-
                                    The current status of the committed expense:
                                     - `active`: there are payments still to be charged. Cancelling a single payment does not change the status.
                                     - `finished`: the last scheduled payment has been charged and nothing remains pending.
                                     - `cancelled`: the committed expense, or its remaining future payments, has been cancelled. Pending payments will never be charged.
                                  enum:
                                    - active
                                    - finished
                                    - cancelled
                                  example: active
                                recipient:
                                  type: object
                                  description: >-
                                    The person the committed expense applies to
                                    when different from the employee. Omitted
                                    when the committed expense applies directly
                                    to the employee, so the employee's
                                    identifier is not duplicated. When present,
                                    `recipient.id` is the same identifier
                                    returned as `FamilyMember.id` by the Family
                                    Members endpoints.
                                  required:
                                    - id
                                  properties:
                                    id:
                                      type: string
                                      format: uuid
                                      description: >-
                                        The unique identifier of the
                                        corresponding family member. This is the
                                        same identifier returned as
                                        `FamilyMember.id` by the Family Members
                                        endpoints.
                                      example: 8a1b2c3d-4e5f-6789-a0b1-c2d3e4f56789
                                committedAmountInCents:
                                  type: integer
                                  description: >-
                                    Total amount committed, in cents (e.g.,
                                    30000 for 300.00).
                                  minimum: 0
                                  example: 30000
                                paidAmountInCents:
                                  type: integer
                                  description: >-
                                    Amount already paid/charged for this
                                    committed expense, in cents.
                                  minimum: 0
                                  example: 10000
                                numberOfPayments:
                                  type: integer
                                  description: >-
                                    Total number of monthly payments the
                                    committed expense is split into.
                                  minimum: 1
                                  example: 3
                                pendingPayments:
                                  type: integer
                                  description: >-
                                    Number of monthly payments not yet charged.
                                    When `status` is `cancelled`, these payments
                                    will never be charged.
                                  minimum: 0
                                  example: 2
        '400':
          description: >-
            Bad Request - Invalid `fiscalYear` format, or unsupported
            `categories` or `status` value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: fiscalYear must be a 4-digit year
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: invalid_token
        '403':
          description: Forbidden - Company does not belong to the specified partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Company does not belong to the specified partner
        '404':
          description: Not Found - The employee or company was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Resource not found
        '500':
          description: Internal Server Error - Something went wrong on our end
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Internal server error
components:
  schemas:
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
      example:
        message: 'Bad request: Invalid field value'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.