You can use the Paycircle importer to create, update, and delete recurring pay elements in bulk. As well as importing the element type and value, you can now control how long a recurring element runs by specifying either a number of periods or an end date.
What you can do
When importing recurring pay elements, you can:
Create new recurring elements for employees.
Update existing recurring elements, e.g. change the value or stop control.
Delete recurring elements by setting the number of recurring periods to 0.
Set a stop control using either a number of periods or a specific end date.
Import indefinitely recurring elements by leaving the stop control columns blank.
Set up your import file
Supported file formats
Recurring pay element imports support both horizontal and vertical file layouts.
Columns available
For each recurring pay element in your element pack, two additional columns are available for mapping:
📌Note: You don't need to use both columns. If both are provided for the same element, the end date takes precedence. If neither column is populated, the element will recur indefinitely.
Column | Description |
Recurring End Date (Element Name) | A date value indicating when the element should stop recurring. Must be in a future pay period. |
Number of Recurring Periods (Element Name) | A whole number indicating how many pay periods the element recurs. Maximum 36 periods. |
Mapping columns
When you upload your file and begin mapping, the recurring end date and number of periods columns appear as linked columns, shown alongside the element they relate to.
To see the available linked columns for a specific element, click on that element's header in the mapping list. The two additional columns, end date and number of periods, will appear directly after the main element column.
Auto-mapping
If your file's column headers match the expected names exactly, auto-mapping will pick them up automatically. This also applies when using saved mapping templates.
Linked columns are hidden until you select their parent element, to keep the mapping list manageable.
If you map a linked column and then unmap the parent element, the linked columns will disappear from the list. Simply re-select the parent element header to make them visible again.
Import behaviour
New elements
If the employee does not already have a recurring element of the imported type, a new one is created. It will appear in the New section of the import summary.
Matching existing elements (single match)
If the employee already has one recurring element of the same type, the import defaults to updating that existing element. These appear in the Updates section of the import summary.
You can choose to override this and create as new instead by clicking into the record and selecting the create option.
Matching existing elements (multiple matches)
If the employee has more than one recurring element of the same type, the importer will show a warning requiring you to choose which existing element to update, or to create a new one. This warning is blocking; you must make a selection before the import can proceed.
Each matching element is displayed with its current value and period count, so you can identify the correct one.
Deleting a recurring element
To delete a recurring element via import, set the Number of Recurring Periods to 0. The element will be removed and will appear as an update in the import results.
Validation rules
The importer validates recurring end dates against the following rules:
Rule | Behaviour |
End date is in the current pay period or the past. | The row is rejected. A recurring element must have a future end date. |
End date exceeds 36 periods in the future. | A warning is shown. You can attempt to fix the value inline, but the import will fail if the date remains invalid. |
Non-date value in the end date column. | The row fails validation. |
Number of periods exceeds 36. | A warning is shown. The maximum number of recurring periods is 36. |
Proration
If the pay element is configured as proratable in the element pack, an end date will trigger proration in the final period. The element's value will be prorated based on the proportion of the period up to the end date.
If the element is not proratable, the end date is used to determine the last whole period the element will be included in, and the element will recur up to and including the period that the end date falls within, at its full value.
When viewing a recurring element that was imported with an end date, a note will appear on the element form indicating the end date and, if applicable, that proration will occur.
📌Note: At present, the end date can only be set or changed via import. A future update will allow end dates to be set directly in the recurring element form.
Frequently asked questions
Can I use both the number of periods and the end date in the same file for different employees?
Yes. Each row is evaluated independently. You can have some employees with an end date and others with a number of periods in the same import file.
What happens if I provide both an end date and a number of periods for the same employee and element?
The end date takes precedence. The number of periods value will be ignored for that row.
Can I change an element from date-based to period-based via import?
Yes. If the element currently has an end date and you import a number of periods (without an end date), it will update to use the period count, and the end date will be cleared.
Can I remove a stop control and make an element recur indefinitely again?
Leave both the end date and number of periods columns blank for that row. The element will revert to indefinite recurring.
Why did my row get skipped with no warning?
If you choose to ignore a row during import e.g by clicking skip on a warning, it is excluded from the import entirely and is not counted in the skipped total. Skipped counts reflect rows that were submitted for import but could not be processed due to validation failures.