> ## 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 punctual limit
> Sets a punctual limit for an employee's benefits strictly during the current payroll cycle. Punctual limits operate independently of recurrent limits.
## Overview
This endpoint allows you to set a punctual limit for an employee's benefits **strictly during the current payroll cycle**.
Unlike the `PUT` recurrent limits endpoint, making a punctual limits update here will **only** affect the specified current `payroll` period.
### Mechanics
* **Mandatory**: To set a punctual limit, you must provide the precise `payroll` identifier (e.g., `2026-05`) as a required query parameter. **This identifier must correspond to the current ongoing payroll cycle**.
* **Independent**: Punctual limits do **not** require a recurrent limit to exist. They operate independently.
* **Precedence**: If an employee has both a recurrent limit and a punctual limit configured for the exact same month, the **punctual limit will always prevail** and be the active limit for that cycle.
If you attempt to set a punctual limit for a future or past payroll cycle, the API will reject the request.
This is particularly useful when you need to momentarily increase or decrease a limit for the current month without modifying the base recurrent limit.
### 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.
For a detailed explanation of how limits and payroll cycles are evaluated, 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., due to precedence rules overriding other limits).
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/punctual
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/punctual:
put:
summary: Set a punctual limit for a specific payroll cycle
description: >-
Sets a punctual limit for an employee's benefits strictly during the
current payroll cycle. Punctual limits operate independently of
recurrent limits.
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 current payroll cycle identifier (format YYYY-MM). It must
strictly correspond to the current ongoing payroll cycle.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- payroll
properties:
payroll:
type: string
pattern: ^\d{4}-(0[1-9]|1[0-2])$
description: >-
The current payroll cycle identifier (format YYYY-MM) this
punctual limit applies to. Future or past payrolls are not
allowed.
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
responses:
'200':
description: Punctual limit successfully created or updated
content:
application/json:
schema:
$ref: '#/components/schemas/LimitsPunctualPutResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: validation_error
message: payroll must be the current month
'401':
description: Unauthorized
'403':
description: Forbidden
components:
schemas:
LimitsPunctualPutResponse:
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 payroll cycle identifier (format YYYY-MM) for which the limits
have been set.
pattern: ^\d{4}-(0[1-9]|1[0-2])$
example: 2023-10
limits:
type: object
description: >-
Echoes back the exact limits payload that was successfully applied
for this cycle
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
````