PayRuns


Overview

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

Elements for PayRuns

The following are required to create a new pay run
PayScheduleID Xero Identifier for the Pay Schedule
The following are optional to create a new pay run
PayRunPeriodEndDate Pay run period end date. Needed if it is an unscheduled pay run
PayRunStatus See Pay run status types
Elements returned on a GET request only
PayRunID Xero identifier for pay run
PayRunPeriodStartDate Period Start Date for the PayRun
PaymentDate Payment Date for the PayRun
Earnings Total Earnings for the PayRun
Deductions Total Deduction for the PayRun
Reimbursement Total Reimbursement for the PayRun
NetPay Total NetPay for the PayRun
UpdateDateUTC The update date for the PayRun
PayStubs See PayStubs

GET PayRuns

Optional parameters for GET PayRuns

Record filter You can specify an individual record by appending the value to the endpoint, i.e.
GET https://…/PayRuns/{identifier}
PayRunID The Xero identifier for a Pay run e.g. 297c2dc5-cc47-4afd-0000-74990b8761e9
You can get all reimbursement types by appending list at the end of super fund endpoint.
GET https://…/payruns
Modified After The ModifiedAfter filter is actually an HTTP header: ‘If-Modified-Since‘.
A UTC timestamp (yyyy-mm-ddThh:mm:ss) . Only employees created or modified since this timestamp will be returned e.g. 2009-11-12T00:00:00
Page By default the number of records returned per call is 100. You can add GET https://…/payruns?page=2 to get the next set of records
Where Use PayRunStatus==Draft for all Draft Payrun and use PayRunStatus==Posted for all posted payruns. Filter by an any element (see Filters)
Order Order by any element returned (see Order By)

Example response for GET PayRuns/{identifier}

<PayRuns>
    <PayRun>
      <PayRunID>5fd08c46-6057-47d9-8f03-4f2153d2dea8</PayRunID>
      <PayScheduleID>d2ec5abc-2487-4d47-b9ac-bca09e1470bd</PayScheduleID>
      <PayRunPeriodStartDate>2014-03-01T00:00:00</PayRunPeriodStartDate>
      <PayRunPeriodEndDate>2014-03-07T00:00:00</PayRunPeriodEndDate>
      <PaymentDate>2014-03-09T00:00:00</PaymentDate>
      <Earnings>3096.23</Earnings>
      <Deductions>18.19</Deductions>
      <Tax>943.32</Tax>
      <Reimbursement>0.00</Reimbursement>
      <NetPay>2134.72</NetPay>
      <PayRunStatus>DRAFT</PayRunStatus>
      <UpdatedDateUTC>2014-03-25T05:33:51</UpdatedDateUTC>
      <Paystubs>
        <Paystub>
          <EmployeeID>7b15677d-b93c-4546-84aa-34395aeaffd6</EmployeeID>
          <PaystubID>fe8ea0be-1ea9-4fa6-9c18-18cd41c57de6</PaystubID>
          <FirstName>Payrun</FirstName>
          <LastName>Post</LastName>
          <LastEdited>2014-03-25T05:33:51</LastEdited>
          <Earnings>1577.00</Earnings>
          <Deductions>0.00</Deductions>
          <Tax>542.24</Tax>
          <Reimbursements>0.00</Reimbursements>
          <NetPay>1034.76</NetPay>
          <UpdatedDateUTC>2014-03-25T05:33:51</UpdatedDateUTC>
        </Paystub>
        <Paystub>
          <EmployeeID>de5d4e8c-ae2b-40aa-91cb-8eabd75c9ed5</EmployeeID>
          <PaystubID>8bb36b8b-3835-4680-8647-269f1172679e</PaystubID>
          <FirstName>what</FirstName>
          <LastName>what</LastName>
          <Earnings>1519.23</Earnings>
          <Deductions>18.19</Deductions>
          <Tax>401.08</Tax>
          <Reimbursements>0.00</Reimbursements>
          <NetPay>1099.96</NetPay>
          <UpdatedDateUTC>2014-03-25T05:33:51</UpdatedDateUTC>
        </Paystub>
      </Paystubs>
    </PayRun>
  </PayRuns>

