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
curl --request --url PUT 'https://api.7shifts.com/v2/company/1234/time_punches/1'
Request body
{
"clocked_in": "2022-01-31T16:00:00Z",
"breaks": [
{
"in": "2022-01-31T18:00:00Z",
"paid": false
}
]
}
}
Response
{
"data": {
"id": 1,
"company_id": 1234,
"shift_id": 0,
"user_id": 1111,
"editable_punch": true,
"role_id": 7410,
"location_id": 7890,
"department_id": 3698,
"hourly_wage": 15,
"approved": false,
"clocked_in": "2022-01-31T16:00:00Z",
"clocked_out": null,
"notes": "",
"auto_clocked_out": false,
"clocked_in_offline": false,
"clocked_out_offline": false,
"tips": 0,
"created": "2022-01-31T168:00:00Z",
"modified": "2022-01-31T18:00:00Z",
"deleted": false,
"pos_type": "web",
"breaks": [
{
"id": 9876,
"user_id": 1111,
"custom_break_id": 0,
"in": "2022-01-31T18:00:00Z",
"out": null,
"paid": false,
"deleted": false
}
]
},
"object": "time_punch"
}
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 | datetime | The time that the employee started their break. UTC in ISO8601 format (format: YYYY-MM-DDTHH:mm:SS) |
| breaks.paid | boolean | Specifies whether the break is paid or unpaid. |
NOTE
- The 'date' & 'clocked_in fields' should have the same values 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
curl --request PUT --url 'https://api.7shifts.com/v2/company/1234/time_punches/1'
Request body
{
"clocked_in": "2022-01-31T16:00:00",
"breaks": [
{
"in": "2022-01-31T18:00:00Z",
"out": "2022-01-31T18:30:00Z",
"paid": false
}
]
}
}
Response
{
"data": {
"id": 1,
"company_id": 1234,
"shift_id": 0,
"user_id": 1111,
"editable_punch": true,
"role_id": 7410,
"location_id": 7890,
"department_id": 3698,
"hourly_wage": 15,
"approved": false,
"clocked_in": "2022-01-31T16:00:00Z",
"clocked_out": null,
"notes": "",
"auto_clocked_out": false,
"clocked_in_offline": false,
"clocked_out_offline": false,
"tips": 0,
"created": "2022-01-31T16:00:00Z",
"modified": "2022-01-31T18:30:00Z",
"deleted": false,
"pos_type": "web",
"breaks": [
{
"id": 9876,
"user_id": 1111,
"custom_break_id": 0,
"in": "2022-01-31T18:00:00Z",
"out": "2022-01-31T18:30:00Z",
"paid": false,
"deleted": false
}
]
},
"object": "time_punch"
}
Here’s an explanation of the new field required in this request body:
| Type | Field | Description |
|---|---|---|
| breaks.out | datetime | The time that the employee returns from their break. UTC in ISO8601 format (format: YYYY-MM-DDTHH:mm:SS) |
NOTE
- The '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
curl --request PUT --url 'https://api.7shifts.com/v2/company/1234/time_punches/1'
Request body
{
"clocked_in": "2022-01-31T16:00:00",
"breaks": [
{
"in": "2022-01-31T18:00:00",
"out": "2022-01-31T18:30:00",
"paid": false
},
"in": "2022-01-31T20: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
{
"clocked_in": "2022-01-31T16:00:00Z",
"breaks": [
{
"in": "2022-01-31T18:00:00Z",
"out": "2022-01-31T18:30:00Z",
"paid": false
},
{
"in": "2022-01-31T20:00:00Z",
"out": "2022-01-31T20:15:00Z",
"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
curl --request PUT --url 'https://api.7shifts.com/v2/company/1234/time_punches/1'
Request body
{
"clocked_in": "2022-01-31T16:00:00Z",
"clocked_out": "2022-01-31T22:00:00Z",
}
Response
{
"data": {
"id": 1,
"company_id": 1234,
"shift_id": 0,
"user_id": 1111,
"editable_punch": true,
"role_id": 7410,
"location_id": 7890,
"department_id": 3698,
"hourly_wage": 15,
"approved": false,
"clocked_in": "2022-01-31T16:00:00Z",
"clocked_out": "2022-01-31T22:00:00Z",
"notes": "",
"auto_clocked_out": false,
"clocked_in_offline": false,
"clocked_out_offline": false,
"tips": 0,
"created": "2022-01-31T16:00:00Z",
"modified": "2022-01-31T22:30:00Z",
"deleted": false,
"pos_type": "web",
"breaks": [
{
"id": 9876,
"user_id": 1111,
"custom_break_id": 0,
"in": "2022-01-31T18:00:00Z",
"out": "2022-01-31T18:30:00Z",
"paid": false,
"deleted": false
},
{
"id": 9900,
"user_id": 1111,
"custom_break_id": 0,
"in": "2022-01-31T20:00:00Z",
"out": "2022-01-31T20:15:00Z",
"paid": true,
"deleted": false
}
]
},
"object": "time_punch"
}
Here’s an explanation of the new field required in the request body:
| Field | Type | Description |
|---|---|---|
| clocked_out | datetime | 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 (integer value in cents) in the clock-out PUT request as follows:
Request body
{
"clocked_in": "2022-01-31T16:00:00Z",
"clocked_out": "2022-01-31T22:00:00Z",
"tips": 1000
}
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 in the clock-out PUT request as follows:
Request body
{
"clocked_in": "2022-01-31T16:00:00Z",
"clocked_out": "2022-01-31T22:00:00Z",
"notes": "Notes entered about shift"
}
Updated over 1 year ago