+ 
+
+
+
+
+
+
+ getAccountBalances
+Get the balance of each general ledger account as at a given date
+Retrieves account balances as at date, optionally including balances for one or
+more prior comparison periods, and optionally filtered by account class, type,
+account IDs, system account code, or tracking item.
Filtering
+-
+
- Filter by
class,type,accountIds, and/orsystemAccountCodes. These can be +combined freely — when more than one is supplied, the server returns only accounts +that match all of the supplied filters (an intersection, not a union).
+ typevalues are matched case-sensitively, so use uppercase (for exampleBANK). Inventory +asset accounts are reported as, and can only be filtered by,INVENTORY; filtering by +their underlying account type does not match them.
+trackingItemIdsandunassignedToTrackingCategoryIdscan be used independently of +the filters above to further narrow which accounts are returned.
+
Comparison periods
+-
+
- Supplying
comparisonPeriodCounttogether withcomparisonPeriodSizereturns +additional balances at prior points in time, in addition to the balance atdate.
+ - The n-th comparison date is
dateshifted back n timescomparisonPeriodSize. ForMONTH, +QUARTER, andYEARsizes, adatethat falls on the last day of its month keeps landing +on the last day of the shifted month (so comparisons across February behave correctly).
+ comparisonPeriodCountandcomparisonPeriodSizemust be supplied together.
+
Bank accounts
+Bank account data is only available to users with bank account view permission for the +organisation.
+-
+
- If the request would include bank accounts and the user lacks this permission, it is
+rejected with
403 Forbidden. A request is treated as including bank accounts when it +has no account filters, filters by all fiveclassvalues and nothing else, includes +BANKintype, or lists a bank account inaccountIds.
+ - For other requests (for example
class=ASSET), bank accounts are silently excluded from +the response for users without this permission, instead of the request being rejected.
+
Results
+Only accounts with a non-zero balance at a given date are returned; accounts and comparison +dates with a net-zero balance are omitted, so the response can be empty.
+Pagination
+This endpoint does not paginate — all matching account balances are returned in a single +response.
+ + ++
/account-balances+
Usage and SDK Samples
+ + +
+
+
+
+
+ await xero.setTokenSet(tokenSet);
+
+const accountingBasis = 'ACCRUAL';
+const date: Date = new Date("2024-12-31");
+const xeroTenantId = '2ae32d9e-4711-4201-9f2a-ac80e5318359';
+const comparisonPeriodCount = 3;
+const comparisonPeriodSize = 'MONTH';
+const accountIds = [];
+const class = [];
+const type = [];
+const systemAccountCodes = [];
+const trackingItemIds = [];
+const unassignedToTrackingCategoryIds = [];
+
+try {
+ const response = await xero.accountingApi.getAccountBalances(accountingBasis, date, xeroTenantId, comparisonPeriodCount, comparisonPeriodSize, accountIds, class, type, systemAccountCodes, trackingItemIds, unassignedToTrackingCategoryIds);
+ console.log(response.body || response.response.statusCode)
+} catch (err) {
+ const error = JSON.stringify(err.response.body, null, 2)
+ console.log(`Status Code: ${err.response.statusCode} => ${error}`);
+}Scopes
+| accountdata.balances.read | +Read general ledger account balances | +
Parameters
+Header parameters
+ | Name | +Description | +
|---|---|
| Xero-Tenant-Id* | +
+
+
+
+
+
+
+
+
+ UUID
+
+
+ (uuid)
+
+
+
+
+The ID of the Xero organisation to query.
+
+
+ Required
+
+ |
+
Query parameters
+ | Name | +Description | +
|---|---|
| accountingBasis* | +
+
+
+
+
+
+
+
+
+ String
+
+
+
+
+Accounting basis for the balance calculation.
+
+
+ Required
+
+ |
+
| date* | +
+
+
+
+
+
+
+
+
+ date
+
+
+ (date)
+
+
+
+
+The date to calculate account balances as at, in ISO 8601 format (YYYY-MM-DD).
+
+
+ Required
+
+ |
+
| comparisonPeriodCount | +
+
+
+
+
+
+
+
+
+ Integer
+
+
+ (int32)
+
+
+
+
+
+ Number of additional comparison balances to return, each one further back in
+time than the last. Must be supplied together with
|
+
| comparisonPeriodSize | +
+
+
+
+
+
+
+
+
+ String
+
+
+
+
+The unit of time each comparison period steps back by. Must be supplied
+together with
+ comparisonPeriodCount.
+ |
+
| accountIds | +
+
+
+
+
+
+
+
+
+ array[UUID]
+
+
+ (uuid)
+
+
+
+
+
+ Filter to specific account IDs (GUIDs). Repeat the parameter for multiple +accounts. +
|
+
| class | +
+
+
+
+
+
+
+
+
+ array[String]
+
+
+
+
+Account classes to filter by. Can be combined with other filters.
+
+ |
+
| type | +
+
+
+
+
+
+
+
+
+ array[String]
+
+
+
+
+Account types to filter by (e.g.
+ BANK, CURRENT, etc). Use INVENTORY to
+match inventory asset accounts, regardless of their underlying account type.
+Can be combined with other filters.
+ |
+
| systemAccountCodes | +
+
+
+
+
+
+
+
+
+ array[String]
+
+
+
+
+System account codes to filter by (e.g.
+ RETAINEDEARNINGS,
+UNREALISEDGAINS). Can be combined with other filters.
+ |
+
| trackingItemIds | +
+
+
+
+
+
+
+
+
+ array[UUID]
+
+
+ (uuid)
+
+
+
+
+Filter to accounts assigned to any of the given tracking item IDs.
+
+ |
+
| unassignedToTrackingCategoryIds | +
+
+
+
+
+
+
+
+
+ array[UUID]
+
+
+ (uuid)
+
+
+
+
+Filter to accounts that are not assigned to any tracking option within the
+given tracking category IDs.
+
+ |
+