PayItems


Overview

URL https://api.xero.com/payroll.xro/1.0/PayItems
Methods Supported POST, GET
Description Allows you to retrieve, add, update and delete Payroll Items in a Xero organisation

Elements for PayItems

EarningsRates See EarningsRates
DeductionTypes See DeductionTypes
LeaveTypes See LeaveTypes
ReimbursementTypes See ReimbursementTypes

Elements for EarningsRates

The following are required to add an Earnings Rate
Name Name of the earnings rate (max length = 100)
AccountCode See Accounts
TypeOfUnits Type of units used to record earnings (max length = 50). Only When RateType is RATEPERUNIT
IsExemptFromTax Most payments are subject to tax, so you should only set this value if you are sure that a payment is exempt from PAYG withholding
IsExemptFromSuper See the ATO website for details of which payments are exempt from SGC
EarningsType See EarningsTypes
The following are optional for an Earnings Rate
EarningsRateID Xero identifier
RateType See RateTypes
RatePerUnit Default rate per unit (optional). Only applicable if RateType is RATEPERUNIT.
Multiplier This is the multiplier used to calculate the rate per unit, based on the employee’s ordinary earnings rate. For example, for time and a half enter 1.5. Only applicable if RateType is MULTIPLE
AccrueLeave Indicates that this earnings rate should accrue leave. Only applicable if RateType is MULTIPLE
Amount Option Amount for FIXEDAMOUNT RateType EarningsRate

Elements for DeductionTypes

The following are required to add a Deduction Type
Name Name of the deduction type (max length = 50)
AccountCode See Accounts
ReducesTax Indicates that this is a pre-tax deduction that will reduce the amount of tax you withhold from an employee.
ReducesSuper Most deductions don’t reduce your superannuation guarantee contribution liability, so typically you will not set any value for this.
The following are optional for a Deduction Type
DeductionTypeID Xero identifier

Elements for LeaveTypes

The following are required to add a Leave Type
Name Name of the leave type (max length = 50)
TypeOfUnits The type of units by which leave entitlements are normally tracked. These are typically the same as the type of units used for the employee’s ordinary earnings rate
IsPaidLeave Set this to indicate that an employee will be paid when taking this type of leave
ShowOnPayslip Set this if you want a balance for this leave type to be shown on your employee’s payslips
The following are optional for a Leave Type
LeaveTypeID Xero identifier
NormalEntitlement The number of units the employee is entitled to each year
LeaveLoadingRate Enter an amount here if your organisation pays an additional percentage on top of ordinary earnings when your employees take leave (typically 17.5%)

Elements for ReimbursementTypes

The following are required to add a Reimbursement Type
Name Name of the reimbursement type (max length = 50)
AccountCode See Accounts
The following are optional for a Reimbursement Type
ReimbursementTypeID Xero identifier

GET PayItems

By default using GET PayItems will return all PayItems.

Example response for GET PayItems

