---
title: "Retrieve Worked Hours and Wages"
method: GET
path: "/v2/reports/hours_and_wages"
tags: ["Reports"]
---

# Retrieve Worked Hours and Wages

`GET /v2/reports/hours_and_wages`

## Request

- Base URL: `https://api.7shifts.com`
- URL: `https://api.7shifts.com/v2/reports/hours_and_wages`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://app.7shifts.com/oauth2/authorize`
    - Client credentials
    - Password
    - Token URL: `https://app.7shifts.com/oauth2/token`
  - API key in cookie `7session`
- TypeScript: <https://skmtc.dev/7shifts/apis/7shifts-api/docs/v2/reports/hours_and_wages/get.ts> (a function with typed inputs; its response is checked against the schema)

## Query parameters

- `punches` boolean, required
- `company_id` integer, required
- `from` string, required
- `to` string, required
- `location_id` integer
- `department_id` integer
- `role_id` integer
- `user_id` integer
- `include_tips` boolean, nullable
- `include_qualified_ot` boolean, nullable

## Headers

- `x-api-version` string: An API version
- `x-company-guid` string, uuid

## Response `200`

OK

- object
  - `users` object[], required: Report data for each employee
    - `user` object: Employee info
      - `id` number: User ID
      - `employee_id` string: Employee payroll ID
      - `first_name` string: First name
      - `last_name` string: Last name
    - `weeks` object[]: Report data for each work week
      - `week` string: Work week (first day of week)
      - `salaried` boolean: Whether employee is salaried during the entire week
      - `shifts` object[]: Report data for each shift or time punch
        - `user_id` number: User ID
        - `date` string: Date and time the shift or time punch started on
        - `week_label` string: Work week the shift or time punch occurred in
        - `day_label` string: Formatted day the shift or time punch started on
        - `label` string: Start and end times of shift or time punch
        - `breaks` string[]: Breaks
        - `location_id` number: Location ID
        - `location_label` string: Location name
        - `role_id` number: Role ID
        - `role_label` string: Role name
        - `wage` number: Hourly wage
        - `status` number: Shift flag (late, no-show, sick)
        - `salaried` boolean: Whether the employee was salaried during this shift
        - `compliance_exceptions` object[]: Compliance exceptions for the shift
          - `date` string: Exception date
          - `violation_type` string: Violation type of this exception
          - `cost` number: The cost of this exception (in dollars)
        - `total` object: Hours and pay info for a shift or group of shifts
          - `regular_hours` number, required: Regular hours
          - `regular_pay` number, required: Regular pay
          - `overtime_hours` number, required: Overtime hours
          - `premium_overtime_hours` number: Premium / Double overtime hours
          - `non_premium_overtime_hours` number: Daily + Weekly + Consecutive overtime hours
          - `overtime_pay` number, required: Overtime pay
          - `premium_overtime_pay` number: Premium / Double overtime pay
          - `non_premium_overtime_pay` number: Daily + Weekly + Consecutive overtime pay
          - `holiday_hours` number, required: Holiday hours
          - `holiday_pay` number, required: Holiday pay
          - `compliance_exceptions_pay` number, required: Compliance exceptions pay
          - `total_hours` number, required: Total hours
          - `qualified_ot_premium` string, required: Qualified overtime earned
          - `total_pay` number, required: Total pay
          - `total_tips` number, required: Tips declared by employee through 7punches
          - `cash_tips` number, required: Cash tips
          - `credit_card_tips` number, required: Credit card tips
          - `total_payment_tips` number, required: DEPRECATED - same value as credit_card_tips
          - `declared_tips` number, required: Declared tips either from 7punches or POS
          - `pos_declared_tips` number: Declared tips from POS
          - `auto_gratuity` number, required: Autogratuity
          - `withheld_cc_amount` number, required: Withheld CC amount
          - `tip_in` number, required: Tip in amount
          - `tip_out` number, required: Tip out amount
          - `earned_tips` number, required: Earned Tips
          - `tips_paid` number, required: Tips that have been paid by employer
          - `tips_paid_on_shift` number, required: Tips that have been paid on shift
          - `tips_paid_on_payouts` number, nullable: Tips that have been paid through tip payouts
          - `tips_to_be_paid` number, required: Tips owed that have not been paid by employer
      - `lone_compliance_exceptions` object[]: Compliance exceptions that aren't associated with any shift or time punch
    - `roles` object[]: Hours and pay totals for each role the employee worked
      - `role_id` number: Role ID
      - `role_label` string: Role name
      - `total` object: Hours and pay info for a shift or group of shifts
        - `regular_hours` number, required: Regular hours
        - `regular_pay` number, required: Regular pay
        - `overtime_hours` number, required: Overtime hours
        - `premium_overtime_hours` number: Premium / Double overtime hours
        - `non_premium_overtime_hours` number: Daily + Weekly + Consecutive overtime hours
        - `overtime_pay` number, required: Overtime pay
        - `premium_overtime_pay` number: Premium / Double overtime pay
        - `non_premium_overtime_pay` number: Daily + Weekly + Consecutive overtime pay
        - `holiday_hours` number, required: Holiday hours
        - `holiday_pay` number, required: Holiday pay
        - `compliance_exceptions_pay` number, required: Compliance exceptions pay
        - `total_hours` number, required: Total hours
        - `total_pay` number, required: Total pay
        - `qualified_ot_premium` string, required: Qualified overtime earned
        - `total_tips` number, required: Tips declared by employee through 7punches
        - `cash_tips` number, required: Cash tips
        - `credit_card_tips` number, required: Credit card tips
        - `total_payment_tips` number, required: DEPRECATED - same value as credit_card_tips
        - `declared_tips` number, required: Declared tips either from 7punches or POS
        - `pos_declared_tips` number: Declared tips from POS
        - `auto_gratuity` number, required: Autogratuity
        - `withheld_cc_amount` number, required: Withheld CC amount
        - `tip_in` number, required: Tip in amount
        - `tip_out` number, required: Tip out amount
        - `earned_tips` number, required: Earned Tips
        - `tips_paid` number, required: Tips that have been paid by employer
        - `tips_paid_on_shift` number, required: Tips that have been paid on shift
        - `tips_paid_on_payouts` number, nullable: Tips that have been paid through tip payouts
        - `tips_to_be_paid` number, required: Tips owed that have not been paid by employer
      - `location_label` string: Location name
    - `total` object: Hours and pay info for a shift or group of shifts
      - `regular_hours` number, required: Regular hours
      - `regular_pay` number, required: Regular pay
      - `overtime_hours` number, required: Overtime hours
      - `premium_overtime_hours` number: Premium / Double overtime hours
      - `non_premium_overtime_hours` number: Daily + Weekly + Consecutive overtime hours
      - `overtime_pay` number, required: Overtime pay
      - `premium_overtime_pay` number: Premium / Double overtime pay
      - `non_premium_overtime_pay` number: Daily + Weekly + Consecutive overtime pay
      - `holiday_hours` number, required: Holiday hours
      - `holiday_pay` number, required: Holiday pay
      - `compliance_exceptions_pay` number, required: Compliance exceptions pay
      - `total_hours` number, required: Total hours
      - `total_pay` number, required: Total pay
      - `total_tips` number, required: Tips declared by employee through 7punches
      - `cash_tips` number, required: Cash tips
      - `credit_card_tips` number, required: Credit card tips
      - `total_payment_tips` number, required: DEPRECATED - same value as credit_card_tips
      - `declared_tips` number, required: Declared tips either from 7punches or POS
      - `pos_declared_tips` number: Declared tips from POS
      - `auto_gratuity` number, required: Autogratuity
      - `withheld_cc_amount` number, required: Withheld CC amount
      - `tip_in` number, required: Tip in amount
      - `tip_out` number, required: Tip out amount
      - `earned_tips` number, required: Earned Tips
      - `tips_paid` number, required: Tips that have been paid by employer
      - `tips_paid_on_shift` number, required: Tips that have been paid on shift
      - `tips_paid_on_payouts` number, nullable: Tips that have been paid through tip payouts
      - `tips_to_be_paid` number, required: Tips owed that have not been paid by employer
    - `salaried` boolean: Whether employee is salaried during the entire date range of the report
  - `show_exception_costs` boolean, required: Whether compliance exceptions and their costs should be shown
  - `tip_tracking_enabled` boolean, required: Whether tips from integrations should be shown
  - `show_tips` boolean, required: Whether we should render the tips column
  - `total` object, required: Hours and pay info for a shift or group of shifts
    - `regular_hours` number, required: Regular hours
    - `regular_pay` number, required: Regular pay
    - `overtime_hours` number, required: Overtime hours
    - `premium_overtime_hours` number: Premium / Double overtime hours
    - `non_premium_overtime_hours` number: Daily + Weekly + Consecutive overtime hours
    - `overtime_pay` number, required: Overtime pay
    - `premium_overtime_pay` number: Premium / Double overtime pay
    - `non_premium_overtime_pay` number: Daily + Weekly + Consecutive overtime pay
    - `holiday_hours` number, required: Holiday hours
    - `holiday_pay` number, required: Holiday pay
    - `compliance_exceptions_pay` number, required: Compliance exceptions pay
    - `total_hours` number, required: Total hours
    - `total_pay` number, required: Total pay
    - `total_tips` number, required: Tips declared by employee through 7punches
    - `cash_tips` number, required: Cash tips
    - `credit_card_tips` number, required: Credit card tips
    - `total_payment_tips` number, required: DEPRECATED - same value as credit_card_tips
    - `declared_tips` number, required: Declared tips either from 7punches or POS
    - `pos_declared_tips` number: Declared tips from POS
    - `auto_gratuity` number, required: Autogratuity
    - `withheld_cc_amount` number, required: Withheld CC amount
    - `tip_in` number, required: Tip in amount
    - `tip_out` number, required: Tip out amount
    - `earned_tips` number, required: Earned Tips
    - `tips_paid` number, required: Tips that have been paid by employer
    - `tips_paid_on_shift` number, required: Tips that have been paid on shift
    - `tips_paid_on_payouts` number, nullable: Tips that have been paid through tip payouts
    - `tips_to_be_paid` number, required: Tips owed that have not been paid by employer
  - `start` string, date, required: Start date of report date range
  - `end` string, date, required: End date of report date range

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `500`: Internal Server Error

## Changes

- **2026-11-03** `40e0ef40dfcd`: 2 info
  - added the required property `users/items/roles/items/total/qualified_ot_premium` to the response with the `200` status
  - added the required property `users/items/weeks/items/shifts/items/total/qualified_ot_premium` to the response with the `200` status

[Operation history](https://skmtc.dev/7shifts/apis/7shifts-api/changes/v2/reports/hours_and_wages/get.md)

---

[API](https://skmtc.dev/7shifts/apis/7shifts-api.md) - [All operations](https://skmtc.dev/7shifts/apis/7shifts-api/llms.txt) - [OpenAPI document](https://skmtc.dev/7shifts/apis/7shifts-api/revisions/40e0ef40dfcd?raw)