Registry / crm-productivity / xero-node

xero-node

JSON →
library15.0.0jsnpmunverified

The xero-node SDK provides a comprehensive client for interacting with the Xero APIs (Accounting, Assets, Bankfeeds, Files, Projects, Payroll AU/NZ/UK) using Node.js. It facilitates OAuth 2.0 authentication and API requests, simplifying integration for developers building applications that connect with Xero accounting data. The library is currently in its 15.0.0 major version, with frequent updates (multiple minor/patch releases per month, and major releases roughly every few months) to reflect changes in the underlying Xero API and add new features. Key differentiators include full API coverage across multiple Xero API sets and robust TypeScript support, making it suitable for enterprise-grade integrations requiring strong typing and reliability.

npm install xero-node
INSTALL
IMPORT
SIG · XERO-NODE
X
xero-node
crm-productivityjavascriptv15.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

XeroClient
import { XeroClient } from 'xero-node';
const XeroClient = require('xero-node');
The library primarily uses ES Modules and ships with TypeScript types. CommonJS `require` should be avoided.
AccountingApi
import { AccountingApi } from 'xero-node';
import { Accounting } from 'xero-node';
Individual API clients like `AccountingApi`, `PayrollAuApi`, etc., are named exports. Do not confuse with the top-level 'Accounting' concept.
Contact
import { Contact } from 'xero-node/dist/gen/model/accounting/contact';
import { Contact } from 'xero-node';
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
import { IXeroClientConfig } from 'xero-node';
import { XeroClientConfig } from 'xero-node';
Configuration interface for the XeroClient, useful for TypeScript users. Often confused with a class.

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();
Debug
Known issues
breakingVersion 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.
affects: >=13.0.0
deprecatedAs 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.
affects: >=13.1.0
breakingVersion 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.
affects: >=12.0.0
gotchaXero'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.
affects: >=1.0.0
gotchaThe 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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: 401 Unauthorized
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)
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'.
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`.
Upgrade
Version history
15.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
56 hits · last 30 days
node
50
Perplexity
1
OpenAI (training)
1
Resources