Example response for GET PayRuns

  <PayRuns>
    <PayRun>
      <PayRunID>5fd08c46-6057-47d9-8f03-4f2153d2dea8</PayRunID>
      <PayScheduleID>d2ec5abc-2487-4d47-b9ac-bca09e1470bd</PayScheduleID>
      <PayRunPeriodStartDate>2014-03-01T00:00:00</PayRunPeriodStartDate>
      <PayRunPeriodEndDate>2014-03-07T00:00:00</PayRunPeriodEndDate>
      <PaymentDate>2014-03-09T00:00:00</PaymentDate>
      <Earnings>3096.23</Earnings>
      <Deductions>18.19</Deductions>
      <Tax>943.32</Tax>
      <Reimbursement>0.00</Reimbursement>
      <NetPay>2134.72</NetPay>
      <PayRunStatus>DRAFT</PayRunStatus>
      <UpdatedDateUTC>2014-03-25T05:33:51</UpdatedDateUTC>
    </PayRun>
    <PayRun>
      <PayRunID>3d0c7874-0be7-4a04-89bb-4a56463c1f95</PayRunID>
      <PayScheduleID>3f29f8e1-e4aa-4d2b-a946-393b5269ef62</PayScheduleID>
      <PayRunPeriodStartDate>2014-02-01T00:00:00</PayRunPeriodStartDate>
      <PayRunPeriodEndDate>2014-02-28T00:00:00</PayRunPeriodEndDate>
      <PaymentDate>2014-02-21T00:00:00</PaymentDate>
      <Earnings>6000.00</Earnings>
      <Deductions>0.00</Deductions>
      <Tax>1883.34</Tax>
      <Reimbursement>0.00</Reimbursement>
      <NetPay>4116.66</NetPay>
      <PayRunStatus>APPROVED</PayRunStatus>
      <UpdatedDateUTC>2014-02-13T02:57:40</UpdatedDateUTC>
    </PayRun>
  </PayRuns>

POST PayRuns

Example request for creating a scheduled PayRun

<PayRuns>
  <PayRun>
    <PayScheduleID>d2ec5abc-2487-4d47-b9ac-bca09e1470bd</PayScheduleID>
  </PayRun>
</PayRuns>

Example request for creating an unscheduled PayRun

<PayRuns>
  <PayRun>
    <PayScheduleID>d2ec5abc-2487-4d47-b9ac-bca09e1470bd</PayScheduleID>
    <PayRunPeriodEndDate>2014-03-07T00:00:00</PayRunPeriodEndDate>
  </PayRun>
</PayRuns>>

Example request for creating and Posting a scheduled PayRun

<Payruns>
  <PayRun>
    <PayScheduleID>bba1d10f-63b1-4692-b5c5-a99f869523a2</PayScheduleID>
    <PayRunStatus>APPROVED</PayRunStatus>
  </PayRun>
</Payruns>

Example request for creating and Posting an unscheduled PayRun

<Payruns>
  <PayRun>
    <PayScheduleID>bba1d10f-63b1-4692-b5c5-a99f869523a2</PayScheduleID>
    <PayRunPeriodEndDate>2013-02-07T00:00:00</PayRunPeriodEndDate>
    <PayRunStatus>APPROVED</PayRunStatus>
  </PayRun>
</Payruns>

Example response from creating a PayRun

<PayRuns>
  <PayRun>
      <PayRunID>6a0ae4aa-1ff9-4ef6-9d7e-e116f0d05f51</PayRunID>
      <PayrollCalendarID>5c05eed9-b621-4ab3-9a62-c472a3921b92</PayrollCalendarID>
      <PayRunPeriodStartDate>2014-03-28T00:00:00</PayRunPeriodStartDate>
      <PayRunPeriodEndDate>2014-04-03T00:00:00</PayRunPeriodEndDate>
      <PaymentDate>2014-03-31T00:00:00</PaymentDate>
      <PayRunStatus>DRAFT</PayRunStatus>
      <UpdatedDateUTC>2014-03-27T23:03:40.0824724</UpdatedDateUTC>
  <PayRun>
<PayRuns>