Pay Runs

Authentication: All endpoints require an Authorization: Bearer <access token> header.

Most endpoints require an X-Company-ID: <company_id> header to scope requests to a specific company. This is the recommended header for most API operations.

Some endpoints require an X-Location-ID: <location_id> header when the query doesn't accept a locationId parameter.

See Authentication for details on how to obtain and use these headers.

Query Pay Runs

Retrieve all pay runs for the company. Pay runs represent payroll periods and contain timesheet data that has been processed for payment.

Query Parameters:

This query takes no parameters and returns all pay runs configured for the company.

Response Fields:

Field Description
id Unique identifier for the pay run
name Name of the pay run (e.g., "May 2024 - Fortnight 2")
description Description of the pay run
startDate Start date of the pay period
endDate End date of the pay period
status Current status (e.g., "Finalised", "Processed")
createdAt Timestamp when the pay run was created
timesheetsSelectedAt Timestamp when timesheets were selected for the pay run
timesheetsSelectedBy.fullName Name of the user who selected timesheets
finalisedAt Timestamp when the pay run was finalised
finalisedBy.fullName Name of the user who finalised the pay run
processedAt Timestamp when the pay run was processed
processedBy.fullName Name of the user who processed the pay run
modifiedAt Timestamp when the pay run was last modified
modifiedBy.fullName Name of the user who last modified the pay run

For the complete PayRun type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

  • Pay runs follow a workflow: Created → Timesheets Selected → Finalised → Processed
  • Only pay runs in "Finalised" or "Processed" status can be used for payroll
  • The date range (startDate to endDate) determines which timesheets are included
  • Multiple pay runs can exist for different periods or employee groups
  • Pay runs are read-only once processed to maintain payroll audit trails
  • The various timestamps track the pay run lifecycle for compliance and audit purposes

GraphQL Query

query PayRuns {
  payRuns {
    id
    name
    description
    startDate
    endDate
    status
    createdAt
    timesheetsSelectedAt
    timesheetsSelectedBy {
      fullName
    }
    finalisedAt
    finalisedBy {
      fullName
    }
    processedAt
    processedBy {
      fullName
    }
    modifiedAt
    modifiedBy {
      fullName
    }
  }
}

Example Variables

{}

Example Response

{
  "data": {
    "payRuns": [
      {
        "id": "38",
        "name": "May 2024 - Fortnight 2",
        "description": null,
        "startDate": "2024-05-20",
        "endDate": "2024-06-02",
        "status": "Finalised",
        "createdAt": "2024-06-06T04:53:26.177Z",
        "timesheetsSelectedAt": null,
        "timesheetsSelectedBy": null,
        "finalisedAt": "2024-06-06T04:55:43.469Z",
        "finalisedBy": {
          "fullName": "Roubler Support"
        },
        "processedAt": null,
        "processedBy": null,
        "modifiedAt": "2024-06-06T04:53:26.177Z",
        "modifiedBy": {
          "fullName": "Roubler Support"
        }
      }
    ]
  }
}

Query Pay Run by ID

Retrieve detailed information about a specific pay run, including pay items, timesheets, and any errors. This provides a complete view of all payment calculations for the period.

Query Parameters:

Parameter Type Required Description
payRunId ID! Yes The ID of the pay run to retrieve

Response Fields:

Field Description
id Unique identifier for the pay run
name Name of the pay run
description Description of the pay run
startDate Start date of the pay period
endDate End date of the pay period
status Current status of the pay run
createdAt Timestamp when the pay run was created
finalisedAt Timestamp when the pay run was finalised
finalisedBy.fullName Name of the user who finalised the pay run
errors Array of errors encountered during pay run processing
errors[].message Error message describing the issue
errors[].employee.id ID of the employee associated with the error
errors[].employee.fullName Full name of the employee associated with the error
payItems Array of calculated pay items for this pay run
payItems[].employee.id Employee ID for this pay item
payItems[].employee.fullName Employee full name
payItems[].payType.id Pay type ID
payItems[].payType.name Pay type name
payItems[].startTime Start time of the pay period for this item
payItems[].endTime End time of the pay period for this item
payItems[].unitAmount Rate per unit (in cents)
payItems[].quantity Number of units (e.g., hours)
payItems[].amount Total amount for this pay item (in cents)
timesheets Array of timesheets included in this pay run
timesheets[].id Timesheet ID
timesheets[].status Timesheet status (e.g., "payrolled")
timesheets[].startTime Start time of the timesheet
timesheets[].endTime End time of the timesheet
timesheets[].hours Total hours for the timesheet
timesheets[].employee.id Employee ID
timesheets[].employee.text Employee name/display text
modifiedAt Timestamp when the pay run was last modified
modifiedBy.fullName Name of the user who last modified the pay run

For the complete PayRun type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

  • Pay items represent the final calculated pay amounts for each employee and pay type
  • Amounts are stored in cents (divide by 100 to get dollar amounts)
  • The errors array will contain any issues that prevented timesheets from being processed
  • Timesheets with status "payrolled" have been included in the pay run calculations
  • Pay items are grouped by employee and pay type for easier payroll processing
  • Each pay item includes the rate (unitAmount), quantity, and total amount
  • This detailed view is typically used for payroll reconciliation and reporting

