Hours & Wages Report

The Hours & Wages report endpoint provides summarized labor data including the amount of time scheduled/worked, earned wages. You are able to specify the report type to use scheduled labor data (scheduled shifts) or actual labor data (time punches). Time punch data are recorded via 7punches or POS integrated data. Additionally, the reports can also include:

• Detailed shift data
• Compliance data
• Tip data

🚧

Plan Restricted Endpoint

The user of this endpoint is restricted to The Works or higher 7shifts plan. Please reference the plan requirements guide for more information.

Specifying the Report Type

The report can either return data based the scheduled hours or the worked hours.

When punches is set to false the report will use scheduled data and return schedule hours and the expected wages. The report payload will be similar to the Scheduled Hours & Wages report that can be found in the Reports section of the 7shifts app.

When punches is set to true the report will use punch data from 7punches or a POS labor data and return worked hours & wages. The report payload will be similar to the Worked Hours & Wages report that can be found in the Reports section of the 7shifts app.

Requests Best Practices

The Hours & Wages report endpoint allows you to run reports across an entire company and for an unlimited time range, although in most cases this request will require a signifiant time to process and you will receive a 500 or 502 time out error. HTTP requests have a maximum time of 30 seconds to complete execution. Add filters (query parameters) to your request to constrain the data fetched by the report and ensure that you can receive the data within 30 seconds.

Use the following filter best practices:

Here's an example GET request to the /reports/hours_and_wages endpoint:

curl --request GET --url 'https://api.7shifts.com/v2/reports/hours_and_wages?company_id=1234&from=2022-12-01&to=2022-12-07&location_id=7890'

Report Data

The report data is structured the same for both the scheduled and worked hours & wages report. The report includes:

• An array of user objects. Each user object includes aggregated and detailed labor information.
• Report total. A dictionary of aggregated labor information for the report.
• Report settings that describe the parameters used to generate the report

Each section includes a labor total that is the aggregate of all the hours and wages for each section.

Below is a high level diagram of the report sections

Labor Totals

Each section of the report includes labor totals, which are the aggregates sum of all the hours, wages. Below is a description and sources of each of the values in the totals:

NOTE: To use the tip values in this report it is recommended to discuss with the restaurant operator how tips are gathered and calculated. The declared_tips can vary between restaurant depending on what this value represents. For example declared_tips in one restaurant can include all the cash tips collected but also taken home, and are only recorded for tax purposes. In another restaurant that uses tip pooling declared_tips may include only cash tips that are used in tip pools. This means 7shifts does not record any distributed/take home values in our calculations. This will affect the earned_tips value across restaurants, depending on their process.

Additionally, the values may be different before and after tip pools are run. It is recommended to be aware into tip pools to better understand these values.

Example totals payload:

"total": {
    "regular_hours": 47,
    "regular_pay": 129,
    "overtime_hours": 11.98,
    "overtime_pay": 74.55,
    "holiday_hours": 0,
    "holiday_pay": 0,
    "compliance_exceptions_pay": 0,
    "total_hours": 58.98,
    "total_pay": 203.55,
    "total_tips": 61.78,
    "cash_tips": 227.14,
    "credit_card_tips": 0,
    "total_payment_tips": 0,
    "pos_declared_tips": 61.78,
    "auto_gratuity": 0,
    "withheld_cc_amount": 0,
    "tip_in": 0,
    "tip_out": 0,
    "earned_tips": 61.78,
    "seven_punches_declared_tips": 61.78
},

User Objects

The user object contains detailed labor information for a user and include the following sections:

• User information object. Identity information about the user.
• Weeks data. An array of labor data broken out by week, and contains the shifts or time punches part of that week.
• Roles. An array of labor data broken out by roles, and contains the aggregate labor totals.
• User totals. The aggregate labor totals, this is the sum all the hours, wages and tip values for the user. See labor totals for a full description of the values.

NOTE the users object also contains a salaried property. If the value is true then the user has a salaried wage type. If the value is false the user has an hourly wage type.

Weeks Data

The weeks data includes an array of detailed labor data grouped per week. Each week data structure includes the detailed shift or time punch information for the user.

Example weeks payload:

"weeks": [
    {
        "week": "2022-12-04",
        "salaried": false,
        "shifts": [
            {
                "user_id": 1234,
                "date": "2022-12-06 08:56:00",
                "week_label": "2022-12-04",
                "day_label": "Dec 6",
                "label": "8:56AM - 2:00PM",
                "breaks": [],
                "location_id": 7890,
                "location_label": "Restaurant",
                "role_id": 5555,
                "role_label": "Server",
                "wage": 12,
                "status": 0,
                "salaried": false,
                "compliance_exceptions": [],
                "total": {
                    "regular_hours": 5.07,
                    "regular_pay": 0,
                    "overtime_hours": 0,
                    "overtime_pay": 0,
                    "holiday_hours": 0,
                    "holiday_pay": 0,
                    "compliance_exceptions_pay": 0,
                    "total_hours": 5.07,
                    "total_pay": 60.84,
                    "total_tips": 0,
                    "cash_tips": 40.64,
                    "credit_card_tips": 0,
                    "total_payment_tips": 0,
                    "pos_declared_tips": 0,
                    "auto_gratuity": 0,
                    "withheld_cc_amount": 0,
                    "tip_in": 0,
                    "tip_out": 0,
                    "earned_tips": 0,
                    "seven_punches_declared_tips": 0
                }
            }
        ],
        "lone_compliance_exceptions": [],
        "total": {
            "regular_hours": 5.07,
            "regular_pay": 0,
            "overtime_hours": 0,
            "overtime_pay": 0,
            "holiday_hours": 0,
            "holiday_pay": 0,
            "compliance_exceptions_pay": 0,
            "total_hours": 0,
            "total_pay": 60.84,
            "total_tips": 0,
            "cash_tips": 40.64,
            "credit_card_tips": 0,
            "total_payment_tips": 0,
            "pos_declared_tips": 0,
            "auto_gratuity": 0,
            "withheld_cc_amount": 0,
            "tip_in": 0,
            "tip_out": 0,
            "earned_tips": 0,
            "seven_punches_declared_tips": 0
        }
    }
],

Roles

The roles data includes an array of detailed labor data grouped by role. Each role data structure includes the labor total information for the user.

User Totals

The user totals is the aggregate sum of all labor data for the user. See labor totals for a full description of the values.

Report Settings

The following values can give you additional context on how the report was generated.