Xero Node.js SDK (OAuth 2.0 Client)

Common errors

• Error: 401 Unauthorized

  cause The access token used for the API request is either missing, invalid, or expired.
  fix Ensure you have completed the OAuth 2.0 authentication flow correctly, retrieved a valid access token, and are setting it on the `XeroClient`. Implement token refresh logic to get a new access token using your refresh token before making requests with an expired token.

• Error: 400 Bad Request - 'The Contacts field is required.' (or similar for other entities)

  cause You are attempting to create or update an entity (e.g., Contacts, Invoices) but the request body is missing or malformed, or required fields within the entity object are not provided.
  fix Verify that your request body adheres to the Xero API schema for the specific endpoint. Ensure all required fields for the entity type are present and correctly formatted. For example, when creating a contact, `contacts: [{ name: '...' }]` is expected.

• Error: Argument of type '{ name: string; }' is not assignable to parameter of type 'Contact'.

  cause This TypeScript error occurs when you pass a plain JavaScript object that doesn't fully conform to the `Contact` (or other model) interface expected by the SDK method.
  fix Explicitly cast your object to the correct type (e.g., `const newContact: Contact = { name: 'Test Contact' };`) or ensure your object strictly matches the model's interface, including all required properties as defined in `xero-node/dist/gen/model/accounting/contact.d.ts`.

Warnings

• breaking Version 13.0.0 introduced breaking changes for Payroll NZ and UK API calls. Specifically, several fields in the `Employee` and `Employment` models (e.g., `firstName`, `lastName`, `dateOfBirth`, `startDate`, `payrollCalendarID`) became required. Calls made with older data models will fail.
  Fix: Review your `Employee` and `Employment` object payloads for Payroll NZ and UK. Ensure all newly required fields are populated before making API calls. Refer to the official Xero API documentation for the exact schema.
• deprecated As of version 13.1.0, several Accounting API endpoints related to `EmployeesAsync` have been marked obsolete and will be removed in future releases. These include `CreateEmployeesAsync`, `GetEmployeeAsync`, `GetEmployeesAsync`, and `UpdateOrCreateEmployeesAsync` variants.
  Fix: Migrate your code to use the supported alternatives for employee management. Consult the Xero API documentation or the Payroll API clients (e.g., `PayrollAuApi`, `PayrollNzApi`, `PayrollUkApi`) for the correct methods.
• breaking Version 12.0.0 introduced a breaking change by adding a new required query parameter, `direction`, to the `getFiles` endpoint. Calls to `getFiles` without this parameter will no longer work.
  Fix: When calling `xero.filesApi.getFiles()`, ensure you provide the `direction` parameter, typically with a value like `'asc'` or `'desc'` to specify sorting order.
• gotcha Xero's OAuth 2.0 flow requires careful management of access tokens and refresh tokens. Access tokens are short-lived (30 minutes) and refresh tokens are valid for 60 days. Failing to refresh an expired access token or properly store/retrieve tokens will lead to authentication failures.
  Fix: Implement robust token storage and refresh logic. The `xero-node` client provides `setTokenSet` and `refreshToken` methods. You should store the `refresh_token` securely and use it to obtain new access tokens when the current one expires.
• gotcha The Xero API expects a `tenantId` (also known as `Xero-Tenant-Id` header) for most operations after authentication. This ID identifies the specific Xero organization you are interacting with. Forgetting to pass it or using an incorrect ID will result in errors.
  Fix: After successful authentication, the `xeroClient.tenantIds` array will contain the IDs of the organizations the user has granted access to. Always pass the relevant `tenantId` (e.g., `xeroClient.tenantIds[0]`) as the first argument to API methods like `getContacts`, `createInvoices`, etc.

Install

• npm install xero-node npm
• yarn add xero-node yarn
• pnpm add xero-node pnpm

Imports

• XeroClient
  wrong:

  const XeroClient = require('xero-node');

  correct:

  import { XeroClient } from 'xero-node';

  The library primarily uses ES Modules and ships with TypeScript types. CommonJS `require` should be avoided.
• AccountingApi
  wrong:

  import { Accounting } from 'xero-node';

  correct:

  import { AccountingApi } from 'xero-node';

  Individual API clients like `AccountingApi`, `PayrollAuApi`, etc., are named exports. Do not confuse with the top-level 'Accounting' concept.
• Contact
  wrong:

  import { Contact } from 'xero-node';

  correct:

  import { Contact } from 'xero-node/dist/gen/model/accounting/contact';

  Specific API models (like `Contact`, `Invoice`, `BankTransaction`) are deeply nested and must be imported from their precise paths, typically within `xero-node/dist/gen/model/<api-set>/<model-name>`.
• IXeroClientConfig
  wrong:

  import { XeroClientConfig } from 'xero-node';

  correct:

  import { IXeroClientConfig } from 'xero-node';

  Configuration interface for the XeroClient, useful for TypeScript users. Often confused with a class.

Quickstart

Demonstrates initializing the XeroClient, managing an access token (refreshing if expired), and making a basic API call to fetch contacts. Requires valid Xero API credentials and an existing tenant ID.

import { XeroClient, Contact, Contacts } from 'xero-node';
import { Response } from 'node-fetch';

const client_id = process.env.XERO_CLIENT_ID ?? '';
const client_secret = process.env.XERO_CLIENT_SECRET ?? '';
const redirect_uri = process.env.XERO_REDIRECT_URI ?? 'http://localhost:3000/callback';
const scopes = ['accounting.contacts.read', 'offline_access'];

const xero = new XeroClient({
  clientId: client_id,
  clientSecret: client_secret,
  redirectUris: [redirect_uri],
  scopes: scopes,
});

async function authenticateAndFetchContacts() {
  if (!client_id || !client_secret) {
    console.error('XERO_CLIENT_ID and XERO_CLIENT_SECRET environment variables must be set.');
    return;
  }

  // In a real application, you would store and retrieve tokens securely.
  // This is a simplified example to get a token via a mock code (requires a valid initial auth flow).
  // For a real-world scenario, you'd perform the OAuth2 dance.
  // For demonstration purposes, we assume a refresh token is available or use a pre-authorized token.
  
  // Example of setting a token from a previous authorization (replace with actual token management)
  xero.setTokenSet({
    access_token: process.env.XERO_ACCESS_TOKEN ?? 'YOUR_INITIAL_ACCESS_TOKEN',
    refresh_token: process.env.XERO_REFRESH_TOKEN ?? 'YOUR_INITIAL_REFRESH_TOKEN',
    expires_at: Date.now() / 1000 + 3600 // Example: expires in 1 hour
  });

  try {
    // Ensure token is fresh
    if (await xero.apiClient.checkTokenSet() && xero.apiClient.tokenSet.expired()) {
        console.log('Access token expired, attempting to refresh...');
        await xero.apiClient.refreshToken();
        console.log('Token refreshed successfully.');
    }

    console.log('Fetching contacts...');
    const contactsResponse = await xero.accountingApi.getContacts(xero.tenantIds[0]);
    const contacts = contactsResponse.body.contacts;
    
    if (contacts && contacts.length > 0) {
      console.log(`Found ${contacts.length} contacts. First contact: ${contacts[0].name}`);
    } else {
      console.log('No contacts found.');
    }
  } catch (error) {
    console.error('Error fetching contacts:', error);
    if (error instanceof Response) {
      const errorBody = await error.text();
      console.error('API Error Response:', errorBody);
    }
  }
}

authenticateAndFetchContacts();