Time tracking
Manage time tracking shifts for Global Payroll employees using the time tracking API
With the time tracking API, you can manage the time worked by employees, and add, update, retrieve and delete their shifts.
The time tracking API only works for Global Payroll.
Independent contractors use timesheets to track their time. For more information, see Timesheets.
Before managing shifts, note the following:
Shifts are linked to contracts. Retrieve the contract ID from the GET list of contracts endpoint.
Shifts are processed and compensated at the end of each payroll cycle. For more information, see Shifts and payroll cycles.
Shifts submitted for a past payroll cycle are compensated at the end of the current cycle without date validation.
Shifts are compensated based on the shift rate and the worker’s hourly base salary.
Shifts can be submitted in two formats:
Shifts with known pay codes and rates defined in Deel.
Granular shifts capturing start time, end time, and break information.
Categorized shifts are suited for when shifts are categorized outside Deel and the shift rates (pay codes/category) are known. To use this API, you must first create shift rates in Deel and then reference those shift rates when submitting categorized shifts.
Following is an example of a categorized shift:
Uncategorized shifts are used to capture the shift information in a more granular way. Unlike categorized shifts, which capture summary information such as total hours worked, uncategorized shifts capture granular start time, end time, and break information. There is no need to set up a shift rate for uncategorized shifts.
When you submit a shift, the shift is automatically associated to the relevant payroll cycle based on the submission timestamp and the cycle’s cutoff date. The cutoff date is the last day for the manager to approve the submitted shifts to be processed within the current payroll cycle.
The payroll calendar is configured per entity by your Deel representative when you onboard. That is when you decide the cutoff dates. If you have questions about your cutoff dates, contact your Deel representative. For more information, see Understanding the Deel Global Payroll Calendar.
Contact support for late shift submissions
If the payroll cutoff date has already passed and waiting for the next cycle for the shift to be processed is not an option for you, you can contact support to process the shift in a special off-cycle payroll run. Off-cycle payroll runs have an additional fee that depends on your contract agreement.
Make sure to provide the shift details via a CSV file through the support channel.
payroll_cycle_ref.dateTo avoid accidental late submissions that result in a shift being processed in the next cycle, you can include the optional payroll_cycle_ref.date parameter when submitting a shift. This parameter ensures that the shift is only associated with the specified cycle if the submission is timely, avoiding shifts being unintentionally pushed to the next payroll cycle.
When you pass a payroll_cycle_ref.date, you’re declaring your intended payroll cycle for the shift. The system compares the request’s timestamp with the cycle’s cutoff date and checks whether the current submission falls within the specified cycle.
This validation ensures that the shift is only associated with the specified cycle if the submission is timely.
Without the payroll_cycle_ref.date parameter, the system automatically determines the cycle based on the submission time — which may lead to late shifts being silently pushed to the next cycle. Use this parameter when you want explicit alignment with a particular payroll cycle.
The following example shows how to use the payroll_cycle_ref.date parameter:
The payroll_cycle_ref.date follows the ISO 8601 date and time format. You can use any date within the cycle’s start and end dates, but we recommend using the cycle’s end date for clarity.
This section covers how to add, update, and delete shifts for an employee.
This section covers how to add shifts for an employee. There are different endpoints available for adding shifts based on the shift type:
Add shifts with known pay codes and rates.
Legacy method (not recommended).
Add granular shifts with detailed time information.
You can add multiple categorized shifts for a single contract by providing an array of shifts. You can add a shift using any of the following time units: HOUR , DAY , WEEK , and MONTH.
Before submitting a categorized shift, create a shift rate and note its external_id.
This method is still supported, but it is recommended to use Add categorized shifts instead.
This shift type adds a shift without requiring time_amount and time_unit in the request body. By default, time_amount is set to summary.total_payable_hours and time_unit is set to HOUR. You can perform the same operations on these shifts as you would with categorized shifts by using the same payload.
Before submitting a categorized shift, create a shift rate and note its external_id.
You can add multiple uncategorized shifts for a single contract by providing an array of shifts.
You can list the shifts in your organization and sort them by the time of creation.
Make a GET request to the List time tracking shifts endpoint.
In the query:
Use the array syntax contract_id[]=value to filter for contract IDs. For multiple contract IDs, you can use contract_id[]=value1&contract_id[]=value2.
You can retrieve the information of a single shift using the external_id of the shift.
You can update a shift before it is processed for payroll. After a shift is processed, your ability to amend it depends on the shift type:
This section explains how to update shifts that have not been processed for payroll:
You can update the information of a categorized shift.
You can only update shifts that have not been processed for payroll. Shifts are processed for payroll at the cutoff date.
Make a PATCH request to the Update a time tracking shift endpoint.
In the path:
In the body:
You can update the information of an uncategorized shift.
You can only update shifts that have not been processed for payroll. Shifts are processed for payroll at the cutoff date.
Make a PATCH request to the Update a raw time tracking shift endpoint.
In the path:
In the body:
You can delete a shift for a contract by using the external_id of the shift.
You can only delete shifts that have not been processed for payroll. Shifts are processed for payroll at the cutoff date.
When you need to adjust hours for shifts that have already been processed for payroll, you can use correction shifts. Corrections create a new shift entry that adjusts the payable hours of the original shift. The correction will be processed in the next payroll cycle, ensuring accurate compensation without modifying historical payroll data.
Before using correction shifts, keep in mind the following aspects:
To submit a correction, use the same Create a time tracking shift endpoint, by specifying CORRECTION_DELTA as the shift_type and including a corrections array with additional fields to specify the correction details.
For example, you may have previously created a shift with 10 total payable hours and this shift has been already processed for payroll. If you later discover that the actual hours worked were 7.5, which requires a reduction of 2.5 hours, note the original shift’s external_id.
Make a POST request to the Create a time tracking shift endpoint with the correction details.
In the body:
Shift rates are used in payroll calculations to define the amount of salary to be paid for a specific shift. The shift rate types are:
You can create shift rates for your organization, which you can then map to individual shifts when adding them.
You can retrieve a shift rate using the external_id of the shift rate.
Make a GET request to the Retrieve a single time tracking shift rate endpoint.
Where:
You can retrieve the list of shift rates for your organization.
You can update a shift rate if it’s not being used in any shift, by using the external_id of the shift rate.
Only shift rates that are not used in any shift can be updated.
Make a PATCH request to the Update a time tracking shift rate endpoint.
In the path:
In the body:
You can delete a shift rate if it’s not being used in any shift, by using the external_id of the shift rate.
Only shift rates that are not used in any shift can be deleted.