Skip to main content

Xero — Application Overview

Xero is a cloud-based accounting platform used by finance teams, accountants, and small-to-medium businesses to manage invoices, contacts, items, purchase orders, tax rates, and multi-currency transactions.

The Xero integration within the Wrk platform allows you to automate accounting Wrkflows by calling the Xero Accounting API through Wrk Actions.

This document provides an overview of how Xero integrates into Wrk, how authentication works, general API behaviour, and a full list of available Wrk Actions.

Authentication​

Xero uses OAuth 2.0 authentication for all Accounting API access.

When connecting Xero via OAuth 2.0:

  • Authentication is initiated directly inside Wrk.
  • Users are redirected to Xero to authorize access.
  • Wrk receives an access token that is used for all subsequent API calls.
  • Tokens are scoped based on the permissions granted during authorization

Important Notes​

  • Xero connections are organization-specific (tenant-based).
  • Wrk automatically refreshes access tokens in the background. If access is revoked inside Xero or organization permissions change, the connection must be reauthenticated.

General API Behaviour​

Base URL and response structure​

The integration uses the Xero Accounting API.

Most Xero API calls return JSON responses that commonly include::

  • ID — Globally unique identifier (UUID format)
  • Status — API execution status (e.g., OK)
  • ProviderName — Application name registered with Xero
  • UpdatedDateUTC — Timestamp of the response
  • Pagination — Pagination metadata (when applicable)
  • Entity Collection — Contacts, Invoices, Items, etc. E.g. Contacts: []

All requests must specify the correct Xero tenant (organization). One can be selected using the Tenant name input or if left blank, it will use the first organization found.

Pagination​

Xero supports pagination on list-style endpoints using:

  • page parameter (page number, 1-based indexing)

Each page returns up to 100 records by default.

When working with large datasets, Wrkflows should iterate page-by-page to ensure complete data retrieval.

Filtering​

Using filters is your go-to for complex, conditional retrievals. It allows you to build sophisticated queries using a SQL-like syntax right in your API request.

  • Syntax: {PropertyName}{Operator}{Value}

  • Key Features:

  • Operators:

    • ==, !=, <, <=, >, >= for exact matches and comparisons.
    • StartsWith(), EndsWith(), Contains() for powerful string matching.
    • AND, OR for combining multiple conditions.

  • Type-Aware: Handles strings (in quotes), numbers, booleans, dates (DateTime(YYYY, MM, DD)), and even GUIDs (GUID("...")).

  • Examples:

    • Status=="AUTHORISED"
    • Name.Contains("Ltd")

Filtering allows Wrkflows to retrieve:

  • Only open invoices
  • Contacts matching a specific name
  • Purchase orders in a particular state

Sorting​

Sorting is supported on many endpoints using the Sort order parameter.

Example:

{PropertyName} [DESC], e.g. Date DESC

Sorting is particularly important when:

  • Paging through data
  • Retrieving the most recent invoices
  • Maintaining consistent ordering between requests

Multi-Currency Behaviour​

If multi-currency is enabled in Xero:

  • Invoices may include CurrencyCode and exchange rate fields.
  • Currency retrieval endpoints return all enabled currencies for the organization.

Wrkflows should ensure currency codes match the organization’s configured currencies.

Rate Limiting​

Xero enforces API rate limits at both:

  • Per-minute level
  • Daily level

If limits are exceeded, Xero may return:

  • HTTP 429 Too Many Requests

Wrkflows calling high-volume endpoints should implement controlled batching and avoid unnecessary repeated calls.

Available Wrk Actions​

  • Create items in Xero
  • Create or update items in Xero
  • Send invoice to email in Xero
  • Retrieve contacts from Xero
  • Retrieve currencies from Xero
  • Retrieve invoices from Xero
  • Retrieve items from Xero
  • Retrieve purchase orders from Xero
  • Retrieve tax rates from Xero
  • Retrieve a link to an online invoice from Xero
  • Delete an item from Xero

Additional Resources​

Xero Accounting API Overview:

​https://developer.xero.com/documentation/api/accounting/overview

Authentication (OAuth 2.0):

​https://developer.xero.com/documentation/guides/oauth2/overview

Pagination Guide:

​https://developer.xero.com/documentation/best-practices/api-call-efficiencies/paging

Rate Limiting:

​https://developer.xero.com/documentation/best-practices/api-call-efficiencies/rate-limits

Filtering Guide: https://developer.xero.com/documentation/best-practices/api-call-efficiencies/filtering

Date-based filtering: https://developer.xero.com/documentation/best-practices/api-call-efficiencies/if-modified-since