Mercer Integration Guide

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

---

​

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.