API Changelog

All notable changes to the NannyKeeper API, newest first.

May 2026v1.6.0Voluntary set-aside override

POST /v1/payroll/run + /v1/payroll/preview

New optional `voluntary_set_aside` field on each employee in the request. Use it to override or skip the employee's recurring voluntary set-aside rule for this paycheck only.
Shape: `{ skip?: boolean, amount?: number }`. `skip: true` bypasses the rule for this paycheck; `amount: <number>` overrides the computed amount ($0–$9,999). Omit the field to apply the recurring rule normally.
The recurring rule itself (rate-of-gross or fixed-per-period) is configured via the dashboard on the employee profile — the API can only override or skip per-paycheck.
Voluntary set-asides are post-tax — they reduce the employee's net pay and accrue to a balance the employer holds in escrow. They do NOT affect gross pay, federal/state taxes, FICA, FUTA, SUTA, W-2 box 1, or Schedule H.

`run_payroll` and `preview_payroll` accept the new `voluntary_set_aside` override field. Existing 1.5.0 callers continue to work without any change — omitting the field applies the recurring rule normally.

April 2026v1.5.0Scheduled payroll

When `pay_date` is more than 5 business days in the future on a direct-deposit payroll, the API no longer fires ACH immediately. Instead the response returns `status: scheduled` and the payroll auto-fires at `scheduled_send_at` (5 biz days before pay_date).
New response fields: `scheduled_send_at` (ISO UTC timestamp) and `is_estimated: true`. The net pay and tax amounts returned are estimates — they're recomputed against current YTD and rate configs at fire time, which may shift the final numbers slightly if a rate fix shipped or another payroll landed in between.
In-window pay dates (within 5 business days) behave exactly as in v1.4.0 — `status: processing`/`pending_funding`/`completed`. No changes to that path.
Non-DD payrolls (check/cash) always fire immediately regardless of pay_date — no scheduled status.
Amount safeguards (`confirm_large_payroll`) and ACH debit authorization (`confirm_ach_debit`) gates now run at approve time for scheduled payrolls; callers still pass them through the same parameters.

Response now includes `is_estimated: true` when pay_date is far enough out that a real run would schedule. Flag lets agents tell users that scheduled numbers will be recomputed at fire.

`run_payroll` and `preview_payroll` pass through the new `scheduled` status, `scheduled_send_at`, and `is_estimated` fields with no parameter changes — v1.4.0 callers continue to work (the new status is an additive enum value).

April 2026v1.4.0Single-call payroll (breaking)

Breaking: the endpoint now creates, approves, and processes the payroll end-to-end. Previously it stopped at `status: draft` and required a human in the dashboard to finish.
Response `status` now reflects the real finalized state — `processing` (direct deposit ACH debit in flight), `pending_funding` (async DD funding), or `completed` (check/cash).
`pay_date` is now OPTIONAL. When omitted, the server picks the earliest valid pay date based on ACH submission lead time (5 business days, holiday-aware) and echoes it back as `pay_period.pay_date` in the response.
If `pay_date` is supplied and past the submission deadline, the API returns HTTP 400 with `details.next_valid_pay_date` so callers can self-correct.
Direct-deposit callers must now set `confirm_large_payroll: true` for totals >$5,000 or any single net pay >$3,000, and `confirm_ach_debit: true` for first-ever DD or when >30 days have elapsed since the last authorization. Mirrors the dashboard safety gates.

`pay_date` is now optional on preview too, defaulting to the same server-computed value. Use this to validate a request before calling /v1/payroll/run.

`run_payroll` and `preview_payroll` tools: `pay_date` is now optional.
`run_payroll`: added `confirm_large_payroll` and `confirm_ach_debit` parameters for direct-deposit safety gates.

March 2026v1.0.0Initial release

POST /v1/calculate — calculate household employer taxes for a single pay period across all 50 states
GET /v1/threshold — check if annual wages cross the IRS FICA threshold ($3,000 for 2026) and state-specific thresholds

POST /v1/payroll/run — run payroll for one or more employees with YTD tax tracking
GET /v1/payroll/:id — retrieve a completed payroll by ID
GET /v1/employees — list employees for an employer (cursor-based pagination, PII-safe)
POST /v1/employees — create a new employee
GET /v1/employers — list all employers in your organization (Professional)
POST /v1/employers — create a new employer in your organization (Professional)
GET /v1/employers/:id/dd-status — check direct deposit readiness
POST /v1/documents/paystub — generate a pay stub PDF for a completed payroll
POST /v1/documents/w2 — generate a W-2 for a given tax year
POST /v1/ach/transfer — initiate direct deposit ACH transfer (Plus and above)

Published @nannykeeper/mcp-server to npm
Supports calculate_nanny_taxes, check_threshold, and run_payroll tools via stdio transport
Compatible with Claude Desktop, Cursor, and any MCP-compliant client