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

# Mercer Integration Guide

> How to use the Limits API to fulfill Mercer specific integration requirements.

This guide explains how the Limits API addresses the four core technical requirements for the Mercer
integration, including idempotent updates and bulk limit disabling.

## Requirements Overview

Mercer's integration requires a robust and fault-tolerant way to manage employee benefits. The four main pillars of this integration are:

1. **Updating Current Limits**: The ability to safely modify an employee's limit for the *currently active* payroll cycle as many times as needed.
2. **Scheduling Future Limits**: Setting limits for upcoming payroll cycles in advance with the same robust update capabilities.
3. **Reading Limits**: Retrieving the current status of limits for reconciliation.
4. **Bulk Limit Disabling**: Preventing a group of employees from using a benefit during a particular future month (e.g., Christmas).

***

## 1. Updating Current Payroll Limits

A major hurdle for Mercer was that once a limit was established for an employee, subsequent calls to update that limit often unintentionally targeted the *next* payroll cycle. They need the ability to confidently update the *current*, active limit multiple times if necessary.

### Solution

The `PUT /companies/{companyId}/employees/{employeeId}/limits/punctual` endpoint targets the open payroll cycle and is fully **idempotent**. It requires the `payroll` query parameter to be explicitly provided.

If Mercer sets an initial meal limit of €150 using the recurrent limit, and later needs to increase it to €200 for the current month (`payroll=2026-01`) due to an exception or resend a payload due to a system retry, the punctual API ensures the limit in the current cycle is exactly what is specified in the latest payload.

**Impact for Mercer:**

* **Active Limit Corrections**: Safely correct or adjust an employee's limit mid-month without bleeding into future periods.
* **Safe Retries**: Synchronization jobs can be re-run cleanly; sending the same data multiple times leaves the system in the exact same state.

***

## 2. Scheduling and Updating Future Limits

Just like the current payroll, Mercer needs to program changes for upcoming months (e.g., salary updates taking effect next month) with the same safety guarantees.

### Solution

Using the `PUT /companies/{companyId}/employees/{employeeId}/limits/recurrent` endpoint (specifying the target month in the `payroll` query, e.g., `payroll=2024-05`), Mercer can schedule base limits for the future. This operation is also **idempotent**. Sending the same payload for `2024-05` multiple times will consistently result in the same scheduled limit, overwriting any previously scheduled amount for that specific cycle.

**Impact for Mercer:**

* **Consistent Synchronization**: The exact same retry mechanisms built for current limits apply directly to future limits.
* **Predictability**: Scheduling is declarative—Mercer states what the limit *should be* in that future month.

***

## 3. Retrieving Limits State

To ensure data consistency between Mercer's systems and the platform, Mercer needs to be able to audit and consult the current configuration of limits.

### Solution

Mercer can use the `GET` endpoints to retrieve the limits:

* `GET /companies/{companyId}/employees/{employeeId}/limits`: To check a single employee.
* `GET /corporations/{corporationId}/limits`: To retrieve a bulk list of all employee limits within a corporation, highly optimized for reconciliation processes via CSV format.

**Impact for Mercer:**

* **Auditability**: Full visibility into both the active limits and the scheduled future limits (by passing the `payroll` parameter).

***

## 4. Bulk Limit Disabling (e.g., Christmas Month)

Mercer has scenarios where a specific benefit limit (like meals) needs to be disabled for a distinct group of employees during a specific month (e.g., December for holidays). Disabling the limit prevents those employees from using that benefit during the selected month.

### Solution

The Limits API provides a dedicated bulk action endpoint tailored for this exact use case:
`POST /companies/{companyId}/limits/disable`

Mercer can send a list of `employees`, specify the `benefit` (e.g., `meal`), and target the specific month using `period=2026-12`. The selected employees cannot use that benefit while their limit is disabled.

<Warning>
  **No `enable` endpoint yet**: there is currently no endpoint to restore a disabled benefit limit before
  its `period` ends — an `enable` counterpart is planned as a follow-up. If Mercer needs to revert
  a suspension today, that requires manual intervention; until `enable` ships, treat `disable`
  calls as final for the `period` they target.
</Warning>

**Impact for Mercer:**

* **Efficiency**: Disable limits for hundreds of employees in a single API call instead of iterating one by one.
* **Per-employee reporting**: The response returns a flat `{total, processed, skipped, failed, errors}` report, so Mercer can immediately see which employees failed and why, instead of having to poll or reconcile separately.

***

## Summary of Platform Benefits

This new declarative and idempotent approach provides several key advantages for integrating systems, fulfilling both explicit requirements and offering additional architectural benefits:

| Feature / Benefit | Description | Why it matters |
| :- | :- | :- |
| **Current Cycle Updates** | `PUT .../limits/punctual` updates the open payroll (mandatory `payroll` param). | **(Mercer Request)** Solves the issue where updates unintentionally applied to future cycles. |
| **Future Cycle Scheduling** | `PUT .../limits/recurrent` specifying a mandatory `payroll` month targets that future period. | **(Mercer Request)** Allows preparing limits in advance (e.g., salary changes taking effect next month). |
| **Idempotency** | Sending the same total requested limits multiple times guarantees the same final state. | **(Platform Benefit)** Enables safe, "blind" retries without complex state-checking logic on the client side. |
| **Bulk Limit Disabling** | `POST .../limits/disable` prevents employees from using a benefit for an array of employees in one call. | **(Mercer Request)** Drastically reduces API calls and efficiently manages temporary restrictions (e.g., Christmas closures). |
| **Optimized Reads** | Support for `text/csv` with `columns` format mirroring limit structure. | **(Mercer Request)** Enables highly efficient generation of large datasets for their internal reporting processes. |

***

## Technical Change Management Strategy

Mercer's technical team is known for being highly specialized and reticent to change established integrations. To successfully present this architectural shift to their engineers, we recommend focusing the narrative on **long-term stability**, **error elimination**, and **simplified implementation**.

### Key Talk Tracks for Mercer's Engineering Team

1. **"We are eliminating your state-checking overhead"**
   * **The Pitch:** Emphasize that adding strict idempotency means they can delete their existing code that fetches the limits state before pushing an update. They can move to a "fire and forget" model, pushing the desired end state directly.
   * **Why it works:** Engineers love deleting complex, brittle code.

2. **"We fixed the 'Next Payroll' bug"**
   * **The Pitch:** Address their primary pain point directly. Explain that the new explicit design (separating Recurrent and Punctual limits) guarantees that a mid-month update will never accidentally apply to the following month.
   * **Why it works:** It shows we actively listened to the bugs they reported and designed a permanent fix at the architectural level.

3. **"The new 'Disable' endpoint is a brand-new capability"**
   * **The Pitch:** Present `POST /limits/disable` as a purpose-built feature for their "Christmas closure" problem. It disables the employee's benefit limit, preventing use of that benefit during the selected period. Be upfront that `enable` is not available yet, so this is best framed as "coming now, with more to follow" rather than a finished round-trip workflow.

* **Why it works:** Framing it as a new capability (with an honest roadmap) builds trust rather than over-promising.

4. **"Your retry logic is now bulletproof"**
   * **The Pitch:** Because both current and future updates are strictly idempotent, their synchronization retry mechanisms (e.g., in case of 500s or network timeouts) are now 100% safe to run without fear of duplication or state corruption.
   * **Why it works:** Technical teams responsible for batch processing highly value strong guarantees around idempotency and fault tolerance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.