Update Time Punch Data

Now that a time punch has been created when the employee clocked in, all subsequent actions require updating the time punch, i.e., making PUT requests to /time_punches.

This section focuses on making PUT requests for:

  • Employee going on a break
  • Employee returning from a break
  • Employee going on another break & returning
  • Employee clocking out

Employee going on a break

A PUT request needs to be made to update the existing time punch with break info as soon as an employee goes on a break. Here’s an example PUT request where we update the time punch created in the previous POST request with break data, by using the time punch ID we received from the response.

An employee may take multiple breaks during a shift. As a result, breaks are specified within a breaks object array in the request body to allow specifying multiple breaks.

Request URL

PUT https://api.7shifts.com/v1/time_punches/1357924680

Request body

{
    "time_punch": {
        "date": "2020-07-31",
        "clocked_in": "08:00:00",
        "breaks": [{
                "in": "12:00:00",
                "paid": false
        }]
    }
}

Response

{
    "status": "success",
    "data": {
        "time_punch": {
            "id": 1357924680
        }
    },
    "message": "Punch has been saved"
}

Here’s an explanation of each of the new fields required in the request body:

Parameter

Type

Description

breaks

Array

Array to specify break objects for each break that the employee takes.

breaks.in

Text/Time

The local time that the employee started their break (format: HH:ii:ss).

breaks.paid

Boolean

Specifies whether the break is paid or unpaid.

📘

NOTE

  • The date & clocked_in fields should have the same values that were used in the original POST request to create the punch.
  • The paid field in each object in the breaks object array specifies whether the employee is supposed to get paid for the break or not. This is something that you could set up as an integration setting within your system to allow an admin/manager to decide whether breaks should be paid or unpaid.

You could also make this setting allow both types of breaks, and then present a modal to the employee going out on a break asking whether they are taking a paid or an unpaid break. This completely depends on how mutual clients would want to handle breaks, and you can implement the setting logic accordingly.

Employee returning from a break

When the employee returns from a break, you need to make a similar PUT request as the previous one while adding a breaks.out field.

Request URL

PUT https://api.7shifts.com/v1/time_punches/1357924680

Request body

{
    "time_punch": {
        "date": "2020-07-31",
        "clocked_in": "08:00:00",
        "breaks": [
            {
        "in": "12:00:00",
                "out": "12:30:00",
                "paid": false
            }
    ]
    }
}

Response

{
    "status": "success",
    "data": {
        "time_punch": {
            "id": 1357924680
        }
    },
    "message": "Punch has been saved"
}

Here’s an explanation of the new field required in this request body:

Type

Field

Description

breaks.out

Text/Time

The local time that the employee returns from their break

📘

NOTE

  • The date, clocked_in, breaks.in, breaks.paid fields must have the same value as the previous PUT request made when the employee started their break.

Employees should not be allowed to start another break if they haven’t returned from their previous break yet, i.e., if breaks.out can’t be empty for any break and needs to have a time set before you create another break object for the employee.

Employee taking another break

When employees take multiple breaks, each break needs to be represented by a separate break object in the breaks object array.

For every PUT request made to the endpoint for updating break info, all previous breaks associated with the time punch being updated will need to be specified as well. Not specifying previous breaks causes them to be overwritten and deleted.

Here’s an example request body showing that the employee has gone on a second break, following the break from the previous requests:

Request URL

PUT https://api.7shifts.com/v1/time_punches/1357924680

Request body

{
    "time_punch": {
        "date": "2020-07-31",
        "clocked_in": "08:00:00",
        "breaks": [
            {
                "in": "12:00:00",
                "out": "12:30:00",
                "paid": false
            },
            {
                "in": "14:00:00",
                "paid": true
            }
    ]
    }
}

As you can see, the first break has been specified, along with the second break. Also, different breaks can have different paid boolean values, based on your paid/unpaid breaks setting logic.

Similarly, when the employee returns from this second break, the request should look as follows:

Request body

{
    "time_punch": {
        "date": "2020-07-31",
        "clocked_in": "08:00:00",
        "breaks": [
            {
                "in": "12:00:00",
                "out": "12:30:00",
                "paid": false
            },
            {
                "in": "14:00:00",
                "out": "14:15:00",
                "paid": true
            }
    ]
    }
}

Employee clocking out

Lastly, at the end of the shift, when the employee performs a clock out action in your system, a final PUT request needs to be made to update the punch with the clocked_out time. Before making this request, you must ensure that each of the breaks associated to the punch has a breaks.out time.

The request would look as follows:

Request URL

PUT https://api.7shifts.com/v1/time_punches/1357924680

Request body

{
    "time_punch": {
        "date": "2020-07-31",
        "clocked_in": "08:00:00",
        "clocked_out": "16:00:00"
    }
}

Response

{
    "status": "success",
    "data": {
        "time_punch": {
            "id": 1357924680
        }
    },
    "message": "Punch has been saved"
}

Here’s an explanation of the new field required in the request body:

Field

Type

Description

clocked_out

Text/Time

The local time that the user clocked out at (format: HH:MM:SS).

Adding tips?

Do employees declare their cash tips upon clocking out of their shift in your system? You can send that cash tips data to 7shifts as well by adding a tips field (positive float value, 2 decimals) in the clock-out PUT request as follows:

Request body

{
    "time_punch": {
        "date": "2020-07-31",
        "clocked_in": "08:00:00",
        "clocked_out": "16:00:00",
        "tips": 32.50
    }
}

Do employees write a note upon clocking out of their shift in your system? You can send the note to 7shifts as well by adding a notes field (medium text field) in the clock-out PUT request as follows:

Request body

{
    "time_punch": {
        "date": "2020-07-31",
        "clocked_in": "08:00:00",
        "clocked_out": "16:00:00",
        "notes": "Lorem ipsum dolor sit amet"
    }
}

Did this page help you?