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

EarningsTypes See EarningsTypes
BenefitTypes See BenefitTypes
DeductionTypes See DeductionTypes
ReimbursementTypes See ReimbursementTypes
TimeOffTypes See TimeOffTypes

Elements for EarningsTypes

The following are required to add an Earnings Type
EarningsType Name of the earnings type (max length = 100)
ExpenseAccountCode See Accounts
EarningsCategory See EarningsCategory
RateType Only when EarningsCategory is OVERTIMEEARNINGS, ALLOWANCE, ADDITIONALEARNINGS
TypeOfUnits Only when EarningsCategory is ADDITIONALEARNINGS, ALLOWANCE and RateType is RATEPERUNIT
The following are optional for an Earnings Type
EarningsRateID Xero identifier
Multiple 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
DoNotAccrueTimeOff Set it to true if time off is NOT to be accumulated based on the hours reported to this earnings type
IsSupplemental Set it to true if this earnings type qualifies as a supplemental earnings according to the IRS regulations, e.g bonus or commission
Amount Optional for EarningsCategory COMMISSION, BONUS, CASHTIPS, NONCASHTIPS, RETROACTIVEPAY, CLERGYHOUSINGALLOWANCE, CLERGYHOUSINGINKIND (this will be the amount that will be added to the employee’s earnings on a per pay period basis). The ALLOWANCE & ADDITIONALEARNINGS EarningsCategory will also have the Amount field when the Rate Type is selected as FIXEDAMOUNT

Elements for BenefitTypes

The following are required to add an Benefit Type
BenefitType Name of the benefit type (max length = 100)
BenefitCategory The category defines the tax implications of the benefit type so it is taxed properly. See BenefitCategory
LiabilityAccountCode The account to which the amount of the benefit is to be credited
ExpenseAccountCode The account to which the amount of the benefit is to be debited.
The following are optional for an Benefit Type
BenefitTypeID Xero identifier
StandardAmount This is a default amount you can set for all employees assigned to this benefit type
CompanyMax The company max is the maximum amount set as a default amount for that particular benefit type for all employees assigned this benefit type in a single year
Percentage This is a default percentage you can set for all employees assigned to this benefit type
ShowBalanceOnPaystub Set this to true if you want this benefit item amount and YTD balance will show on the employee’s paystubs

Elements for DeductionTypes

The following are required to add a Deduction Type
DeductionType Name of the deduction type (max length = 50)
DeductionCategory The category defines the tax implications of the deduction type so it is taxed properly
CalculationType Deductions can be a fixed amount, or they can be calculated as a percentage of the employee’s total earnings. Standard Plan, Catch-up Plan. Only needed DeductionCategory is not AFTERTAXDEDUCTION, DEPENDEDNTCARE, FLEXIBLESPENDINGACCOUNT,HSASINGLEPLAN, HSAFAMILYPLAN, SECTION125PLAN
LiabilityAccountCode The computed amount of the deduction is credited to this account. See See Accounts
The following are optional for a Deduction Type
DeductionTypeID Xero identifier
StandardAmount This is a default amount you can set for all employees assigned to this deduction type. If you have more than one employee that pays the same amount for health insurance, setting this amount will save you time when setting up the employee deductions. If you choose not to set an amount here, you can enter the amounts to be deducted on a per employee basis. Only applicable when DeductionCategory is AFTERTAXDEDUCTION, DEPENDENTCARE, FLEXIBLESPENDINGACCOUNT,
SECTION125PLAN
CompanyMax The company max is the maximum amount set as a default amount to be deducted for that particular deduction type for all employees assigned this deduction type in a single year. For example, the IRS publishes limits for certain deduction types each year. You can set a company maximum that is lower than the IRS limit, depending on your plan requirements. If you don’t set a maximum, the deduction will stop automatically when the IRS limit is reached.
Only applicable when DeductionCategory is AFTERTAXDEDUCTION, DEPENDENTCARE, FLEXIBLESPENDINGACCOUNT,
SECTION125PLAN

Elements for ReimbursementTypes

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

Elements for TimeOffTypes

