Added Payroll by Workweek support for earning types, pay schedules, and payrolls

We've added Payroll by Workweek support across the earning types, pay schedules, and payrolls APIs. Workweek breakdowns are the input Gusto uses to calculate overtime pay accurately for nonexempt employees under the Fair Labor Standards Act (FLSA). Read more in our Payroll by Workweek guide.

Why this matters

Overtime pay is calculated on a per-workweek basis, not per pay period. For a nonexempt employee who works overtime, the hours and earnings that count toward their overtime premium depend on which workweek each item belongs to. Payroll by Workweek adds the fields partners need to supply, read, and reflect that per-workweek data on the Partner API.

Key functionality

• Earning types gain category and included_in_overtime_pay. When creating a custom earning type with POST earning_types, you specify a category (one of Commission, DiscretionaryBonus, ServiceCharges, OnCallPay, or Other). For every category except Other, overtime treatment is fixed and included_in_overtime_pay is set automatically. For Other, you set it explicitly. Both fields are immutable after creation.
  • Affected endpoints:
    • POST /v1/companies/{company_uuid}/earning_types
    • GET /v1/companies/{company_uuid}/earning_types
• Pay schedules gain workweek_start_day. Weekly and biweekly schedules now carry a workweek_start_day on reads and writes. The field can only be changed once per pay period.
  • Affected endpoints:
    • GET /v1/companies/{company_uuid}/pay_schedules/{pay_schedule_uuid}
    • POST /v1/companies/{company_uuid}/pay_schedules
    • PUT /v1/companies/{company_uuid}/pay_schedules/{pay_schedule_uuid}
• Payrolls gain workweek breakdowns. fixed_compensations and hourly_compensations entries accept a breakdowns array specifying how much of each earning applies to each workweek. Unprocessed payroll responses from prepare, create, and update also include a top-level workweeks array listing each workweek's date range within the pay period.
  • Affected endpoints:
    • PUT /v1/companies/{company_uuid}/payrolls/{payroll_uuid}/prepare
    • PUT /v1/companies/{company_uuid}/payrolls/{payroll_uuid}/update
    • POST /v1/companies/{company_uuid}/payrolls
    • GET /v1/companies/{company_uuid}/payrolls/{payroll_uuid}
• Payroll gross_pay is now returned on unprocessed responses. Previously gross_pay was only available on processed payrolls—it now appears on prepare, create, and update so you can read an estimated total while building.
  • Affected endpoints:
    • PUT /v1/companies/{company_uuid}/payrolls/{payroll_uuid}/prepare
    • PUT /v1/companies/{company_uuid}/payrolls/{payroll_uuid}/update
    • POST /v1/companies/{company_uuid}/payrolls
• Processed show responses include pay_adjustments. pay_adjustments is a new per-employee array reflecting overtime premium corrections carried over from a previous workweek.
  • Affected endpoints: GET /v1/companies/{company_uuid}/payrolls/{payroll_uuid}

Read more in the Payroll by Workweek guide.