v2023-04-01

This is the changelog for v2023-04-01, which contains payroll API breaking changes.

To learn more about versions in our API, read the Versioning guide.

• Improvements to our existing payroll API endpoints. These changes focus on removing unexpected mutations on the payroll record from existing GET endpoints and improving reliability and performance, see Payroll Guide for more details
  • Removed eligible_employees from the get pay periods endpoint. The eligible employees for a payroll are determined by the employee_compensations returned from the payrolls prepare endpoint. The end date cannot be more than 3 months in the future.
  • For the get payrolls endpoint
    • totals are no longer included by default and employee_compensations and version were removed. You can optionally request totals with the include param, i.e. ?include=totals,payroll_status_meta.
    • Start and end date range cannot be more than a year. The end date cannot be more than 3 months in the future.
    • Added processing_statuses param used to return processed, unprocessed or both types of payrolls, defaults to processed, i.e. processing_statuses=unprocessed,processed.
    • Added payroll_types param used to return regular, off_cycle, or both types of payrolls, defaults to regular, i.e. payrolls_types=regular,off_cycle
  • Introduced a new endpoint used to 'prepare' a payroll for the running payroll process. This will add/remove eligible employees from the payroll employee_compensations and provide a payroll version for making subsequent updates to the payroll record.
  • Changed type of payroll_deadline field from Date to Timestamp to give a more accurate time to run payroll by to pay employees on time. payroll_deadline now returns the original payroll deadline when the payroll is late. If payroll has not been run by the deadline, a prepare request will update both the check date and deadline to reflect the soonest employees can be paid and the deadline by which the payroll must be run in order for said check date to be met.
  • The endpoint to update a payroll by start_date and end_date was removed. Please use Update Payroll by ID for all update requests going forward.
  • For the show payroll endpoint, the show_calculation param was removed and is no longer necessary to see payroll calculations. Also subsequent requests to the show endpoint will not clear out calculations as they used to. The version attribute was removed and will now be returned from the prepare endpoint. The employee_compensations and totals attributes were removed for unprocessed payrolls, they will still be there for calculated and processed payrolls.
  • check_date will no longer change when fetching unprocessed payrolls from the index or show endpoints, however the check date will be accurate if the payroll is not late. To get an accurate check_date for a late payroll you need to prepare/calculate/submit the payroll.
• Capitalize all off-cycle payroll reasons