Pay Stubs


Overview

URL https://api.xero.com/payroll.xro/1.0/PayStubs
Methods Supported POST, GET
Description Allows you to retrieve and update paystubs in a Xero organisation
Allows you to retrieve, add, update and delete Paystub Earnings Lines.
Allows you to retrieve and update Paystub Timesheet Earnings Lines.
Allows you to retrieve and update Paystub Leave Earnings Lines.
Allows you to retrieve, add, update and delete Paystub Deduction Lines.
Allows you to retrieve, add, update and delete Paystub Reimbursement Lines.
Allows you to retrieve Paystub Benefit Lines.
Allows you to retrieve Paystub TimeOff Lines.

Elements for PayStub

EmployeeID Xero identifier for payroll employee
PayStubID Xero identifier for payroll paystub
PayRunID
FirstName Employee first name
LastName Employee last name
LastEdited Last edited
Earnings The Total Earnings for the PayRun
Deductions The Total Deductions for the PayRun
Tax The Total Tax for the PayRun
Reimbursements The Total Reimbursement for the PayRun
NetPay The Total NetPay for the PayRun
UpdatedDateUTC
EarningsLines See EarningsLine
LeaveEarningsLines See LeaveEarningsLine
TimesheetEarningsLines See TimesheetEarningsLine
DeductionLines See DeductionLine
ReimbursementLines See ReimbursementLine
BenefitLines See BenefitLine
TimeOffLines See TimeOffLine

Elements for a EarningsLine

The following elements are required to add a EarningsLine

EarningsTypeID Xero identifier for payroll earnings type.
RatePerUnit Rate per unit for earnings rate.
NumberOfUnits Earnings rate number of units

Elements for a LeaveEarningsLine

The following elements are required to add a LeaveEarningsLine

EarningsTypeID Xero identifier for payroll earnings type.
RatePerUnit Rate per unit for earnings rate.
NumberOfUnits Earnings rate number of units

Elements for a TimesheetEarningsLine

The following elements are required to add a TimesheetEarningsLine

EarningsTypeID Xero identifier for payroll earnings type.
RatePerUnit Rate per unit for earnings type
NumberOfUnits Earnings rate number of units.

Elements for a DeductionLine

The following elements are required to add a DeductionLine

DeductionTypeID Xero identifier for payroll earnings type.
CalculationType Calculation Type code
Percentage The Percentage of the Deduction Line.
Amount Deduction amount.

Elements for a ReimbursementLine

The following elements are required to add a ReimbursementLine

ReimbursementTypeID Xero identifier for payroll reimbursement type
Description Reimbursement lines description (max length 50)
ExpenseAccount Reimbursement expense account. For posted pay run you should be able to see expense account code
Amount Reimbursement amount

Elements for a BenefitLine

The following elements are required to add a BenefitLine

BenefitTypeID Xero identifier for payroll benefit type
Amount Reimbursement amount

Elements for a TimeOffLine

The following elements are required to add a TimeOffLine

TimeOffTypeID Xero identifier for payroll time off type
Hours Hours of time off
Balance Balance for the time off type

GET PayStub

Optional parameters for GET PayStub

Record filter You can specify an individual record by appending the value to the endpoint, i.e.
GET https://…/PayStubs/{identifier}
PayStubID The Xero identifier for a Paystub e.g. 297c2dc5-cc47-4afd-0000-74990b8761e9

Example response for GET PayStubs/{identifier}

Example TBC

POST PayStub

Use this method to add, update or delete one or more paystub line items.

Note: You do not need to provide a line item type that you don’t need to update. However, if a line item type is included, you must specify all lines of that type, otherwise missing lines will be deleted.

Example of minimum elements required to add a new PayStub

Example TBC

Example of updating a paystub

Example TBC

Example of updating a paystubs timesheet earnings lines

<PayStubs>
  <PayStub>
    <EmployeeID>509d776f-6826-4873-8d17-fea3a2a750c0</EmployeeID>
    <PayStubID>f626ca03-aa29-43d4-8204-4ba12293fdb0</PayStubID>
    <EarningsLines>
      <EarningsLine>
        <EarningsTypeID>a24dd671-afd3-49bf-a60e-88acd7faa9e4</EarningsTypeID>
        <RatePerUnit>30.0000</RatePerUnit>
        <NumberOfUnits>40.0000</NumberOfUnits>
      </EarningsLine>
    </EarningsLines>
  </PayStub>
</PayStubs>

Note that we can not add a TimesheetEarningsLine and LeaveEarningsLine through PayStub Service. You can update the RatePerUnit of a TimesheetEarningsLine.

Example of adding a paystub Deduction Line

<PayStubs>
  <PayStub>
    <EmployeeID>509d776f-6826-4873-8d17-fea3a2a750c0</EmployeeID>
    <PayStubID>621cffb4-38cc-43dd-9c0b-c9e0e1b0f578</PayStubID>
    <DeductionLines>
      <DeductionLine>
        <DeductionTypeID>0c29b630-4e53-453d-a2e7-e8e97a95f636</DeductionTypeID>
        <CalculationType>FIXEDAMOUNT</CalculationType>
        <Amount>15.00</Amount>
      </DeductionLine>
    </DeductionLines>
  </PayStub>
</PayStubs>

Example of adding a paystub Reimbursement Line

<PayStubs>
  <PayStub>
    <EmployeeID>509d776f-6826-4873-8d17-fea3a2a750c0</EmployeeID>
    <PayStubID>621cffb4-38cc-43dd-9c0b-c9e0e1b0f578</PayStubID>
    <ReimbursementLines>
      <ReimbursementLine>
        <ReimbursementTypeID>bd246b96-c637-4767-81cf-851ba8fa93c2</ReimbursementTypeID>
        <Description>Test Description</Description>
        <Amount>10.00</Amount>
      </ReimbursementLine>
    </ReimbursementLines>
  </PayStub>
</PayStubs>