The following are required to add a TimeOff Type
TimeOffType Name of the time off type (max length = 50)
TimeOffCategory Select Unpaid Time Off to indicate that an employee will not get paid when taking this time off type.
If Paid Time Off is selected the employee will get paid when taking this time off type and you can accrue the liability on the Balance Sheet
ExpenseAccountCode The account to which the amount of the time off is to be debited. Only applies for TimeOffCategory of PAIDTIMEOFF
LiabilityAccountCode The computed amount of the time off is credited to this account
The following are optional for a TimeOff Type
TimeOffTypeID Xero identifier
ShowBalanceToEmployee Set it to true if you want the balance for this time off type to show on the employee’s paystub and in the employee’s My Payroll account.

GET PayItems

By default using GET PayItems will return all PayItems.

Example response for GET PayItems

<PayItems>
    <EarningsTypes>
      <EarningsType>
        <EarningsRateID>5a467a52-e60e-4a3d-bca8-3447a8e1fd79</EarningsRateID>
        <EarningsType>Regular Hours</EarningsType>
        <EarningsCategory>REGULAREARNINGS</EarningsCategory>
        <ExpenseAccountCode>668</ExpenseAccountCode>
        <DoNotAccrueTimeOff>false</DoNotAccrueTimeOff>
        <UpdatedDateUTC>2014-02-12T10:34:44</UpdatedDateUTC>
      </EarningsType>
      <EarningsType>
        <EarningsRateID>201bea36-29c8-424a-baa6-bf7ccd1dc364</EarningsRateID>
        <EarningsType>Overtime Hours</EarningsType>
        <EarningsCategory>OVERTIMEEARNINGS</EarningsCategory>
        <RateType>MULTIPLE</RateType>
        <Multiple>1.5000</Multiple>
        <ExpenseAccountCode>668</ExpenseAccountCode>
        <DoNotAccrueTimeOff>true</DoNotAccrueTimeOff>
        <UpdatedDateUTC>2014-02-24T01:37:49</UpdatedDateUTC>
      </EarningsType>
      <EarningsType>
        <EarningsRateID>0e5305a4-3c1c-4191-b210-e77a63e745e8</EarningsRateID>
        <EarningsType>Bonus</EarningsType>
        <EarningsCategory>BONUS</EarningsCategory>
        <ExpenseAccountCode>668</ExpenseAccountCode>
        <IsSupplemental>true</IsSupplemental>
        <UpdatedDateUTC>2014-02-12T10:34:44</UpdatedDateUTC>
      </EarningsType>
      <EarningsType>
        <EarningsRateID>b5e1f919-f00f-4a68-947c-91c740d4511c</EarningsRateID>
        <EarningsType>Another Regular Earnings</EarningsType>
        <EarningsCategory>REGULAREARNINGS</EarningsCategory>
        <ExpenseAccountCode>612</ExpenseAccountCode>
        <DoNotAccrueTimeOff>false</DoNotAccrueTimeOff>
        <UpdatedDateUTC>2014-02-24T10:53:20</UpdatedDateUTC>
      </EarningsType>
    </EarningsTypes>
    <BenefitTypes>
      <BenefitType>
        <BenefitTypeID>9fca3a4b-d767-4ba5-952d-36287f98811e</BenefitTypeID>
        <BenefitType>Employer Health Insurance</BenefitType>
        <BenefitCategory>SECTION125PLAN</BenefitCategory>
        <LiabilityAccountCode>250</LiabilityAccountCode>
        <ExpenseAccountCode>668</ExpenseAccountCode>
        <ShowBalanceOnPaystub>false</ShowBalanceOnPaystub>
        <UpdatedDateUTC>2014-02-12T10:34:44</UpdatedDateUTC>
      </BenefitType>
    </BenefitTypes>
    <DeductionTypes>
      <DeductionType>
        <DeductionTypeID>7bd5f5ac-de4c-4b09-84d0-ad9150a8ab44</DeductionTypeID>
        <DeductionType>Health Insurance</DeductionType>
        <DeductionCategory>SECTION125PLAN</DeductionCategory>
        <LiabilityAccountCode>250</LiabilityAccountCode>
        <UpdatedDateUTC>2014-02-23T23:58:30</UpdatedDateUTC>
      </DeductionType>
      <DeductionType>
        <DeductionTypeID>ad155ceb-8b5a-4ec9-915c-b5dc4cf9bc7f</DeductionTypeID>
        <DeductionType>Retirement Plan</DeductionType>
        <DeductionCategory>401KRETIREMENTPLAN</DeductionCategory>
        <CalculationType>STANDARDPLAN</CalculationType>
        <LiabilityAccountCode>250</LiabilityAccountCode>
        <UpdatedDateUTC>2014-02-23T23:58:30</UpdatedDateUTC>
      </DeductionType>
      <DeductionType>
        <DeductionTypeID>0638c33e-e079-4887-8715-380d7cadaea0</DeductionTypeID>
        <DeductionType>401k Retirement Plan Standard Plan</DeductionType>
        <DeductionCategory>401KRETIREMENTPLAN</DeductionCategory>
        <CalculationType>STANDARDPLAN</CalculationType>
        <LiabilityAccountCode>216</LiabilityAccountCode>
        <UpdatedDateUTC>2014-02-24T00:45:56</UpdatedDateUTC>
      </DeductionType>
    </DeductionTypes>
    <ReimbursementTypes>
      <ReimbursementType>        <ReimbursementTypeID>ca1373ae-0408-4366-bca9-a5bedfb16d6f</ReimbursementTypeID>
        <ReimbursementType>Travel Allowance</ReimbursementType>
        <ExpenseOrLiabilityAccountCode>250</ExpenseOrLiabilityAccountCode>
        <UpdatedDateUTC>2014-02-12T10:34:44</UpdatedDateUTC>
      </ReimbursementType>
      <ReimbursementType>        <ReimbursementTypeID>3bf68b77-f7d4-4867-a941-2cbe70bc776f</ReimbursementTypeID>
        <ReimbursementType>Automobile Mileage</ReimbursementType>
        <ExpenseOrLiabilityAccountCode>250</ExpenseOrLiabilityAccountCode>
        <UpdatedDateUTC>2014-02-12T10:34:44</UpdatedDateUTC>
      </ReimbursementType>                <ReimbursementTypeID>2d70007e-0256-4485-abbf-f7ef28748131</ReimbursementTypeID>
        <ReimbursementType>Other Reimbursable Costs</ReimbursementType>
        <ExpenseOrLiabilityAccountCode>250</ExpenseOrLiabilityAccountCode>
        <UpdatedDateUTC>2014-02-12T10:34:44</UpdatedDateUTC>
      </ReimbursementType>
    </ReimbursementTypes>
    <TimeOffTypes>
      <TimeOffType>
        <TimeOffTypeID>a3633fa6-b845-47e1-92f1-6f2c299f6f3b</TimeOffTypeID>
        <TimeOffType>Vacation</TimeOffType>
        <TimeOffCategory>PAID</TimeOffCategory>
        <ShowBalanceToEmployee>true</ShowBalanceToEmployee>
        <UpdatedDateUTC>2014-02-12T10:34:44</UpdatedDateUTC>
      </TimeOffType>
      <TimeOffType>
        <TimeOffTypeID>33e13a4f-a223-46cb-a76d-64559f74a6ee</TimeOffTypeID>
        <TimeOffType>Sick</TimeOffType>
        <TimeOffCategory>PAID</TimeOffCategory>
        <ShowBalanceToEmployee>true</ShowBalanceToEmployee>
        <UpdatedDateUTC>2014-02-12T10:34:44</UpdatedDateUTC>
      </TimeOffType>
    </TimeOffTypes>
  </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>
  <EarningsTypes>
    <EarningsType>
      <EarningsRateID>5a467a52-e60e-4a3d-bca8-3447a8e1fd79</EarningsRateID>
      <EarningsType>Regular Hours</EarningsType>
      <EarningsCategory>REGULAREARNINGS</EarningsCategory>
      <ExpenseAccountCode>668</ExpenseAccountCode>
      <DoNotAccrueTimeOff>false</DoNotAccrueTimeOff>
      <UpdatedDateUTC>2014-02-12T10:34:44</UpdatedDateUTC>
    </EarningsType>
    <EarningsType>
      <EarningsRateID>201bea36-29c8-424a-baa6-bf7ccd1dc364</EarningsRateID>
      <EarningsType>Overtime Hours</EarningsType>
      <EarningsCategory>OVERTIMEEARNINGS</EarningsCategory>
      <RateType>MULTIPLE</RateType>
      <Multiple>1.5000</Multiple>
      <ExpenseAccountCode>668</ExpenseAccountCode>
      <DoNotAccrueTimeOff>true</DoNotAccrueTimeOff>
      <UpdatedDateUTC>2014-02-24T01:37:49</UpdatedDateUTC>
    </EarningsType>
    <EarningsType>
      <EarningsRateID>dbe14484-d9bf-4116-9d61-f36f249109a0</EarningsRateID>
      <EarningsType>Allowance</EarningsType>
      <EarningsCategory>ALLOWANCE</EarningsCategory>
      <RateType>RATEPERUNIT</RateType>
      <TypeOfUnits>What</TypeOfUnits>
      <RatePerUnit>15.000000</RatePerUnit>
      <ExpenseAccountCode>500</ExpenseAccountCode>
      <IsSupplemental>false</IsSupplemental>
      <UpdatedDateUTC>2014-02-24T00:07:59</UpdatedDateUTC>
    </EarningsType>
  </EarningsTypes>
  <BenefitTypes>
    <BenefitType>
      <BenefitTypeID>9fca3a4b-d767-4ba5-952d-36287f98811e</BenefitTypeID>
      <BenefitType>Employer Health Insurance</BenefitType>
      <BenefitCategory>SECTION125PLAN</BenefitCategory>
      <LiabilityAccountCode>250</LiabilityAccountCode>
      <ExpenseAccountCode>668</ExpenseAccountCode>
      <ShowBalanceOnPaystub>false</ShowBalanceOnPaystub>
      <UpdatedDateUTC>2014-02-12T10:34:44</UpdatedDateUTC>
    </BenefitType>
  </BenefitTypes>
  <DeductionTypes>
    <DeductionType>
      <DeductionTypeID>0638c33e-e079-4887-8715-380d7cadaea0</DeductionTypeID>
      <DeductionType>401k Retirement Plan Standard Plan</DeductionType>
      <DeductionCategory>401KRETIREMENTPLAN</DeductionCategory>
      <CalculationType>STANDARDPLAN</CalculationType>
      <LiabilityAccountCode>216</LiabilityAccountCode>
      <UpdatedDateUTC>2014-02-24T00:45:56</UpdatedDateUTC>
    </DeductionType>
    <DeductionType>
      <DeductionTypeID>46b2f627-f515-4179-9ff5-400716fdaf4a</DeductionTypeID>
      <DeductionType>457 Retirement Plan Standard Plan</DeductionType>
      <DeductionCategory>401KRETIREMENTPLAN</DeductionCategory>
      <CalculationType>CATCHUPPLAN</CalculationType>
      <LiabilityAccountCode>230</LiabilityAccountCode>
      <UpdatedDateUTC>2014-02-24T00:46:33</UpdatedDateUTC>
    </DeductionType>
  </DeductionTypes>
  <ReimbursementTypes>
    <ReimbursementType>
      <ReimbursementTypeID>ca1373ae-0408-4366-bca9-a5bedfb16d6f</ReimbursementTypeID>
      <ReimbursementType>Travel Allowance</ReimbursementType>
      <ExpenseOrLiabilityAccountCode>250</ExpenseOrLiabilityAccountCode>
      <UpdatedDateUTC>2014-02-12T10:34:44</UpdatedDateUTC>
    </ReimbursementType>
    <ReimbursementType>
      <ReimbursementTypeID>3bf68b77-f7d4-4867-a941-2cbe70bc776f</ReimbursementTypeID>
      <ReimbursementType>Automobile Mileage</ReimbursementType>
      <ExpenseOrLiabilityAccountCode>250</ExpenseOrLiabilityAccountCode>
      <UpdatedDateUTC>2014-02-12T10:34:44</UpdatedDateUTC>
    </ReimbursementType>
  </ReimbursementTypes>
  <TimeOffTypes>
    <TimeOffType>
      <TimeOffTypeID>a3633fa6-b845-47e1-92f1-6f2c299f6f3b</TimeOffTypeID>
      <TimeOffType>Vacation</TimeOffType>
      <TimeOffCategory>PAID</TimeOffCategory>
      <ShowBalanceToEmployee>true</ShowBalanceToEmployee>
      <UpdatedDateUTC>2014-02-12T10:34:44</UpdatedDateUTC>
    </TimeOffType>
    <TimeOffType>
      <TimeOffTypeID>33e13a4f-a223-46cb-a76d-64559f74a6ee</TimeOffTypeID>
      <TimeOffType>Sick</TimeOffType>
      <TimeOffCategory>PAID</TimeOffCategory>
      <ShowBalanceToEmployee>true</ShowBalanceToEmployee>
      <UpdatedDateUTC>2014-02-12T10:34:44</UpdatedDateUTC>
    </TimeOffType>
  </TimeOffTypes>
</PayItems>