<PayItems>
    <EarningsRates>
      <EarningsRate>
        <EarningsRateID>eca71b79-edab-4c3f-967f-a405453bac08</EarningsRateID>
        <Name>Ordinary Hours</Name>
        <EarningsType>ORDINARYTIMEEARNINGS</EarningsType>
        <RateType>RATEPERUNIT</RateType>
        <AccountCode>477</AccountCode>
        <TypeOfUnits>Hours</TypeOfUnits>
        <IsExemptFromTax>false</IsExemptFromTax>
        <IsExemptFromSuper>false</IsExemptFromSuper>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </EarningsRate>
      <EarningsRate>
        <EarningsRateID>f8eb8381-7db0-4de3-ada0-e03bbd1d811f</EarningsRateID>
        <Name>Overtime Hours (exempt from super)</Name>
        <EarningsType>OVERTIMEEARNINGS</EarningsType>
        <RateType>MULTIPLE</RateType>
        <AccountCode>477</AccountCode>
        <Multiplier>1.5000</Multiplier>
        <IsExemptFromTax>false</IsExemptFromTax>
        <IsExemptFromSuper>true</IsExemptFromSuper>
        <AccrueLeave>false</AccrueLeave>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </EarningsRate>
      <EarningsRate>
        <EarningsRateID>694d0065-f594-48f7-89c0-5cfd7a0c4c92</EarningsRateID>
        <Name>Allowances subject to tax withholding and super</Name>
        <EarningsType>ALLOWANCE</EarningsType>
        <RateType>RATEPERUNIT</RateType>
        <AccountCode>477</AccountCode>
        <TypeOfUnits>Fixed Amount</TypeOfUnits>
        <IsExemptFromTax>false</IsExemptFromTax>
        <IsExemptFromSuper>false</IsExemptFromSuper>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </EarningsRate>
      <EarningsRate>
        <EarningsRateID>92d6ae67-4302-4561-9000-90163cac8eb8</EarningsRateID>
        <Name>Allowances exempt from tax withholding and super</Name>
        <EarningsType>ALLOWANCE</EarningsType>
        <RateType>RATEPERUNIT</RateType>
        <AccountCode>477</AccountCode>
        <TypeOfUnits>Fixed Amount</TypeOfUnits>
        <IsExemptFromTax>true</IsExemptFromTax>
        <IsExemptFromSuper>true</IsExemptFromSuper>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </EarningsRate>
    </EarningsRates>
    <DeductionTypes>
      <DeductionType>
        <DeductionTypeID>f9be43ee-1876-4e67-a295-2a30eadd1942</DeductionTypeID>
        <Name>Union Fees/Subscriptions</Name>
        <AccountCode>850</AccountCode>
        <ReducesTax>false</ReducesTax>
        <ReducesSuper>false</ReducesSuper>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </DeductionType>
      <DeductionType>
        <DeductionTypeID>f70fcea1-157c-4a1a-8724-369160e5cb5c</DeductionTypeID>
        <Name>Lease Payments</Name>
        <AccountCode>850</AccountCode>
        <ReducesTax>true</ReducesTax>
        <ReducesSuper>true</ReducesSuper>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </DeductionType>
      <DeductionType>
        <DeductionTypeID>8d6e580f-37e1-48cf-80fe-e591008a251f</DeductionTypeID>
        <Name>FBT</Name>
        <AccountCode>850</AccountCode>
        <ReducesTax>true</ReducesTax>
        <ReducesSuper>true</ReducesSuper>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </DeductionType>
      <DeductionType>
        <DeductionTypeID>eabff3b0-2fdc-4e3b-955c-30e113829c74</DeductionTypeID>
        <Name>Other Pre-Tax Deductions</Name>
        <AccountCode>850</AccountCode>
        <ReducesTax>true</ReducesTax>
        <ReducesSuper>true</ReducesSuper>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </DeductionType>
      <DeductionType>
        <DeductionTypeID>c0b2f074-883e-451b-8863-185fd2403cef</DeductionTypeID>
        <Name>Other Post-Tax Deductions</Name>
        <AccountCode>850</AccountCode>
        <ReducesTax>false</ReducesTax>
        <ReducesSuper>false</ReducesSuper>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </DeductionType>
    </DeductionTypes>
    <ReimbursementTypes>
      <ReimbursementType>
        <ReimbursementTypeID>d4263307-f387-4c69-9525-7482d742ef50</ReimbursementTypeID>
        <Name>Travel National Costs</Name>
        <AccountCode>493</AccountCode>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </ReimbursementType>
      <ReimbursementType>
        <ReimbursementTypeID>7ecdc711-ea65-469a-ab9d-2a63f0753129</ReimbursementTypeID>
        <Name>Other Reimbursable Costs</Name>
        <AccountCode>850</AccountCode>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </ReimbursementType>
    </ReimbursementTypes>
    <LeaveTypes>
      <LeaveType>
        <LeaveTypeID>bd2ead8d-f8f9-480a-8a71-260222ed1a34</LeaveTypeID>
        <Name>Annual Leave</Name>
        <TypeOfUnits>Hours</TypeOfUnits>
        <NormalEntitlement>152.0000</NormalEntitlement>
        <IsPaidLeave>true</IsPaidLeave>
        <ShowOnPayslip>true</ShowOnPayslip>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </LeaveType>
      <LeaveType>
        <LeaveTypeID>cd61fd41-671b-4d1f-ad6e-fbcb1eca3fc3</LeaveTypeID>
        <Name>Long Service Leave</Name>
        <TypeOfUnits>Hours</TypeOfUnits>
        <IsPaidLeave>true</IsPaidLeave>
        <ShowOnPayslip>false</ShowOnPayslip>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </LeaveType>
      <LeaveType>
        <LeaveTypeID>c06359d4-ee61-4f74-9c74-f94ef6a850e3</LeaveTypeID>
        <Name>Parental Leave (unpaid)</Name>
        <TypeOfUnits>Hours</TypeOfUnits>
        <IsPaidLeave>false</IsPaidLeave>
        <ShowOnPayslip>false</ShowOnPayslip>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </LeaveType>
      <LeaveType>
        <LeaveTypeID>271814d6-1087-45f2-923a-8301113a298b</LeaveTypeID>
        <Name>Personal/Carer's Leave</Name>
        <TypeOfUnits>Hours</TypeOfUnits>
        <NormalEntitlement>76.0000</NormalEntitlement>
        <IsPaidLeave>true</IsPaidLeave>
        <ShowOnPayslip>false</ShowOnPayslip>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </LeaveType>
      <LeaveType>
        <LeaveTypeID>f3a5f2f8-c14e-4223-ab58-4e779e0f6f2c</LeaveTypeID>
        <Name>Carer's Leave (unpaid)</Name>
        <TypeOfUnits>Hours</TypeOfUnits>
        <IsPaidLeave>false</IsPaidLeave>
        <ShowOnPayslip>false</ShowOnPayslip>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </LeaveType>
      <LeaveType>
        <LeaveTypeID>30ca48d0-fe04-40c2-b590-f5191159259f</LeaveTypeID>
        <Name>Compassionate Leave (paid)</Name>
        <TypeOfUnits>Hours</TypeOfUnits>
        <IsPaidLeave>true</IsPaidLeave>
        <ShowOnPayslip>false</ShowOnPayslip>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </LeaveType>
      <LeaveType>
        <LeaveTypeID>1e1765bc-1dbc-4ac9-b6cd-9f9f3290d8a4</LeaveTypeID>
        <Name>Compassionate Leave (unpaid)</Name>
        <TypeOfUnits>Hours</TypeOfUnits>
        <IsPaidLeave>false</IsPaidLeave>
        <ShowOnPayslip>false</ShowOnPayslip>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </LeaveType>
      <LeaveType>
        <LeaveTypeID>42d46756-9f2b-4456-ad44-8c889ff4a5bd</LeaveTypeID>
        <Name>Community Service Leave</Name>
        <TypeOfUnits>Hours</TypeOfUnits>
        <IsPaidLeave>false</IsPaidLeave>
        <ShowOnPayslip>false</ShowOnPayslip>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </LeaveType>
      <LeaveType>
        <LeaveTypeID>7ea96a9f-d7c2-4de1-a3ac-bf89980f1890</LeaveTypeID>
        <Name>Other Unpaid Leave</Name>
        <TypeOfUnits>Hours</TypeOfUnits>
        <IsPaidLeave>false</IsPaidLeave>
        <ShowOnPayslip>false</ShowOnPayslip>
        <UpdatedDateUTC>2013-04-09T23:45:25</UpdatedDateUTC>
      </LeaveType>
    </LeaveTypes>
  </PayItems>

