Skip to main content

​
Employee Spending Limits

The Limits API enables partners to manage spending limits for employee benefits across three categories: meal, transport, and nursery (childcare).

​
How It Works

Cobee uses two types of limits to give you complete flexibility: Recurrent Limits and Punctual Limits.

​
1. Recurrent Limits (Base Rules)

Recurrent limits act as the foundational base for an employee’s benefits month after month.
  • Setup: They must be set for the next payroll cycle (e.g., if the current month is February, you must send March).
  • Behavior: Once set, a recurrent limit automatically carries over into all subsequent payrolls unless modified or disabled.
  • Endpoint: PUT /companies/{companyId}/employees/{employeeId}/limits/recurrent
Use Case: Setting standard monthly allowances like a €150/month transport benefit for a newly onboarded employee.

​
2. Punctual Limits (Current Cycle Adjustments)

Punctual limits allow you to specify a one-time adjustment that applies strictly to the current payroll cycle.
  • Setup: They must be set for the current payroll cycle (e.g., if the current month is February, you must send February).
  • Behavior: Punctual limits are completely independent. They do not require a recurrent limit to exist first, and they only affect the exact month you specify. Once the month ends, the system reverts to the employee’s base recurrent limits (if any exist).
  • Endpoint: PUT /companies/{companyId}/employees/{employeeId}/limits/punctual
Use Cases:
  • Ad-hoc Adjustments: An employee receives a one-time €50 meal bonus for the current month.
  • New signups mid-month: Restricting or allowing a specific amount for the prorated remaining days of the current month.

​
3. Precedence (The Golden Rule)

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 act as the active limit for that cycle.

​
Common Scenarios

​
Scenario 1: Standard Onboarding

Situation: You register a new employee in January. You want them to have a base €200 meal allowance every month starting in February. Once you successfully register the employee (receiving a 200 OK), you configure the employee’s recurrent limits by specifying the next payroll cycle (payroll=2026-02). They cannot consume benefits in January. When February starts, the €200 limit becomes active and will automatically carry over to March, April, and beyond.

​
Scenario 2: Onboarding with Prorated Current Month

Situation: An employee is registered in January. You want their standard €220 recurrent limit to start in February, but you also want them to enjoy the prorated limit amount that corresponds to the remaining days of January. You make two calls: one to the punctual endpoint for the current month (payroll=2026-01) with the prorated amount, and one to the recurrent endpoint for the next month (payroll=2026-02) with the full €220 amount.

​
Scenario 3: Changing a Recurrent Limit in the Future

Situation: An employee’s base recurrent limit is €200/month. You want to increase this base limit to €220/month starting in September. Because recurrent limits can only be explicitly set for the next payroll cycle, you cannot schedule this change months in advance. You must wait until August, and then call the recurrent endpoint specifying the target payroll (payroll=2026-09).
Best Practice: Both recurrent and punctual limit endpoints are idempotent. Repeated identical requests will leave the system in the same desired state. If you make a mistake setting a limit, simply resend the payload for that exact same payroll cycle and the system will overwrite the value.