Nowsta Custom Reporting File Guide

Modified on Wed, 08 Nov 2023 at 03:00 PM

Nowsta Custom Reporting File Guide

For Nowsta to be able to create a Custom file for you, we require an example file that clearly outlines the setup of the columns and the specific information you would like to be able to pull from the Nowsta database. This example file can be created by your company using the following guide and templates linked within:  Custom File Overview

Important Details

There is a fee associated with the creation of any Custom File. Please reach out to for more information and assistance.

It typically it takes an average of 3-4 business weeks for us to complete a customized file. Once we have received the appropriate file format, we will check it and submit it to our engineering team. Our Engineering Sprints run in 2 week intervals therefore the time frame for completion depends on when in that process the ticket is submitted. 

All file templates must be in .csv format

Nowsta can only pull data for fields it already tracks

The Column headers can be named anything that suits your Payroll system but if these headers are different to what the field is called in Nowsta it is important that you detail which field this column relates to, as in the key example below.

Key example


Payroll System Field

Nowsta Field

Column E

Employee ID

Payroll ID

Column H

Department ID

Department pay code

Possible Columns

Below is a list of some standard columns we can add to a payroll report. In addition, we can also support hard coded columns, where we set the column always to have a specific value.

Please Note: 

  • A single column can only hold one value or can only be hardcoded to one value. 

E.g We cannot have a single column in a report that shows a Position Pay Code in some rows and a Department Pay Code in other rows.

  • Formatting of values within a particular column ( time formatting, number of decimal places for a value, etc.) usually is something we can do.

Common Columns Related to Workers and Shifts

If there is a field that already exists in the Nowsta platform and you would like it to be included as a column in a payroll file, it is likely we can include it, but please note that this will need to be escalated to our Engineering Team for confirmation first.

Common Columns


The company for which the hours were worked.


List of relevant breaks for the punchcard(s).

worker first name

First name of worker.

worker last name

Last name of worker.

payroll id

Payroll ID field set on the Worker Profile. Often this will be referred to as "Payroll ID" or “Employee ID” in payroll files.

position pay code

Position Pay Code field set on the Position.

company pay code

Metadata field from company. The company can set this on their settings page

department pay code

Pay Code field set on the Department. Often this will be referred to as "Department ID" in payroll files.

venue pay code

Pay Code field set on the Venue.

event external id 

Field on event used most often to track IDs coming in from TPP/Caterease integration, or supplied by the customer through the single event view “Event ID” field. Any time you see something like "Event ID" in a payroll file, typically it is this field that is meant

position name

Name of the position worked.

event name

Name of the event worked (note: will be empty for non-event shifts).

time zone

Time zone in which the hours were worked.

client name

Name of client for which the hours were worked (if any).

department name

Name of the department associated with the position worked (if any).

job name 

This value will vary based on the following:

If the punchcard is for an event shift, the job name will be the name of the event.

If the punchcards is for a non-event shift for a specific position, or the worker uses GPS self-clock in, the job name will be “<position_name> shift".

If the punchcard is from an unscheduled shift clocked using the timeclock, it will be “[Timeclock]".

starts at

Time at which the punchcard starts.

ends at

Time at which the punchcard ends.

Hours-Related Columns


Number of hours worked, this will depend on the mode used and how the rows is split. It represents either the punchcard’s hours worked, hours worked for a part of a punchcard if hours mode is used, or overtime/double overtime if it has been split.

break hours

Total number of hours spent on breaks.

minimum hours difference

Difference between the number of hours worked and the minimum paid hours for the punchcard. This can’t be negative.

total hours

Total hours worked, based on the punchcard regardless of how it was split

regular hours

Total regular pay hours worked (i.e. not overtime).

overtime hours

Total overtime hours worked.

double overtime hours

Total double overtime hours worked.

Pay-Related Columns

regular hours pay

Pay awarded for regular hours worked.

overtime hours pay

Pay awarded for overtime hours worked.

double overtime hours pay

Pay awarded for double overtime hours worked.

bonus pay

Tips, bonuses field on the punchcard. This is a segment of "Additional Pay".

minimum hours pay

How much is paid for the minimum hours difference when the number of hours worked on the punchcard is less than the minimum paid hours set for the punchcard. This is a segment of "Additional Pay".

drive pay

This column takes the Drive Rate field from the punchcard and multiplies it to the Drive Time field to calculate the Drive Pay. This is a segment of "Additional Pay".

reimbursement pay

Reimbursements field on the punchcard. This is a segment of "Additional Pay".

spread of hours pay

The amount paid out as part of the Spread of Hours Bonus. This is a special bonus only applicable to hours worked in New York. Customers can turn this on from the Overtime Rules Settings page.

additional pay

All pay that is not directly related to hours worked. This is the sum of bonus pay, drive pay, reimbursement pay, minimum hours pay and spread of hours pay. This does not include regular pay, overtime hours pay, or double overtime hours pay.

declared tips

Only relevant for companies with the declared tips enabled option turned on on the backend. This setting allows users at those companies to declare their tips through the Timeclock app. This is not included in "Additional Pay", nor factored in anywhere else.

total pay

Total amount of wages paid for the punchcard(s).

Nowstapay deduction

This is a dollar amount that has been offered and cashed out on NowstaPay. Companies that use NowstaPay generally want to exclude hours already paid out from their payroll calculations.

Rate Fields

regular rate

Rate at which the worker is paid for regular hours.

overtime rate

Rate at which the worker is paid for overtime hours.

double overtime rate

Rate at which the worker is paid for double overtime hours.

client bill rate

Rate at which a client should be invoiced/billed for this shift.

Potential complicating factors

Below is a list of possible complications to consider when creating your file template that could require extra effort from our Engineering Team:

  • Grouping modes

  • Row split modes

    • regular hours
    • overtime hours
    • double-overtime hours
    • spread-of-hours pay
    • remaining additional pay (tips, reimbursements, travel pay, minimum hours pay)
  • Any kind of unusual rules around pay and overtime

    • E.g. a special way to calculate overtime 

  • Any kind of complex logic

    • E.g. an external CSV file with multiple different pay codes that need to be mapped

  • Columns/data that aren’t included in this document

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article