These docs are for v2.2022.0501. Click to read the latest docs for v2.2023.0501.

Read Employee Wage Data

This section focuses on:

  • Structure of GET requests to the /wages endpoint:
    • Get familiar with the request you need to make to read wage data for a particular user.
  • Understanding the /wages response:
    • Learn what the wage data in the response represents.
  • Finding the current wage data:
    • Figure out how to find out the true current wages for a given user.

GET Structure for /wages

Wage data for a specific user in 7shifts can be read through the /wages endpoint, one user at a time.

Please bear in mind that this may return multiple wage objects. Finding out which wage object denotes the true current wage for a user is further explained in Understanding the /wages Response.

An example GET request to the /wages endpoint to list wage objects for the user_id 1111

Request URL

curl --request GET --url 'https://api.7shifts.com/v2/company/1234/users/1111/wages'

Understanding the Wages Response

Example Response 1

{
    "data": {
        "current_wages": [
            {
                "id": 6494898,
                "effective_date": "2020-12-01",
                "role_id": null,
                "wage_type": "weekly_salary",
                "wage_cents": 120000,
                "created": "2020-12-01T15:32:23Z",
                "modified": "2020-12-01T15:32:23Z"
            },
            {
                "id": 6488058,
                "effective_date": "2019-10-28",
                "role_id": 1004823,
                "wage_type": "hourly",
                "wage_cents": 1700,
                "created": "2019-10-28T14:40:37Z",
                "modified": "2019-10-28T14:40:37Z"
            }
        ],
        "upcoming_wages": []
    },
    "object": "user_wages"
}

Example Response 2

{
    "data": {
        "current_wages": [
            {
                "id": 6494898,
                "effective_date": "2020-12-24",
                "role_id": null,
                "wage_type": "hourly",
                "wage_cents": 1200,
                "created": "2020-12-24T15:32:23Z",
                "modified": "2020-12-24T15:32:23Z"
            },
            {
                "id": 6488058,
                "effective_date": "2020-12-24",
                "role_id": 1004823,
                "wage_type": "hourly",
                "wage_cents": 1700,
                "created": "2020-12-24T14:40:37Z",
                "modified": "2020-12-24T14:40:37Z"
            },
            {
                "id": 6488059,
                "effective_date": "2020-12-24",
                "role_id": 1004835,
                "wage_type": "hourly",
                "wage_cents": 1500,
                "created": "2020-12-24T14:40:37Z",
                "modified": "2020-12-24T14:40:37Z"
            }
        ],
        "upcoming_wages": []
    },
    "object": "user_wages"
}

Here’s an explanation of each of the fields in the response body.

ParameterTypeDescription
effective_datedateDate that this wage object comes into effect. YYYY-mm-dd.
role_idintegerID of the role that this wage object is for. May be set to null for weekly salaries and role-agnostic wages.
wage_typestringMay be set to weekly_salary for salaried users and hourly for hourly wage users.
wage_centsIntegerAmount for the wage object in cents.

Finding the Current Wage Data

1576

Here are the detailed steps on determining the most current wage data:

Weekly Salary or Hourly Wage?

Let’s look at Example Response 1 first — notice that there are multiple wage objects in the response.

The first thing you need to check for is whether the user in question has been assigned a weekly salary or an hourly wage. The way to check this is to look for the wage object in the current array with the most recent effective_date and looking at the wage_type field.

If wage_type is set to weekly_salary, then you can assume that this user has a weekly salary in 7shifts. This means that regardless of a user being scheduled for a shift or having a time punch in 7shifts, they will be getting paid this amount (in cents) for the current week.

Please note that running the Worked Hours & Wages report in 7shifts splits the wage_cents amount for wage_type = weekly_salary between every assigned department, and then splits it into 7 equal parts for each day.

For example, John Smith is assigned to Front of House & Back of House departments, and has a weekly salary of $1,400. If you were to run the report for Front of House with just a one-day time range, the report would show the labor cost as $1400/2 depts/7 days = $100.

If wage_type value is hourly for the most recent effective_date wage object, go on to step 2.

Role-Agnostic Wage or Per-Role Wages?

You can make the following request /companies/labor_settings endpoint and look at the parameter wage_based_roles_enabled field to find out whether the account has wage-based roles enabled or not:

curl --request GET --url 'https://api.7shifts.com/v2/company/1234/labor_settings'

If wage_based_roles_enabled is false, it means that there’s just one wage for the user, regardless of what role the user is assigned to. In that case, you should look for the wage object in the /wages response with the most recent effective_date that has the role_id as null like the first wage object in Example Response 2).

Get Wage for each Role

If wage_based_roles is true, it means there’s a different wage for each role that the user is assigned to. In that case, look for the most recent effective_date field and read the wage_cents field in each of the role_ids that the user is assigned to like the second & third wage objects in Example Response 2)

Please note that the /wages response may contain objects for wages that are for roles that the user is no longer assigned to or for different 7shifts accounts. You do not need to worry about these, as long as the above logic is being followed.