Xero API Integration: A Developer’s Tutorial

5. Making API Calls to Xero (Fetching Unpaid Invoices)

Now for the fun part: using the Xero API to fetch data. With a valid access token and a tenant ID, you can call any of Xero’s API endpoints that your scopes permit. Xero’s APIs include accounting (invoices, contacts, etc.), assets, projects, and more. As an example, let’s fetch unpaid invoices from the accounting API.

Using the Xero Node SDK, we can call the accountingApi.getInvoices method. This returns a list of invoices for the specified tenant. We can then filter or query for the unpaid ones. In Xero, an invoice that is approved and awaiting payment typically has a Status of AUTHORISED (and it will have an AmountDue > 0). We can filter by status in the request or just retrieve and filter in code. Here’s how to do it:

// Assuming xero.accountingApi is available after authentication and we have tenantId
const result = await xero.accountingApi.getInvoices(tenantId);
// The SDK returns a response object; the invoices are inside .body or .records depending on version
const invoices = result.body.Invoices || result.body.invoices || result.body; 
// (Adjust based on actual SDK response structure)
const unpaidInvoices = invoices.filter(inv => inv.Status === 'AUTHORISED');
console.log(`Found ${unpaidInvoices.length} unpaid invoices in Xero.`);
unpaidInvoices.forEach(inv => {
  console.log(`${inv.InvoiceNumber}: Due ${inv.AmountDue} ${inv.CurrencyCode} by ${inv.DueDate}`);
});

The above code retrieves all invoices and filters those with Status == 'AUTHORISED'. You could also check inv.AmountDue > 0 to catch any partially paid invoices. If performance is a concern (e.g., thousands of invoices), Xero’s API supports a “where” query parameter to filter server-side (the SDK might let you pass a filter string). For instance, you could query getInvoices(tenantId, { where: 'Status=="AUTHORISED"' }) to have Xero return only “AUTHORISED” invoices. Check the Xero API docs for the exact syntax and capabilities of queries.

Using REST calls (Axios) directly: While the SDK simplifies things, you can also call the API with a standard HTTP client. For example, using axios:

const axios = require('axios');
const response = await axios.get('https://api.xero.com/api.xro/2.0/Invoices', {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Xero-Tenant-Id': tenantId,
    Accept: 'application/json'
  }
});
const invoices = response.data.Invoices;

This hits the same endpoint directly. Notice we must include the Authorization header with the Bearer token and the Xero-Tenant-Id header with the tenantId. The base URL for Xero’s accounting API is https://api.xero.com/api.xro/2.0/, and we append the endpoint (Invoices). The response JSON contains an array of Invoices. You can filter those similarly. Using the SDK or raw HTTP is up to you – the SDK handles some boilerplate (like constructing URLs, etc.) and provides TypeScript definitions, whereas direct HTTP calls give you more control or may be more familiar in simple cases.

Either way, at this point your backend service can successfully pull data from Xero. You could extend this to other endpoints: e.g., fetching Contacts, Accounts, or creating new invoices or payments. Be mindful of rate limits (Xero allows a certain number of calls per minute/day), and implement error handling. For example, handle 401 Unauthorized (token expired, you need to then refresh and retry) and 429 Too Many Requests (rate limit hit, you need to back off accordingly).

Congratulations, you’ve built a basic Xero API integration in Node.js, complete with OAuth 2.0 authentication, secure token handling, tenant selection, and data retrieval. We went through registering a Xero developer app, implementing the OAuth flow step by step, and making API calls to fetch real accounting data. Along the way, you learned about important concepts like access/refresh tokens and Xero tenant IDs, which are crucial for any Xero integration.