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 associated to a user looks as follows (12345 needs to be substituted with the user’s ID):

Request URL

GET https://api.7shifts.com/v1/user/12345/wages

📘

NOTE

The parent endpoint here is spelt /user (without the ‘s’), and not /users.

Understanding the Wages Response

Now that you know how to make a basic request to retrieve wage data for a specific user, let’s explore some example responses:

Example Response 1

{
    "status": "success",
    "data": {
        "current": [
            {
                "effective_date": "2020-12-01",
                "user_id": 1199471,
                "role_id": null,
                "wage_type": "weekly_salary",
                "wage_cents": 120000
            },
            {
                "effective_date": "2019-10-28",
                "user_id": 1199471,
                "role_id": 144064,
                "wage_type": "hourly",
                "wage_cents": 3000
            }
        ],
        "upcoming": []
    },
    "message": ""
}

Example Response 2

{
    "status": "success",
    "data": {
        "current": [
            {
                "effective_date": "2020-12-24",
                "user_id": 1199304,
                "role_id": null,
                "wage_type": "hourly",
                "wage_cents": 1200
            },
            {
                "effective_date": "2020-12-24",
                "user_id": 1199304,
                "role_id": 157327,
                "wage_type": "hourly",
                "wage_cents": 1700
            },
            {
                "effective_date": "2020-12-24",
                "user_id": 1199304,
                "role_id": 157329,
                "wage_type": "hourly",
                "wage_cents": 1500
            }
        ],
        "upcoming": []
    },
    "message": ""
}

You’ll mostly be working with only a few fields in each user object in the response. Here are some details on them:

Parameter

Type

Description

effective_date

Date

Date that this wage object comes into effect. YYYY-mm-dd.

user_id

Integer

ID of the user that this wage object is for.

role_id

Integer

ID of the role that this wage object is for. May be set to null for weekly salaries and role-agnostic wages.

wage_type

String

May be set to weekly_salary for salaried users and hourly for hourly wage users.

wage_cents

Integer

Amount for the wage object in cents.

Finding the Current Wage Data

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 $1400. 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 is set to 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 on the /companies endpoint, and look at the boolean wage_based_roles field to find out whether the account has wage-based roles enabled or not:

GET https://api.7shifts.com/v1/companies

If wage_based_roles is set to 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 set to 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.


Did this page help you?