Added ability to specify effective-dated windows for employee and company benefits

You can now schedule effective-dated benefit deductions and contributions directly on external employee benefits. This enables accurate, auditable benefit changes over time—reducing manual work, payroll-time fixes, and partner-side scheduling logic.

Multiple employee benefit records—each with its own window—can exist for the same company benefit, providing a log of scheduled changes. Read more on our Benefit effective dating guide.

Why this matters

Benefits aren’t static. Employers frequently need to plan and manage changes over time, such as:

• New hires or terminations mid-cycle
• Leaves of absence with $0 deduction periods
• Catch-up or corrective contributions
• Temporary increases or decreases to address over- or under-withholding
• Switching benefit providers and scheduling changes to take effect in the future

Without effective dating, this logic needed to be manually managed—through payroll-time overrides or custom-built scheduling systems, approaches that aren’t scalable or auditable, and that introduce risk for missed or incorrect deductions.

Key functionality

• For an employee benefit to be applied to a payroll, it must be marked active on both the employee and the company benefit levels, and it needs to be specified as effective by the pay period end date.
• Existing employee benefits will have "effective_date: 1970-01-01" and "expiration_date: null". Creating a new employee benefit with an effective_date automatically sets the expiration date of the existing active benefit, so that no manual updates are required.
• The new include=all_benefits query parameter allows retrieval of all benefits, including future and expired benefits.
• The new action param on the bulk update employee benefits for a company benefit endpoint is used to specify create or update actions, and is required if effective dating params (effective_date or expiration_date) are passed.

Updated endpoints

Employee benefit APIs

• [POST /v1/employees/{employee_id}/employee_benefits](ref: post-v1-employees-employee_id-employee_benefits)
  • effective_date and expiration_date params are now accepted in the request body
  • effective_date and expiration_date fields now seen in the response body
• [GET /v1/employees/{employee_id}/employee_benefits](ref: get-v1-employees-employee_id-employee_benefits)
  • effective_date and expiration_date fields now seen in response body
  • include=all_benefits query param now accepted. If passed, this endpoint returns all benefits for the employee, instead of only the current benefit.
• [GET /v1/employee_benefits/{employee_benefit_id}](ref: get-v1-employee_benefits-employee_benefit_id)
  • effective_date and expiration_date fields now seen in the response body
• [PUT /v1/employee_benefits/{employee_benefit_id}](ref: put-v1-employee_benefits-employee_benefit_id)
  • effective_date and expiration_date params are now accepted in the request body
  • effective_date and expiration_date fields now seen in the response body

Company benefit APIs

• [GET /v1/company_benefits/{company_benefit_id}](ref: get-v1-company_benefits-company_benefit_id)
  • effective_date and expiration_date fields now seen in the response body
  • include=all_benefits query param now accepted. If passed, this endpoint returns all benefits for the employee, instead of only the current benefit.
• [GET /v1/company_benefits/{company_benefit_id}/employee_benefits](ref: get-v1-company_benefits-company_benefit_id-employee_benefits)
  • effective_date and expiration_date fields now seen in the response body
  • include=all_benefits query param now accepted. If passed, this endpoint returns all benefits for the employee, instead of only the current benefit.
• [PUT /v1/company_benefits/{company_benefit_id}/employee_benefits](ref: put-v1-company_benefits-company_benefit_id-employee_benefits)
  • effective_date and expiration_date params are now accepted in the request body
  • action param with possible values create or update is now accepted in the request body, and is required if effective dating params (effective_date or expiration_date) are passed
  • effective_date and expiration_date fields now seen in the response body