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:
| Query Parameter | Description | Notes |
|---|---|---|
from and to | Specify the start and end date for the report | It is recommended to use a maximum range of 1 or 2 week for the report. If you receive a 500 or 502 timeout error, try shortening the report time range. |
location_id | Location filter for the report | For most companies the report should be filtered by a location_id. When you don't specify a location_id the report fetches all the shifts or time_punches for every users in a company. This can take a significant amount of time and may result in a 500 or 502 timeout error. |
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:
| Value | Type | Description |
|---|---|---|
regular_hours | float | Regular hours worked. |
regular_pay | float | Regular pay in dollars. |
overtime_hours | float | Overtime hours worked. Will only apply if overtime is enabled for the company. |
overtime_pay | float | Overtime pay in dollars. Will only apply if overtime is enabled for the company. |
holiday_hours | float | Holiday hours worked. Will only apply if holidays are enabled for the company. Hours that are worked during Holidays will be included in the overtime calculation. |
holiday_pay | float | Holiday pay in dollars. Will only apply if holidays are enabled for the company. Hours that are worked during Holidays will be included in the overtime calculation. |
compliance_exceptions_pay | float | Compliance exception pay in dollars. Will only apply if compliance fees are enabled for eligible jurisdictions. |
total_hours | float | Total hours worked. |
total_pay | float | Total pay in dollars. |
total_tips | float | The total tip amount in dollars. |
cash_tips | float | Cash declared tips amount in dollars. Available on accounts with a POS integration that support cash tips. |
credit_card_tips | float | POS credit card tips amount in dollars. Available on accounts with a POS integration that support credit card tips. |
total_payment_tips | float | POS credit card tips amount in dollars. Available on accounts with a POS integration that support credit card tips. |
declared_tips | float | Declared tips amount in dollars. Available on accounts with a POS integration that support declared tips or 7punches enabled . |
auto_gratuity | float | Auto gratuity tip amount in dollars. Available on accounts with 7punches or with a POS integration that support auto gratuities. |
withheld_cc_amount | float | Amount reclaim from credit card tips. Only available when Tip Pooling is enabled and with a POS integration that support credit card tips. |
tip_in | float | The amount of tip contributed to a tip pool in dollars. Only available when Tip Pooling is enabled and the labor data is part of a tip pool. |
tip_out | float | The amount of tip received from a tip pool in dollars. Only available when Tip Pooling is enabled and the labor data is part of a tip pool. |
earned_tips | float | Calculated earned tip amount in dollars. The calculation is (( cash_tips + declared_tips + auto_gratuity + total_payment_tips) - withheld_cc_amount) - (tip_in + tip_out) |
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.
| Value | Type | Description |
|---|---|---|
week | date | The starting day of the week. |
salaried | bool | If true the labor data is for salaried work. If false the labor data if for hourly shifts. |
shifts | array | An array of detailed shift or time punch data . |
lone_compliance_exceptions | array | An array of compliance exceptions. |
total | dict | The aggregate sum of labor data for the week. See labor totals for a full description of the values. |
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.
| Value | Type | Description |
|---|---|---|
| role_id | int | The role_id. If the user has time punch without a assigned role it will display 0. |
| role_label | string | The role_label. If the user has time punch without an assigned role it will display No Role. |
| location_label | string | The name of the location for this role |
| total | dict | The aggregate sum of labor data for the user. See labor totals for a full description of the values. |
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.
| Value | Type | Description |
|---|---|---|
show_exception_costs | bool | If a company has enabled Compliance fees under labor & compliance settings this flag will be true. Certain jurisdictions like California, NY or DC 7shifts can calculate labor exceptions. |
tip_tracking_enabled | bool | If a company has enabled Declared Tips under time clocking settings this flag will be true. This setting allows employees to declare tips when punching out via 7punches or an integrated POS |
show_tips | bool | Always true. Designates if tip values will be included in the report. |
start | date | The start date of the report |
end | date | The end date of the report |
Updated almost 2 years ago