Module xero.finance

ballerinax/xero.finance Ballerina library

2.0.0

Overview

Xero is a cloud-based accounting platform for small and medium-sized businesses. The Xero Finance API gives lenders and financial partners read access to an organisation's financial statements, bank statement data and cash validation summaries so that they can assess a loan application with confidence.

The Xero Finance connector lets Ballerina applications call the Xero Finance API, version 19.0.0. It provides methods for financial statement reports, revenue and expense by contact reports, cash validation and bank statement accounting data.

Key features

  • Retrieve balance sheet, profit and loss, cash flow and trial balance reports
  • Analyse revenue and expense totals by customer and supplier contact
  • Validate cash positions across bank accounts and reconciled statement lines
  • Access bank statement data together with the matching accounting transactions
  • Authenticate with OAuth 2.0 using a refresh token or a bearer token

Setup guide

To use the Xero Finance connector you need a Xero account, a registered app and an access token that grants the finance scopes.

  1. Sign in to the Xero developer portal and select New app.

  2. Enter an app name and company URL, choose Web app, and add a redirect URI that your application controls.

  3. Open the Configuration page of the app and copy the Client id. Generate a Client secret and copy it.

  4. Request the scopes your use case needs when you authorise the app: offline_access, finance.statements.read, finance.cashvalidation.read and finance.bankstatementsplus.read.

  5. Complete the authorisation code flow to obtain a refresh token. The token endpoint is https://identity.xero.com/connect/token.

  6. Call the GET https://api.xero.com/connections endpoint with the access token and copy the tenantId of the organisation you want to query.

Note: The Finance API is available to Xero partners with the required finance scopes enabled for the app.

Quickstart

To use the xero.finance connector in your Ballerina application, update the .bal file as follows:

Step 1: Import the module

Copy
import ballerinax/xero.finance;

Step 2: Instantiate a new connector

Create a Config.toml file with your credentials:

Copy
clientId = "<CLIENT_ID>"
clientSecret = "<CLIENT_SECRET>"
refreshToken = "<REFRESH_TOKEN>"
tenantId = "<TENANT_ID>"

Then create a finance:Client using them:

Copy
configurable string clientId = ?;
configurable string clientSecret = ?;
configurable string refreshToken = ?;
configurable string tenantId = ?;

finance:Client xero = check new ({
    auth: {
        clientId,
        clientSecret,
        refreshToken,
        refreshUrl: "https://identity.xero.com/connect/token"
    }
});

Step 3: Invoke the connector operation

Retrieve the balance sheet report:

Copy
public function main() returns error? {
    finance:BalanceSheetResponse _ = check xero->getFinancialStatementBalanceSheet({xeroTenantId: tenantId});
}

Step 4: Run the Ballerina application

Copy
bal run

Examples

The Xero Finance connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:

  1. Period-end financial review - Summarise the balance sheet, profit and loss and trial balance for a reporting period.
  2. Contact revenue and expense analysis - Compare revenue and expense by contact and check the cash validation position.

Import

import ballerinax/xero.finance;Copy

Other versions

See more...

Metadata

Released date: 1 day ago

Version: 2.0.0

License: Apache-2.0


Security

No known vulnerabilities in libraries

Checked on 2026-11-21 via OSV.dev


Compatibility

Platform: any

Ballerina version: 2201.13.0

GraalVM compatible: Yes


Pull count

Total: 46

Current verison: 1


Weekly downloads


Source repository


Keywords

Vendor/Xero

Area/Finance & Accounting

Type/Connector


Contributors