Skip to main content
PUT
/
companies
/
{companyId}
/
employees
/
{employeeId}
/
limits
/
recurrent
Set recurrent employee limits
curl --request PUT \
  --url https://pre-partners-api.cobee.io/api/v3/companies/{companyId}/employees/{employeeId}/limits/recurrent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
{
  "companyId": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
  "employeeId": "dd3de3a0-f903-42a0-b729-4cb16f185bc6",
  "payroll": "2023-11",
  "limits": {
    "meal": {
      "amount": {
        "amountInCents": 10000,
        "currency": "EUR"
      },
      "appliesTo": "employee",
      "period": "payroll"
    },
    "transport": {
      "amount": {
        "amountInCents": 5000,
        "currency": "EUR"
      },
      "appliesTo": "employee",
      "period": "payroll"
    },
    "nursery": {
      "amount": {
        "amountInCents": 15000,
        "currency": "EUR"
      },
      "appliesTo": "employee",
      "period": "payroll"
    }
  }
}

​
Overview

This endpoint allows you to set the employee limits for all the benefits defined by the partner, such as meals, transport and nurseries. It is mandatory to send the field appliesTo for each benefit to specify if the limit applies to the employee or a child. The possible values are employee or child.

​
Period values per benefit

Although the period field accepts payroll and year as possible values, not all benefits support both:
BenefitAllowed period values
mealpayroll only
transportpayroll only
nurseryyear only
Sending an unsupported period value for a given benefit will result in a validation error.

​
How it works?

The recurrent limit acts as the foundational base for an employee’s benefits month after month. It is tied to a specific payroll cycle using the mandatory payroll query parameter.
  • Next payroll cycle: You can only set recurrent limits for the next upcoming payroll cycle (e.g., if the current month is February, you must send March). Once set, this limit will automatically carry over into all subsequent payrolls.
  • Current or other future payroll cycles: If you attempt to update recurrent limits for the current payroll cycle or any cycle beyond the next one, the API will reject the request with a 400 Bad Request error.
  • Precedence: If an employee has a recurrent limit set, but a punctual limit is also set for the exact same month, the punctual limit will always prevail for that specific cycle.
If you need to make an adjustment for the current payroll cycle, please use the Punctual Limits endpoint instead.
For a detailed explanation of how limits work, including examples and scenarios, please refer to the Overview page.
Important: The response returned by this endpoint only echoes the limits you have just configured. It does not recalculate or return the final, effectively applied limits for the employee (e.g., if a punctual limit overrides this recurrent configuration).To retrieve the actual limits that will apply to an employee for a specific payroll cycle, you must use the Get employee limits endpoint.

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 company identifier

​
employeeId
string
required

The employee identifier

Query Parameters

​
payroll
string
required

The next payroll cycle identifier (format YYYY-MM). It must strictly correspond to the next upcoming payroll cycle.

Pattern: ^\d{4}-(0[1-9]|1[0-2])$

Body

application/json
​
meal
object
​
transport
object
​
nursery
object

Response

Limits successfully set

​
companyId
string<uuid>
required

The unique identifier of the company.

Example:

"a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890"

​
employeeId
string<uuid>
required

The unique identifier of the employee.

Example:

"dd3de3a0-f903-42a0-b729-4cb16f185bc6"

​
payroll
string
required

The next payroll cycle identifier (format YYYY-MM) from which the recurrent limits take effect.

Pattern: ^\d{4}-(0[1-9]|1[0-2])$
Example:

"2023-11"

​
limits
object
required

Echoes back the exact limits payload that was successfully applied to future cycles