> ## 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.
# Set recurrent limit
> Sets the recurrent employee limits for all the benefits defined by the partner
## 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**:
| Benefit | Allowed `period` values |
| ----------- | ----------------------- |
| `meal` | `payroll` only |
| `transport` | `payroll` only |
| `nursery` | `year` 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](/en/api-reference/limits/endpoint/put_employee_limits_punctual) endpoint instead.
For a detailed explanation of how limits work, including examples and scenarios, please refer to the
[Overview](/en/api-reference/limits/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](/en/api-reference/limits/endpoint/get_employee_limits) endpoint.
## OpenAPI
````yaml PUT /companies/{companyId}/employees/{employeeId}/limits/recurrent
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}/limits/recurrent:
put:
summary: Set recurrent employee limits
description: >-
Sets the recurrent employee limits for all the benefits defined by the
partner
parameters:
- name: companyId
in: path
required: true
schema:
type: string
format: uuid
description: The company identifier
- name: employeeId
in: path
required: true
schema:
type: string
description: The employee identifier
- name: payroll
in: query
required: true
schema:
type: string
pattern: ^\d{4}-(0[1-9]|1[0-2])$
description: >-
The next payroll cycle identifier (format YYYY-MM). It must strictly
correspond to the next upcoming payroll cycle.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
meal:
type: object
required:
- amount
- appliesTo
- period
properties:
amount:
type: object
required:
- amountInCents
- currency
properties:
amountInCents:
type: integer
currency:
type: string
example: EUR
appliesTo:
type: string
enum:
- employee
- child
description: Specifies who the limit applies to
period:
type: string
enum:
- payroll
- year
description: The period the limit applies for
transport:
type: object
required:
- amount
- appliesTo
- period
properties:
amount:
type: object
required:
- amountInCents
- currency
properties:
amountInCents:
type: integer
currency:
type: string
example: EUR
appliesTo:
type: string
enum:
- employee
- child
description: Specifies who the limit applies to
period:
type: string
enum:
- payroll
- year
description: The period the limit applies for
nursery:
type: object
required:
- amount
- appliesTo
- period
properties:
amount:
type: object
required:
- amountInCents
- currency
properties:
amountInCents:
type: integer
currency:
type: string
example: EUR
appliesTo:
type: string
enum:
- employee
- child
description: Specifies who the limit applies to
period:
type: string
enum:
- payroll
- year
description: The period the limit applies for
responses:
'200':
description: Limits successfully set
content:
application/json:
schema:
$ref: '#/components/schemas/LimitsRecurrentPutResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: validation_error
message: Invalid employeeId
'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
components:
schemas:
LimitsRecurrentPutResponse:
type: object
required:
- companyId
- employeeId
- payroll
- limits
properties:
companyId:
type: string
description: The unique identifier of the company.
format: uuid
example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
employeeId:
type: string
description: The unique identifier of the employee.
format: uuid
example: dd3de3a0-f903-42a0-b729-4cb16f185bc6
payroll:
type: string
description: >-
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:
type: object
description: >-
Echoes back the exact limits payload that was successfully applied
to future cycles
properties:
meal:
type: object
required:
- amount
- appliesTo
- period
properties:
amount:
type: object
required:
- amountInCents
- currency
properties:
amountInCents:
type: integer
example: 10000
currency:
type: string
example: EUR
appliesTo:
type: string
enum:
- employee
- child
description: Specifies who the limit applies to
period:
type: string
enum:
- payroll
- year
description: The period the limit applies for
example: payroll
transport:
type: object
required:
- amount
- appliesTo
- period
properties:
amount:
type: object
required:
- amountInCents
- currency
properties:
amountInCents:
type: integer
example: 5000
currency:
type: string
example: EUR
appliesTo:
type: string
enum:
- employee
- child
description: Specifies who the limit applies to
period:
type: string
enum:
- payroll
- year
description: The period the limit applies for
example: payroll
nursery:
type: object
required:
- amount
- appliesTo
- period
properties:
amount:
type: object
required:
- amountInCents
- currency
properties:
amountInCents:
type: integer
example: 15000
currency:
type: string
example: EUR
appliesTo:
type: string
enum:
- employee
- child
description: Specifies who the limit applies to
period:
type: string
enum:
- payroll
- year
description: The period the limit applies for
example: payroll
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
````