POST PayItems

Use this method to create, update or delete one or more payroll pay items.

Note: Deleting payroll PayItems works as follows. If you include a PayItem type (example: <DeductionTypes>) you must include each <DeductionType>, otherwise it will be deleted. If you omit the PayItem type from your request all PayItems of that type will not be modified or deleted.

There is one exception, PayItems that have been used within a POSTED Payrun will become ‘locked’ and can not be deleted.

Example updating payitems

<PayItems>
  <DeductionTypes>
    <DeductionType>
      <AccountCode>826</AccountCode>
      <DeductionTypeID>648a097e-11ff-42ad-be47-e77b85597a0f</DeductionTypeID>
      <Name>Union Fees</Name>
      <ReducesSuper>false</ReducesSuper>
      <ReducesTax>false</ReducesTax>
    </DeductionType>
    <DeductionType>
      <AccountCode>826</AccountCode>
      <DeductionTypeID>82758787-2baf-4677-8aec-2fa1651b57a9</DeductionTypeID>
      <Name>Social Club</Name>
      <ReducesSuper>false</ReducesSuper>
      <ReducesTax>false</ReducesTax>
    </DeductionType>
  </DeductionTypes>
  <EarningsRates>
    <EarningsRate>
      <AccountCode>477</AccountCode>
      <AccrueLeave>false</AccrueLeave>
      <EarningsRateID>d55a0c16-dc45-40dd-b8c1-95496c9f20f0</EarningsRateID>
      <IsAllowance>false</IsAllowance>
      <IsExemptFromSuper>false</IsExemptFromSuper>
      <IsExemptFromTax>false</IsExemptFromTax>
      <Name>Ordinary Hours</Name>
      <RateType>FIXED</RateType>
      <TypeOfUnits>Hours</TypeOfUnits>
    </EarningsRate>
    <EarningsRate>
      <AccountCode>477</AccountCode>
      <AccrueLeave>false</AccrueLeave>
      <EarningsRateID>acff395b-4ced-4737-b6b4-ed0f241c1ff0</EarningsRateID>
      <IsAllowance>false</IsAllowance>
      <IsExemptFromSuper>true</IsExemptFromSuper>
      <IsExemptFromTax>false</IsExemptFromTax>
      <Multiplier>1.5000</Multiplier>
      <Name>Overtime Hours (exempt from super)</Name>
      <RateType>MULTIPLE</RateType>
    </EarningsRate>
  </EarningsRates>
  <LeaveTypes>
    <LeaveType>
      <IsPaidLeave>true</IsPaidLeave>
      <LeaveLoadingRate>2.0000</LeaveLoadingRate>
      <LeaveTypeID>209b9774-ebe5-4b9e-b222-cf296444f57b</LeaveTypeID>
      <Name>Annual Leave</Name>
      <NormalEntitlement>160.0000</NormalEntitlement>
      <ShowOnPayslip>true</ShowOnPayslip>
      <TypeOfUnits>Hours</TypeOfUnits>
    </LeaveType>
  </LeaveTypes>
</PayItems>