> ## 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.

# Overview

> Learn how to manage employee spending limits for meal, transport, and childcare benefits.

# 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`

<Note>
  **Use Case**: Setting standard monthly allowances like a €150/month transport benefit for a newly onboarded employee.
</Note>

### 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`

<Note>
  **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.
</Note>

### 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.

```mermaid theme={null}
sequenceDiagram
    participant Partner
    participant API
    participant Cobee

    Note over Partner: 1. Register new employee (January)
    Partner->>API: PUT .../limits/recurrent?payroll=2026-02
    Note right of Partner: Set RECURRENT limit: €200
    API->>Cobee: Save base limit starting Feb '26
    Cobee-->>API: Success
    API-->>Partner: 200 OK
    Note over Partner,API: Jan: No limit.<br/>Feb onwards: €200/month
```

***

### 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.

```mermaid theme={null}
sequenceDiagram
    participant Partner
    participant API
    participant Cobee

    Partner->>API: PUT .../limits/punctual?payroll=2026-01
    Note right of Partner: Set PUNCTUAL limit (Prorated): €100
    API->>Cobee: Save one-time limit for Jan '26
    
    Partner->>API: PUT .../limits/recurrent?payroll=2026-02
    Note right of Partner: Set RECURRENT limit: €220
    API->>Cobee: Save base limit starting Feb '26
    
    Note over Partner,API: Jan: Employee has €100.<br/>Feb onwards: Employee has €220.
```

***

### 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`).

```mermaid theme={null}
sequenceDiagram
    participant Partner
    participant API
    participant Cobee

    Note over Partner: Base Recurrent Limit: €200
    Note over Partner: WAIT UNTIL AUGUST
    Partner->>API: PUT .../limits/recurrent?payroll=2026-09
    Note right of Partner: Update RECURRENT limit: €220
    API->>Cobee: Overwrite base limit starting Sep '26
    Cobee-->>API: Success
    API-->>Partner: 200 OK
    Note over Partner,API: Aug: €200<br/>Sep onwards: €220
```

***

### Scenario 4: Bulk Suspending Benefits (e.g., Summer Holidays)

**Situation**: You want to temporarily suspend benefits for a specific group of employees during the month of July.

First, use the `GET` limits endpoint to retrieve the list of employees. Cross-reference this list with your own internal client data to identify exactly which employees should have their benefits suspended. Then, call the **disable** endpoint for those employees by passing their IDs and the target cycle (`payroll=2026-07`).

If you make a mistake, simply call the **enable** endpoint for the same employees to revert the suspension.

<Info>
  **Global suspension**: If your goal is to suspend benefits for the **entire company** (all employees), you can simply omit the `employees` array in the request body completely.
</Info>

```mermaid theme={null}
sequenceDiagram
    participant Partner
    participant Cobee

    Note over Partner: 1. Suspend future benefits for specific employees
    Partner->>Cobee: POST .../limits/disable?payroll=2026-07
    Note over Partner,Cobee: Benefits scheduled to be inactive in July
    
    Note over Partner: 2. Revert suspension (if mistake)
    Partner->>Cobee: POST .../limits/enable?payroll=2026-07
    Note over Partner,Cobee: Benefits will be active in July
```

<Info>
  **Important**: The Limits disable/enable endpoints are intended specifically for systemic, temporary benefit suspensions. For common employee status changes like Medical Leave, you should continue to use the standard Employee API.
</Info>

***

### Scenario 5: Future Suspension Timing Constraint

**Situation**: You register an employee in January and want to suspend their meal benefit specifically for the month of August.

Similar to recurrent limits, you **cannot** schedule a disablement many months in advance. The `payroll` parameter is limited strictly to the **current or next** payroll cycle. Therefore, you must wait until July opens, and then make your `disable` call targeting `payroll=2026-08`.

```mermaid theme={null}
sequenceDiagram
    participant Partner
    participant API
    participant Cobee

    Note over Partner: Goal: Disable meals for August
    Note over Partner: WAIT UNTIL JULY
    Partner->>API: POST .../limits/disable?payroll=2026-08
    Note right of Partner: Target specific category: meal
    API->>Cobee: Schedule disablement for Aug '26
    Cobee-->>API: Success
```

***

<Tip>
  **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.
</Tip>