GraphQL Query

query PayRun($payRunId: ID!) {
  payRun(id: $payRunId) {
    id
    name
    description
    startDate
    endDate
    status
    createdAt
    finalisedAt
    finalisedBy {
      fullName
    }
    errors {
      message
      employee {
        id
        fullName
      }
    }
    payItems {
      employee {
        id
        fullName
      }
      payType {
        id
        name
      }
      startTime
      endTime
      unitAmount
      quantity
      amount
    }
    timesheets {
      id
      status
      startTime
      endTime
      hours
      employee {
        id
        text
      }
    }
    modifiedAt
    modifiedBy {
      fullName
    }
  }
}

Example Variables

{
  "payRunId": "38"
}

Example Response

{
  "data": {
    "payRun": {
      "id": "38",
      "name": "May 2024 - Fortnight 2",
      "description": null,
      "startDate": "2024-05-20",
      "endDate": "2024-06-02",
      "status": "Finalised",
      "createdAt": "2024-06-06T04:53:26.177Z",
      "finalisedAt": "2024-06-06T05:00:17.747Z",
      "finalisedBy": {
        "fullName": "Roubler Support"
      },
      "errors": [],
      "payItems": [
        {
          "employee": {
            "id": "72908",
            "fullName": "Craig Bussell"
          },
          "payType": {
            "id": "790",
            "name": "Ordinary - Standard - Standard"
          },
          "startTime": "2024-05-19T23:00:00.000Z",
          "endTime": "2024-05-20T05:00:00.000Z",
          "unitAmount": 14423,
          "quantity": 33,
          "amount": 475959
        },
        {
          "employee": {
            "id": "72909",
            "fullName": "Nicolas Chan"
          },
          "payType": {
            "id": "788",
            "name": "Overtime - Standard - Standard"
          },
          "startTime": "2024-06-01T06:00:00.000Z",
          "endTime": "2024-06-01T07:00:00.000Z",
          "unitAmount": 2200,
          "quantity": 1,
          "amount": 2200
        }
      ],
      "timesheets": [
        {
          "id": "4518861",
          "status": "payrolled",
          "startTime": "2024-05-29T21:00:00.000Z",
          "endTime": "2024-05-30T01:00:00.000Z",
          "hours": 4,
          "employee": {
            "id": "72908",
            "text": "Craig Bussell"
          }
        },
        {
          "id": "4518849",
          "status": "payrolled",
          "startTime": "2024-05-19T22:00:00.000Z",
          "endTime": "2024-05-20T05:00:00.000Z",
          "hours": 7,
          "employee": {
            "id": "72909",
            "text": "Nicolas Chan"
          }
        }
      ],
      "modifiedAt": "2024-06-06T04:53:26.177Z",
      "modifiedBy": {
        "fullName": "Roubler Support"
      }
    }
  }
}

Process Pay Run

Process a finalised pay run to mark it as processed. This indicates that the payroll has been completed and the data has been exported or integrated with external payroll systems.

Mutation Parameters:

Parameter Type Required Description
id ID! Yes ID of the pay run to process
input ProcessPayRunInput! Yes Input object containing processing details
input.processedAt DateTime! Yes Timestamp when the pay run was processed

Response Fields:

Field Description
id Unique identifier for the pay run
status Updated status (should be "Processed")

For the complete PayRun type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

  • Only pay runs in "Finalised" status can be processed
  • Processing a pay run is typically done after exporting payroll data
  • Once processed, the pay run cannot be modified or deleted
  • The processedAt timestamp should reflect when the payroll was actually completed
  • This operation is the final step in the pay run workflow
  • Processed pay runs maintain a complete audit trail for compliance

GraphQL Mutation

mutation ProcessPayrun($id: ID!, $input: ProcessPayRunInput!) {
  processPayRun(id: $id, input: $input) {
    id
    status
  }
}

Example Variables

{
  "id": "40",
  "input": {
    "processedAt": "2024-05-20T20:00:00Z"
  }
}

Example Response

{
  "data": {
    "processPayRun": {
      "id": "40",
      "status": "Processed"
    }
  }
}

Delete Pay Run

Delete a pay run. This removes the pay run and releases any associated timesheets back to an unpaid status.

Mutation Parameters:

Parameter Type Required Description
id ID! Yes ID of the pay run to delete

Response Fields:

Field Description
(boolean) Returns true if the pay run was successfully deleted

Implementation Notes:

  • Only pay runs that have not been processed can be deleted
  • Deleting a pay run does not delete the timesheets, it only removes them from the pay run
  • Timesheets will return to their previous status and can be included in future pay runs
  • This operation is typically used to correct mistakes before payroll processing
  • Once a pay run is processed, it cannot be deleted (for audit trail purposes)
  • The deletion is permanent and cannot be undone

GraphQL Mutation

mutation DeletePayrun($id: ID!) {
  deletePayRun(id: $id)
}

Example Variables

{
  "id": "39"
}

Example Response

{
  "data": {
    "deletePayRun": true
  }
}