Add earnings rates endpoint to Payroll-Api-AU #752

sue-obeirne-xero · 2025-10-01T04:25:52Z

Description

Adding docs for updating the V2 earnings rate endpoint to be enabled for AU region to GET, POST and GET/{Id}

Release Notes

Enables AU consumers to get earnings rates without having to get Payitems object
Better validation messages
Correct error handling

Screenshots (if appropriate):

Types of Changes

Bug fix (non-breaking change that fixes an issue)
New feature (non-breaking change that adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)

github-actions · 2025-10-01T04:26:09Z

PETOSS-823

github-actions · 2025-10-01T04:26:10Z

Thanks for raising an issue, a ticket has been created to track your request

rickyh5000 · 2025-10-01T22:30:34Z

xero-payroll-au.yaml

    url: https://github.com/XeroAPI/Xero-OpenAPI/blob/master/LICENSE
 servers:
-  - description: Xero Payroll AU API
+  - description: Xero Payroll AU API (v1)


Does this mean all the new earnings rates endpoints (that are calling the public api V2) will be under this v1?

Maybe we need a new seperate server for our new endpoitns?

rickyh5000 · 2025-10-01T22:39:24Z

xero-payroll-au.yaml

+        - in: query
+          name: page
+          description: Page number which specifies the set of records to retrieve. By default the number of the records per set is 100. When page value is not a number or a negative number, by default, the first set of records is returned
+          example: https://api.xero.com/payroll.xro/2.0/earningsRates?page=2 to get the second set of the records.


Should this just be the page number? And not the entire query

good catch yes!!

xero-payroll-au.yaml

rickyh5000 · 2025-10-01T22:49:37Z

xero-payroll-au.yaml

+      tags:
+        - PayrollAu
+      operationId: getEarningsRates
+      x-hasPayrollUkProblem: true


What is this for?

Its a vendor extension used for generation of the SDKs from the spec...specifically java sdk in this case 😀 Theres a list in xero-internal I'll send to you

rickyh5000 · 2025-10-01T22:54:14Z

xero-payroll-au.yaml

+      tags:
+        - PayrollAu
+      operationId: createEarningsRate
+      x-hasPayrollUkProblem: true


xero-payroll-au.yaml

rickyh5000 · 2025-10-01T22:57:59Z

xero-payroll-au.yaml

+      operationId: getEarningsRate
+      servers: 
+      - url: https://api.xero.com/payroll.xro/2.0
+      x-hasPayrollUkProblem: true


rickyh5000 · 2025-10-02T00:49:49Z

xero-payroll-au.yaml

+    Pagination:
+      properties:
+        page:
+          type: integer
+          example: 1
+        pageSize:
+          type: integer
+          example: 10
+        pageCount:
+          type: integer
+          example: 1
+        itemCount:
+          type: integer
+          example: 2
+    Problem:
+      description: The object returned for a bad request
+      type: object
+      properties:
+        type:
+          description: The type of error format
+          type: string
+          example: application/problem+json
+        title:
+          description: The type of the error
+          type: string
+          example: BadRequest
+        status:
+          description: The error status code
+          type: string
+          example: 400
+        detail:
+          description: A description of the error
+          type: string
+          example: Validation error occurred.
+        instance:
+          type: string
+        invalidFields:
+          type: array
+          items:
+            $ref: '#/components/schemas/InvalidField'
+    InvalidField:
+      type: object
+      properties:
+        name:
+          description: The name of the field that caused the error
+          type: string
+          example: isExemptFromSuper
+        reason:
+          description: The reason the error occurred
+          type: string
+          example: The property isExemptFromSuper is required.


Are these meant to be here?

yep they are part of the open api schema for the v2 endpoints

rickyh5000 · 2025-10-02T00:51:58Z

xero-payroll-au.yaml

+          description: For allowances using RatePerUnit only,  whether it contributes towards the overtime rate.
+          type: boolean
+          example: false
+    EarningsRateObject:


What's the difference between this EarningsRateObject and EarningsRates? Because we also have V1 and V2 as well:

EarningsRateObject needs to be cleaned up thank you!

sue-obeirne-xero · 2025-10-02T04:31:57Z

xero-payroll-au.yaml

+      operationId: getEarningsRates
+      x-hasPayrollUkProblem: true
+      servers: 
+      - url: https://api.xero.com/payroll.xro/2.0


@rickyh5000 have left the server uri as is and only added the V2 server uri for the V2 endpoints... however if you think it would be easier to understand we can always put both server uris into the dropdown?

I just think it might be a bit misleading but not sure how easy it is to put the V2 server uri into the dropdown

… for pagination query param, remove unnecessary object

…dler

rickyh5000 · 2025-10-06T01:09:46Z

xero-payroll-au.yaml

+          type: boolean
+          example: false
+        AccrueLeave:
+          description:  Indicates that this earnings rate should affect accruing of leave. Only applicable if RateType is MULTIPLEOFORDINARYEARNINGSRATE


Suggested change

description: Indicates that this earnings rate should affect accruing of leave. Only applicable if RateType is MULTIPLEOFORDINARYEARNINGSRATE

description: Indicates that this earnings rate should affect accruing of leave.

Not sure if we need that extra part here, this feels like more just a generic description and the Required if RateType is MultipleOfOrdinaryEarningsRate is more for the POST only

Add earnings rates endpoint to payroll api au

6cd1df1