Skip to main content
GET
Get employee committed expenses
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 endpoints and the 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 endpoints, and can be used with the Get family member endpoint.

Webhooks

The employee.committed-expense.* and employee.committed-expense.payment.* webhook 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.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

companyId
string<uuid>
required

The unique identifier of the company

employeeId
string
required

The unique identifier of the employee

Query Parameters

fiscalYear
string

Restrict the results to a single fiscal year (e.g. 2026). If not provided, all fiscal years with committed expenses are returned.

Pattern: ^[0-9]{4}$
Example:

"2026"

categories
string

Comma-separated list of benefit categories to include in the response. Currently only nursery-benefit is supported. If not provided, all categories are returned.

Example:

"nursery-benefit"

status
string

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.

Example:

"active,finished"

Response

Employee committed expenses successfully retrieved

company
object
required