Skip to main content
PUT
/
companies
/
{companyId}
/
employees
/
{employeeId}
/
limits
/
punctual
Set a punctual limit for a specific payroll cycle
curl --request PUT \
  --url https://pre-partners-api.cobee.io/api/v3/companies/{companyId}/employees/{employeeId}/limits/punctual \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "payroll": "<string>"
}
'
{
  "companyId": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
  "employeeId": "dd3de3a0-f903-42a0-b729-4cb16f185bc6",
  "payroll": "2023-10",
  "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 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:
BenefitAllowed period values
mealpayroll only
transportpayroll only
nurseryyear 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 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 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 current payroll cycle identifier (format YYYY-MM). It must strictly correspond to the current ongoing payroll cycle.

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

Body

application/json
​
payroll
string
required

The current payroll cycle identifier (format YYYY-MM) this punctual limit applies to. Future or past payrolls are not allowed.

Pattern: ^\d{4}-(0[1-9]|1[0-2])$
​
meal
object
​
transport
object
​
nursery
object

Response

Punctual limit successfully created or updated

​
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 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
object
required

Echoes back the exact limits payload that was successfully applied for this cycle