From 3c0e27df757bc46db87782b1f6b7d4ee312dbaf9 Mon Sep 17 00:00:00 2001 From: Github Actions Date: Tue, 10 Nov 2026 05:42:35 +0000 Subject: [PATCH] Releasing 18.4.0 (OAS: 20.0.1) --- Gemfile.lock | 2 +- docs/account_data/Account.md | 27 + docs/account_data/AccountBalance.md | 25 + docs/account_data/AccountBalancesResponse.md | 17 + docs/account_data/AccountDataApi.md | 297 ++ docs/account_data/AccountMovement.md | 35 + docs/account_data/AccountMovementsResponse.md | 17 + docs/account_data/AccountTransactionLine.md | 37 + .../AccountTransactionsResponse.md | 23 + .../AccountTransactionsResponsePagination.md | 19 + docs/account_data/AccountingDateRange.md | 19 + docs/account_data/FieldProblem.md | 27 + docs/account_data/GatewayProblem.md | 27 + docs/account_data/LedgerDecimal.md | 19 + docs/account_data/LineSource.md | 27 + docs/account_data/LineTaxRate.md | 21 + docs/account_data/ProblemDetails.md | 25 + docs/account_data/TrackingItemDetails.md | 21 + docs/account_data/TransactionAccount.md | 29 + docs/account_data/ValidationProblem.md | 27 + docs/account_data/index.html | 4404 +++++++++++++++++ docs/accounting/index.html | 3 +- docs/app_store/index.html | 3 +- docs/assets/index.html | 3 +- docs/files/index.html | 3 +- docs/finance/index.html | 3 +- docs/payroll_au/index.html | 3 +- docs/payroll_au_v2/index.html | 3 +- docs/payroll_nz/index.html | 3 +- docs/payroll_uk/index.html | 3 +- docs/projects/index.html | 3 +- lib/xero-ruby.rb | 19 + lib/xero-ruby/api/account_data_api.rb | 419 ++ lib/xero-ruby/api_client.rb | 10 + lib/xero-ruby/configuration.rb | 2 + lib/xero-ruby/models/account_data/account.rb | 351 ++ .../models/account_data/account_balance.rb | 287 ++ .../account_data/account_balances_response.rb | 229 + .../models/account_data/account_movement.rb | 347 ++ .../account_movements_response.rb | 229 + .../account_data/account_transaction_line.rb | 359 ++ .../account_transactions_response.rb | 269 + ...ccount_transactions_response_pagination.rb | 243 + .../account_data/accounting_date_range.rb | 242 + .../models/account_data/field_problem.rb | 273 + .../models/account_data/gateway_problem.rb | 285 ++ .../models/account_data/ledger_decimal.rb | 278 ++ .../models/account_data/line_source.rb | 273 + .../models/account_data/line_tax_rate.rb | 243 + .../models/account_data/problem_details.rb | 273 + .../account_data/tracking_item_details.rb | 257 + .../account_data/transaction_account.rb | 366 ++ .../models/account_data/validation_problem.rb | 275 + lib/xero-ruby/version.rb | 4 +- 54 files changed, 10695 insertions(+), 13 deletions(-) create mode 100644 docs/account_data/Account.md create mode 100644 docs/account_data/AccountBalance.md create mode 100644 docs/account_data/AccountBalancesResponse.md create mode 100644 docs/account_data/AccountDataApi.md create mode 100644 docs/account_data/AccountMovement.md create mode 100644 docs/account_data/AccountMovementsResponse.md create mode 100644 docs/account_data/AccountTransactionLine.md create mode 100644 docs/account_data/AccountTransactionsResponse.md create mode 100644 docs/account_data/AccountTransactionsResponsePagination.md create mode 100644 docs/account_data/AccountingDateRange.md create mode 100644 docs/account_data/FieldProblem.md create mode 100644 docs/account_data/GatewayProblem.md create mode 100644 docs/account_data/LedgerDecimal.md create mode 100644 docs/account_data/LineSource.md create mode 100644 docs/account_data/LineTaxRate.md create mode 100644 docs/account_data/ProblemDetails.md create mode 100644 docs/account_data/TrackingItemDetails.md create mode 100644 docs/account_data/TransactionAccount.md create mode 100644 docs/account_data/ValidationProblem.md create mode 100644 docs/account_data/index.html create mode 100644 lib/xero-ruby/api/account_data_api.rb create mode 100644 lib/xero-ruby/models/account_data/account.rb create mode 100644 lib/xero-ruby/models/account_data/account_balance.rb create mode 100644 lib/xero-ruby/models/account_data/account_balances_response.rb create mode 100644 lib/xero-ruby/models/account_data/account_movement.rb create mode 100644 lib/xero-ruby/models/account_data/account_movements_response.rb create mode 100644 lib/xero-ruby/models/account_data/account_transaction_line.rb create mode 100644 lib/xero-ruby/models/account_data/account_transactions_response.rb create mode 100644 lib/xero-ruby/models/account_data/account_transactions_response_pagination.rb create mode 100644 lib/xero-ruby/models/account_data/accounting_date_range.rb create mode 100644 lib/xero-ruby/models/account_data/field_problem.rb create mode 100644 lib/xero-ruby/models/account_data/gateway_problem.rb create mode 100644 lib/xero-ruby/models/account_data/ledger_decimal.rb create mode 100644 lib/xero-ruby/models/account_data/line_source.rb create mode 100644 lib/xero-ruby/models/account_data/line_tax_rate.rb create mode 100644 lib/xero-ruby/models/account_data/problem_details.rb create mode 100644 lib/xero-ruby/models/account_data/tracking_item_details.rb create mode 100644 lib/xero-ruby/models/account_data/transaction_account.rb create mode 100644 lib/xero-ruby/models/account_data/validation_problem.rb diff --git a/Gemfile.lock b/Gemfile.lock index de1bd726..26992a6f 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,7 +1,7 @@ PATH remote: . specs: - xero-ruby (18.3.0) + xero-ruby (18.4.0) faraday (>= 2.0, < 3.0) json (~> 2.1, >= 2.1.0) json-jwt (~> 1.16, >= 1.16.3) diff --git a/docs/account_data/Account.md b/docs/account_data/Account.md new file mode 100644 index 00000000..16859694 --- /dev/null +++ b/docs/account_data/Account.md @@ -0,0 +1,27 @@ +# XeroRuby::AccountData::Account + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**code** | **String** | | [optional] +**name** | **String** | | +**_class** | **String** | | +**type** | **String** | Account type (e.g. `BANK`, `CURRENT`). Reported as `INVENTORY` for inventory asset accounts, regardless of the account's underlying type. | +**status** | **String** | | +**system_account_code** | **String** | System account code, or `NONE` if the account has no system account code. | + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::Account.new(code: null, + name: null, + _class: null, + type: null, + status: null, + system_account_code: null) +``` + + diff --git a/docs/account_data/AccountBalance.md b/docs/account_data/AccountBalance.md new file mode 100644 index 00000000..00faa899 --- /dev/null +++ b/docs/account_data/AccountBalance.md @@ -0,0 +1,25 @@ +# XeroRuby::AccountData::AccountBalance + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**account_id** | **String** | The account this balance is for. | +**date** | **Date** | The date this balance applies to (YYYY-MM-DD). | +**balance** | [**LedgerDecimal**](LedgerDecimal.md) | | +**signed_balance** | **Float** | Balance as a signed number (positive for debit, negative for credit). | +**account** | [**Account**](Account.md) | | + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::AccountBalance.new(account_id: null, + date: null, + balance: null, + signed_balance: null, + account: null) +``` + + diff --git a/docs/account_data/AccountBalancesResponse.md b/docs/account_data/AccountBalancesResponse.md new file mode 100644 index 00000000..06565987 --- /dev/null +++ b/docs/account_data/AccountBalancesResponse.md @@ -0,0 +1,17 @@ +# XeroRuby::AccountData::AccountBalancesResponse + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**account_balances** | [**Array<AccountBalance>**](AccountBalance.md) | | + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::AccountBalancesResponse.new(account_balances: null) +``` + + diff --git a/docs/account_data/AccountDataApi.md b/docs/account_data/AccountDataApi.md new file mode 100644 index 00000000..491bf1a7 --- /dev/null +++ b/docs/account_data/AccountDataApi.md @@ -0,0 +1,297 @@ +# XeroRuby::AccountData::AccountDataApi + +All URIs are relative to *https://api.xero.com/accountdata.xro/1.0* + +Method | HTTP request | Description +------------- | ------------- | ------------- +[**get_account_balances**](AccountDataApi.md#get_account_balances) | **GET** /account-balances | Get the balance of each general ledger account as at a given date +[**get_account_movements**](AccountDataApi.md#get_account_movements) | **GET** /account-movements | Get the net movement of each general ledger account over a date range +[**get_account_transactions**](AccountDataApi.md#get_account_transactions) | **GET** /account-transactions | Get general ledger account transactions between two dates, with pagination and filtering + + + +## get_account_balances + +> AccountBalancesResponse get_account_balances(accounting_basis, date, xero_tenant_id, opts) + +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/or `systemAccountCodes`. 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). - `type` values are matched case-sensitively, so use uppercase (for example `BANK`). Inventory asset accounts are reported as, and can only be filtered by, `INVENTORY`; filtering by their underlying account type does not match them. - `trackingItemIds` and `unassignedToTrackingCategoryIds` can be used independently of the filters above to further narrow which accounts are returned. ### Comparison periods - Supplying `comparisonPeriodCount` together with `comparisonPeriodSize` returns additional balances at prior points in time, in addition to the balance at `date`. - The n-th comparison date is `date` shifted back n times `comparisonPeriodSize`. For `MONTH`, `QUARTER`, and `YEAR` sizes, a `date` that falls on the last day of its month keeps landing on the last day of the shifted month (so comparisons across February behave correctly). - `comparisonPeriodCount` and `comparisonPeriodSize` must 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 five `class` values and nothing else, includes `BANK` in `type`, or lists a bank account in `accountIds`. - 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. + +### Example + +```ruby +# load the gem +require 'xero-ruby' + +creds = { + client_id: ENV['CLIENT_ID'], + client_secret: ENV['CLIENT_SECRET'], + redirect_uri: ENV['REDIRECT_URI'], + scopes: ENV['SCOPES'] +} +xero_client = XeroRuby::ApiClient.new(credentials: creds) + +token_set = fetch_valid_token_set(user) # example + +xero_client.refresh_token_set(token_set) + +# You need to namespace your api method call to one of the following api sets +# [:accounting_api, :assets_api, :projects_api, :files_api, :payroll_au_api, :payroll_nz_api, :payroll_uk_api, :app_store_api] + +api_instance = xero_client. + + + +accounting_basis = 'ACCRUAL' # String | Accounting basis for the balance calculation. +date = Date.parse('2024-12-31') # Date | The date to calculate account balances as at, in ISO 8601 format (YYYY-MM-DD). +xero_tenant_id = '2ae32d9e-4711-4201-9f2a-ac80e5318359' # String | The ID of the Xero organisation to query. +opts = { + comparison_period_count: 3, # Integer | Number of additional comparison balances to return, each one further back in time than the last. Must be supplied together with `comparisonPeriodSize`. - **Minimum**: 1 - **Maximum**: 100 + + comparison_period_size: 'MONTH', # String | The unit of time each comparison period steps back by. Must be supplied together with `comparisonPeriodCount`. + + account_ids: ['account_ids_example'], # Array | Filter to specific account IDs (GUIDs). Repeat the parameter for multiple accounts. - **Maximum**: 50 account IDs - **Validation**: Returns 404 if any ID does not exist for the organisation + + _class: ['_class_example'], # Array | Account classes to filter by. Can be combined with other filters. + + type: ['type_example'], # Array | 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. + + system_account_codes: ['system_account_codes_example'], # Array | System account codes to filter by (e.g. `RETAINEDEARNINGS`, `UNREALISEDGAINS`). Can be combined with other filters. + + tracking_item_ids: ['tracking_item_ids_example'], # Array | Filter to accounts assigned to any of the given tracking item IDs. + + unassigned_to_tracking_category_ids: ['unassigned_to_tracking_category_ids_example'] # Array | Filter to accounts that are not assigned to any tracking option within the given tracking category IDs. +} + +begin + #Get the balance of each general ledger account as at a given date + result = api_instance.get_account_balances(accounting_basis, date, xero_tenant_id, opts) + p result +rescue XeroRuby::AccountData::ApiError => e + puts "Exception when calling AccountDataApi->get_account_balances: #{e}" +end +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **accounting_basis** | **String**| Accounting basis for the balance calculation. | + **date** | **Date**| The date to calculate account balances as at, in ISO 8601 format (YYYY-MM-DD). | + **xero_tenant_id** | [**String**](.md)| The ID of the Xero organisation to query. | + **comparison_period_count** | **Integer**| Number of additional comparison balances to return, each one further back in time than the last. Must be supplied together with `comparisonPeriodSize`. - **Minimum**: 1 - **Maximum**: 100 | [optional] + **comparison_period_size** | **String**| The unit of time each comparison period steps back by. Must be supplied together with `comparisonPeriodCount`. | [optional] + **account_ids** | [**Array<String>**](String.md)| Filter to specific account IDs (GUIDs). Repeat the parameter for multiple accounts. - **Maximum**: 50 account IDs - **Validation**: Returns 404 if any ID does not exist for the organisation | [optional] + **_class** | [**Array<String>**](String.md)| Account classes to filter by. Can be combined with other filters. | [optional] + **type** | [**Array<String>**](String.md)| 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. | [optional] + **system_account_codes** | [**Array<String>**](String.md)| System account codes to filter by (e.g. `RETAINEDEARNINGS`, `UNREALISEDGAINS`). Can be combined with other filters. | [optional] + **tracking_item_ids** | [**Array<String>**](String.md)| Filter to accounts assigned to any of the given tracking item IDs. | [optional] + **unassigned_to_tracking_category_ids** | [**Array<String>**](String.md)| Filter to accounts that are not assigned to any tracking option within the given tracking category IDs. | [optional] + +### Return type + +[**AccountBalancesResponse**](AccountBalancesResponse.md) + +### Authorization + +[OAuth2](../README.md#OAuth2) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json, application/problem+json + + +## get_account_movements + +> AccountMovementsResponse get_account_movements(accounting_basis, start_date, end_date, xero_tenant_id, opts) + +Get the net movement of each general ledger account over a date range + +Retrieves account movements between `startDate` and `endDate`, optionally including movements for one or more prior comparison periods of the same length, and optionally filtered by account class, type, account IDs, system account code, or tracking item. ### Filtering - Filter by `class`, `type`, `accountIds`, and/or `systemAccountCodes`. 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). - `type` values are matched case-sensitively, so use uppercase (for example `BANK`). Inventory asset accounts are reported as, and can only be filtered by, `INVENTORY`; filtering by their underlying account type does not match them. - `trackingItemIds` and `unassignedToTrackingCategoryIds` can be used independently of the filters above to further narrow which accounts are returned. ### Comparison periods - Supplying `comparisonPeriodCount` together with `comparisonPeriodSize` returns additional movements for prior date ranges of the same length, in addition to the movement between `startDate` and `endDate`. - Each comparison range is calculated by moving the primary range back by `comparisonPeriodSize`, `comparisonPeriodCount` times. For `MONTH`, `QUARTER`, and `YEAR` sizes, range boundaries that fall on the last day of a month keep landing on the last day of the shifted month. - `comparisonPeriodCount` and `comparisonPeriodSize` must be supplied together. - The primary range and every comparison range must not overlap each other. A request whose periods would overlap is rejected with `400 Bad Request`. Ranges that share a single boundary day count as overlapping, which month-end adjustment can cause when shifting by `MONTH`, `QUARTER`, or `YEAR`. ### 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 five `class` values and nothing else, includes `BANK` in `type`, or lists a bank account in `accountIds`. - 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. ### Pagination This endpoint does not paginate — the full set of matching account movements is returned in a single response. ### Results Only combinations of account and date range with non-zero movement are returned; comparison ranges are not zero-filled. The response is a flat list with no guaranteed ordering. + +### Example + +```ruby +# load the gem +require 'xero-ruby' + +creds = { + client_id: ENV['CLIENT_ID'], + client_secret: ENV['CLIENT_SECRET'], + redirect_uri: ENV['REDIRECT_URI'], + scopes: ENV['SCOPES'] +} +xero_client = XeroRuby::ApiClient.new(credentials: creds) + +token_set = fetch_valid_token_set(user) # example + +xero_client.refresh_token_set(token_set) + +# You need to namespace your api method call to one of the following api sets +# [:accounting_api, :assets_api, :projects_api, :files_api, :payroll_au_api, :payroll_nz_api, :payroll_uk_api, :app_store_api] + +api_instance = xero_client. + + + +accounting_basis = 'ACCRUAL' # String | Accounting basis for the movement calculation. +start_date = Date.parse('2024-01-01') # Date | Start date of the movement range, in ISO 8601 format (YYYY-MM-DD). +end_date = Date.parse('2024-12-31') # Date | End date of the movement range, in ISO 8601 format (YYYY-MM-DD). +xero_tenant_id = '2ae32d9e-4711-4201-9f2a-ac80e5318359' # String | The ID of the Xero organisation to query. +opts = { + comparison_period_count: 3, # Integer | Number of additional comparison movements to return, each covering a range further back in time than the last. Must be supplied together with `comparisonPeriodSize`. - **Minimum**: 1 - **Maximum**: 100 + + comparison_period_size: 'MONTH', # String | The unit of time each comparison range steps back by. Must be supplied together with `comparisonPeriodCount`. + + account_ids: ['account_ids_example'], # Array | Filter to specific account IDs (GUIDs). Repeat the parameter for multiple accounts. - **Maximum**: 50 account IDs - **Validation**: Returns 404 if any ID does not exist for the organisation + + _class: ['_class_example'], # Array | Account classes to filter by. Can be combined with other filters. + + type: ['type_example'], # Array | 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. + + system_account_codes: ['system_account_codes_example'], # Array | System account codes to filter by (e.g. `RETAINEDEARNINGS`, `UNREALISEDGAINS`). Can be combined with other filters. + + tracking_item_ids: ['tracking_item_ids_example'], # Array | Filter to accounts assigned to any of the given tracking item IDs. + + unassigned_to_tracking_category_ids: ['unassigned_to_tracking_category_ids_example'] # Array | Filter to accounts that are not assigned to any tracking option within the given tracking category IDs. +} + +begin + #Get the net movement of each general ledger account over a date range + result = api_instance.get_account_movements(accounting_basis, start_date, end_date, xero_tenant_id, opts) + p result +rescue XeroRuby::AccountData::ApiError => e + puts "Exception when calling AccountDataApi->get_account_movements: #{e}" +end +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **accounting_basis** | **String**| Accounting basis for the movement calculation. | + **start_date** | **Date**| Start date of the movement range, in ISO 8601 format (YYYY-MM-DD). | + **end_date** | **Date**| End date of the movement range, in ISO 8601 format (YYYY-MM-DD). | + **xero_tenant_id** | [**String**](.md)| The ID of the Xero organisation to query. | + **comparison_period_count** | **Integer**| Number of additional comparison movements to return, each covering a range further back in time than the last. Must be supplied together with `comparisonPeriodSize`. - **Minimum**: 1 - **Maximum**: 100 | [optional] + **comparison_period_size** | **String**| The unit of time each comparison range steps back by. Must be supplied together with `comparisonPeriodCount`. | [optional] + **account_ids** | [**Array<String>**](String.md)| Filter to specific account IDs (GUIDs). Repeat the parameter for multiple accounts. - **Maximum**: 50 account IDs - **Validation**: Returns 404 if any ID does not exist for the organisation | [optional] + **_class** | [**Array<String>**](String.md)| Account classes to filter by. Can be combined with other filters. | [optional] + **type** | [**Array<String>**](String.md)| 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. | [optional] + **system_account_codes** | [**Array<String>**](String.md)| System account codes to filter by (e.g. `RETAINEDEARNINGS`, `UNREALISEDGAINS`). Can be combined with other filters. | [optional] + **tracking_item_ids** | [**Array<String>**](String.md)| Filter to accounts assigned to any of the given tracking item IDs. | [optional] + **unassigned_to_tracking_category_ids** | [**Array<String>**](String.md)| Filter to accounts that are not assigned to any tracking option within the given tracking category IDs. | [optional] + +### Return type + +[**AccountMovementsResponse**](AccountMovementsResponse.md) + +### Authorization + +[OAuth2](../README.md#OAuth2) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json, application/problem+json + + +## get_account_transactions + +> AccountTransactionsResponse get_account_transactions(xero_tenant_id, opts) + +Get general ledger account transactions between two dates, with pagination and filtering + +Retrieves transactions posted between `startDate` and `endDate` (inclusive), optionally filtered by account IDs, class, type, or system account code, with cursor-based pagination for large result sets. **First call:** omit `token`. Supply `accountingBasis`, `startDate`, and `endDate` (all required), plus any optional filters. **Continuation calls:** supply only `token`, taken from the previous response's `pagination.nextToken`. Do not send any other query parameters — they are ignored if present, since the original request is captured by the token. ### Pagination - Results are returned in pages of 200 lines. - Use `pagination.nextToken` from the response as the `token` query parameter to fetch the next page. Send only the `token` query parameter on continuation requests — all other query parameters are ignored on a continuation call, since the original request's parameters are already captured by the token. - The `token` value is an opaque string. Treat it as an opaque string only — do not parse, modify, or construct it yourself. Tokens may expire. - When `pagination` is `null`, you've reached the last page. - The API captures a consistent snapshot at the time of the first request (via `maxJournalNumber`), so transactions added while you are paginating through a result set won't appear partway through, and won't cause duplicates or gaps. ### Filtering - Filter by `accountIds`, `class`, `type`, and/or `systemAccountCodes`. These can be combined freely — when more than one is supplied, the server returns only transactions for accounts that match **all** of the supplied filters (an intersection, not a union). - `type` values are matched case-sensitively, so use uppercase (for example `BANK`). Inventory asset accounts are reported as, and can only be filtered by, `INVENTORY`; filtering by their underlying account type does not match them. - Use `systemAccountCodes=NONE` to match accounts that have no system account code. - Filters are only read from the first request in a pagination sequence — see Pagination above. ### Bank accounts Bank account transactions are only available to users with bank account view permission for the organisation. - If the user lacks this permission and the request includes `BANK` in `type`, or lists a bank account in `accountIds`, it is rejected with `403 Forbidden`. - For all other requests, including unfiltered requests, bank account transactions are silently excluded from the results for users without this permission. + +### Example + +```ruby +# load the gem +require 'xero-ruby' + +creds = { + client_id: ENV['CLIENT_ID'], + client_secret: ENV['CLIENT_SECRET'], + redirect_uri: ENV['REDIRECT_URI'], + scopes: ENV['SCOPES'] +} +xero_client = XeroRuby::ApiClient.new(credentials: creds) + +token_set = fetch_valid_token_set(user) # example + +xero_client.refresh_token_set(token_set) + +# You need to namespace your api method call to one of the following api sets +# [:accounting_api, :assets_api, :projects_api, :files_api, :payroll_au_api, :payroll_nz_api, :payroll_uk_api, :app_store_api] + +api_instance = xero_client. + + + +xero_tenant_id = '2ae32d9e-4711-4201-9f2a-ac80e5318359' # String | The ID of the Xero organisation to query. +opts = { + accounting_basis: 'ACCRUAL', # String | Accounting basis for the transaction query. Required on the first call; not used (and ignored) on continuation calls made with `token`. + + start_date: Date.parse('2024-01-01'), # Date | Start date in ISO 8601 format (YYYY-MM-DD). Required on the first call; not used (and ignored) on continuation calls made with `token`. + + end_date: Date.parse('2024-12-31'), # Date | End date in ISO 8601 format (YYYY-MM-DD). Required on the first call; not used (and ignored) on continuation calls made with `token`. + + account_ids: ['account_ids_example'], # Array | Filter to specific account IDs (GUIDs). Repeat the parameter for multiple accounts. Only used on the first call. - **Maximum**: 20 account IDs - **Validation**: Returns 404 if any ID does not exist for the organisation + + _class: ['_class_example'], # Array | Account classes to filter by. Can be combined with other filters. Only used on the first call. + + type: ['type_example'], # Array | 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. Only used on the first call. + + system_account_codes: ['system_account_codes_example'], # Array | System account codes to filter by (e.g. `RETAINEDEARNINGS`, `UNREALISEDGAINS`). Use `NONE` to match accounts with no system account code. Can be combined with other filters. Only used on the first call. + + include: ['[\"trackingCategories\"]'], # Array | Additional data to include in the response. Only used on the first call. + + max_journal_number: 999999, # Integer | Maximum journal number to include in results, for point-in-time queries. If omitted, the server captures the current maximum journal number at the time of the first request and reuses it for every subsequent page, so the whole paginated result set is consistent as at the moment you started. Only used on the first call. + + token: 'token_example' # String | Continuation token from a previous response's `pagination.nextToken`. When present, all other query parameters are ignored. Opaque — do not parse, modify, or construct it. +} + +begin + #Get general ledger account transactions between two dates, with pagination and filtering + result = api_instance.get_account_transactions(xero_tenant_id, opts) + p result +rescue XeroRuby::AccountData::ApiError => e + puts "Exception when calling AccountDataApi->get_account_transactions: #{e}" +end +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **xero_tenant_id** | [**String**](.md)| The ID of the Xero organisation to query. | + **accounting_basis** | **String**| Accounting basis for the transaction query. Required on the first call; not used (and ignored) on continuation calls made with `token`. | [optional] + **start_date** | **Date**| Start date in ISO 8601 format (YYYY-MM-DD). Required on the first call; not used (and ignored) on continuation calls made with `token`. | [optional] + **end_date** | **Date**| End date in ISO 8601 format (YYYY-MM-DD). Required on the first call; not used (and ignored) on continuation calls made with `token`. | [optional] + **account_ids** | [**Array<String>**](String.md)| Filter to specific account IDs (GUIDs). Repeat the parameter for multiple accounts. Only used on the first call. - **Maximum**: 20 account IDs - **Validation**: Returns 404 if any ID does not exist for the organisation | [optional] + **_class** | [**Array<String>**](String.md)| Account classes to filter by. Can be combined with other filters. Only used on the first call. | [optional] + **type** | [**Array<String>**](String.md)| 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. Only used on the first call. | [optional] + **system_account_codes** | [**Array<String>**](String.md)| System account codes to filter by (e.g. `RETAINEDEARNINGS`, `UNREALISEDGAINS`). Use `NONE` to match accounts with no system account code. Can be combined with other filters. Only used on the first call. | [optional] + **include** | [**Array<String>**](String.md)| Additional data to include in the response. Only used on the first call. | [optional] + **max_journal_number** | **Integer**| Maximum journal number to include in results, for point-in-time queries. If omitted, the server captures the current maximum journal number at the time of the first request and reuses it for every subsequent page, so the whole paginated result set is consistent as at the moment you started. Only used on the first call. | [optional] + **token** | **String**| Continuation token from a previous response's `pagination.nextToken`. When present, all other query parameters are ignored. Opaque — do not parse, modify, or construct it. | [optional] + +### Return type + +[**AccountTransactionsResponse**](AccountTransactionsResponse.md) + +### Authorization + +[OAuth2](../README.md#OAuth2) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json, application/problem+json + diff --git a/docs/account_data/AccountMovement.md b/docs/account_data/AccountMovement.md new file mode 100644 index 00000000..7bfba6d4 --- /dev/null +++ b/docs/account_data/AccountMovement.md @@ -0,0 +1,35 @@ +# XeroRuby::AccountData::AccountMovement + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**account_id** | **String** | The account this movement is for. | +**date_range** | [**AccountingDateRange**](AccountingDateRange.md) | | +**debits** | **Float** | Total debits posted to this account within the date range. | +**credits** | **Float** | Total credits posted to this account within the date range. | +**movement** | [**LedgerDecimal**](LedgerDecimal.md) | | +**signed_movement** | **Float** | Movement as a signed number (positive for debit, negative for credit). | +**tax_debits** | **Float** | Total tax debits within the date range. Omitted from the response when tax values are not available. | [optional] +**tax_credits** | **Float** | Total tax credits within the date range. Omitted from the response when tax values are not available. | [optional] +**signed_tax_movement** | **Float** | Tax movement as a signed number (positive for debit, negative for credit). Omitted from the response when tax values are not available. | [optional] +**account** | [**Account**](Account.md) | | + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::AccountMovement.new(account_id: null, + date_range: null, + debits: null, + credits: null, + movement: null, + signed_movement: null, + tax_debits: null, + tax_credits: null, + signed_tax_movement: null, + account: null) +``` + + diff --git a/docs/account_data/AccountMovementsResponse.md b/docs/account_data/AccountMovementsResponse.md new file mode 100644 index 00000000..748191a8 --- /dev/null +++ b/docs/account_data/AccountMovementsResponse.md @@ -0,0 +1,17 @@ +# XeroRuby::AccountData::AccountMovementsResponse + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**account_movements** | [**Array<AccountMovement>**](AccountMovement.md) | | + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::AccountMovementsResponse.new(account_movements: null) +``` + + diff --git a/docs/account_data/AccountTransactionLine.md b/docs/account_data/AccountTransactionLine.md new file mode 100644 index 00000000..f7b2a1c2 --- /dev/null +++ b/docs/account_data/AccountTransactionLine.md @@ -0,0 +1,37 @@ +# XeroRuby::AccountData::AccountTransactionLine + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**journal_number** | **Integer** | Unique journal number for this transaction. | +**journal_date** | **Date** | Accounting date of the transaction (YYYY-MM-DD). | +**description** | **String** | Line description, falling back to the journal narration. Empty if neither is set. | +**account** | [**TransactionAccount**](TransactionAccount.md) | | +**net_amount** | [**LedgerDecimal**](LedgerDecimal.md) | | +**signed_net_amount** | **Float** | Net amount as a signed number (positive for debit, negative for credit). | [optional] +**tax_amount** | [**LedgerDecimal**](LedgerDecimal.md) | | [optional] +**signed_tax_amount** | **Float** | Tax amount as a signed number (positive for debit, negative for credit). | [optional] +**source** | [**LineSource**](LineSource.md) | | +**tax_rate** | [**LineTaxRate**](LineTaxRate.md) | | +**tracking_categories** | [**Hash<String, TrackingItemDetails>**](TrackingItemDetails.md) | Present only when `include=trackingCategories` was requested, and omitted otherwise. Keys are tracking category IDs (UUIDs); values describe the selected tracking option. The object is empty when the line has no tracking. | [optional] + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::AccountTransactionLine.new(journal_number: null, + journal_date: null, + description: null, + account: null, + net_amount: null, + signed_net_amount: null, + tax_amount: null, + signed_tax_amount: null, + source: null, + tax_rate: null, + tracking_categories: null) +``` + + diff --git a/docs/account_data/AccountTransactionsResponse.md b/docs/account_data/AccountTransactionsResponse.md new file mode 100644 index 00000000..b0feb1a0 --- /dev/null +++ b/docs/account_data/AccountTransactionsResponse.md @@ -0,0 +1,23 @@ +# XeroRuby::AccountData::AccountTransactionsResponse + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**currency_code** | **String** | Organisation's base currency code (ISO 4217). | +**max_journal_number** | **Integer** | Maximum journal number included in this result set. Captured at the first request and held constant across all pages for consistency. | +**lines** | [**Array<AccountTransactionLine>**](AccountTransactionLine.md) | Transaction lines for this page (max 200). | +**pagination** | [**AccountTransactionsResponsePagination**](AccountTransactionsResponsePagination.md) | | [optional] + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::AccountTransactionsResponse.new(currency_code: USD, + max_journal_number: 546, + lines: null, + pagination: null) +``` + + diff --git a/docs/account_data/AccountTransactionsResponsePagination.md b/docs/account_data/AccountTransactionsResponsePagination.md new file mode 100644 index 00000000..6baa1ffb --- /dev/null +++ b/docs/account_data/AccountTransactionsResponsePagination.md @@ -0,0 +1,19 @@ +# XeroRuby::AccountData::AccountTransactionsResponsePagination + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**page_size** | **Integer** | | +**next_token** | **String** | Opaque continuation token for the next page. Send it as the `token` query parameter to retrieve the next page. | + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::AccountTransactionsResponsePagination.new(page_size: 200, + next_token: ZXhhbXBsZS1jb250aW51YXRpb24tdG9rZW4) +``` + + diff --git a/docs/account_data/AccountingDateRange.md b/docs/account_data/AccountingDateRange.md new file mode 100644 index 00000000..e8ef8f27 --- /dev/null +++ b/docs/account_data/AccountingDateRange.md @@ -0,0 +1,19 @@ +# XeroRuby::AccountData::AccountingDateRange + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**start_date** | **Date** | | +**end_date** | **Date** | | + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::AccountingDateRange.new(start_date: null, + end_date: null) +``` + + diff --git a/docs/account_data/FieldProblem.md b/docs/account_data/FieldProblem.md new file mode 100644 index 00000000..e652492d --- /dev/null +++ b/docs/account_data/FieldProblem.md @@ -0,0 +1,27 @@ +# XeroRuby::AccountData::FieldProblem + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**field_name** | **String** | The name of the offending parameter, or an empty string when the failure is not tied to one parameter. | [optional] +**type** | **String** | | [optional] +**title** | **String** | | [optional] +**status** | **Integer** | | [optional] +**detail** | **String** | | [optional] +**instance** | **String** | | [optional] + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::FieldProblem.new(field_name: null, + type: null, + title: null, + status: null, + detail: null, + instance: null) +``` + + diff --git a/docs/account_data/GatewayProblem.md b/docs/account_data/GatewayProblem.md new file mode 100644 index 00000000..c28f0a04 --- /dev/null +++ b/docs/account_data/GatewayProblem.md @@ -0,0 +1,27 @@ +# XeroRuby::AccountData::GatewayProblem + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**type** | **String** | | [optional] +**title** | **String** | | +**status** | **Integer** | | +**detail** | **String** | | [optional] +**instance** | **String** | The correlation ID of the request, also returned in the `Xero-Correlation-Id` header. | [optional] +**extensions** | **Hash<String, Object>** | | [optional] + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::GatewayProblem.new(type: null, + title: Unauthorized, + status: null, + detail: null, + instance: null, + extensions: null) +``` + + diff --git a/docs/account_data/LedgerDecimal.md b/docs/account_data/LedgerDecimal.md new file mode 100644 index 00000000..7636f41e --- /dev/null +++ b/docs/account_data/LedgerDecimal.md @@ -0,0 +1,19 @@ +# XeroRuby::AccountData::LedgerDecimal + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**value** | **Float** | Amount value (always positive). | +**type** | **String** | | + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::LedgerDecimal.new(value: null, + type: null) +``` + + diff --git a/docs/account_data/LineSource.md b/docs/account_data/LineSource.md new file mode 100644 index 00000000..6e747d3b --- /dev/null +++ b/docs/account_data/LineSource.md @@ -0,0 +1,27 @@ +# XeroRuby::AccountData::LineSource + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**document_id** | **String** | | [optional] +**document_type** | **String** | | [optional] +**event_type** | **String** | | [optional] +**contact_id** | **String** | | [optional] +**contact_name** | **String** | | [optional] +**reference** | **String** | | [optional] + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::LineSource.new(document_id: null, + document_type: null, + event_type: null, + contact_id: null, + contact_name: null, + reference: null) +``` + + diff --git a/docs/account_data/LineTaxRate.md b/docs/account_data/LineTaxRate.md new file mode 100644 index 00000000..ec4cada9 --- /dev/null +++ b/docs/account_data/LineTaxRate.md @@ -0,0 +1,21 @@ +# XeroRuby::AccountData::LineTaxRate + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**code** | **String** | | [optional] +**name** | **String** | | [optional] +**percentage** | **Float** | | [optional] + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::LineTaxRate.new(code: null, + name: null, + percentage: null) +``` + + diff --git a/docs/account_data/ProblemDetails.md b/docs/account_data/ProblemDetails.md new file mode 100644 index 00000000..1df89b8f --- /dev/null +++ b/docs/account_data/ProblemDetails.md @@ -0,0 +1,25 @@ +# XeroRuby::AccountData::ProblemDetails + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**type** | **String** | URI reference identifying the problem type. | [optional] +**title** | **String** | Short, human-readable summary. | +**status** | **Integer** | HTTP status code. | +**detail** | **String** | Detailed explanation of the problem. | [optional] +**instance** | **String** | URI reference identifying the specific occurrence. | [optional] + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::ProblemDetails.new(type: null, + title: null, + status: null, + detail: null, + instance: null) +``` + + diff --git a/docs/account_data/TrackingItemDetails.md b/docs/account_data/TrackingItemDetails.md new file mode 100644 index 00000000..fc27e6db --- /dev/null +++ b/docs/account_data/TrackingItemDetails.md @@ -0,0 +1,21 @@ +# XeroRuby::AccountData::TrackingItemDetails + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**category_name** | **String** | | +**option_id** | **String** | | +**option_name** | **String** | | + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::TrackingItemDetails.new(category_name: null, + option_id: null, + option_name: null) +``` + + diff --git a/docs/account_data/TransactionAccount.md b/docs/account_data/TransactionAccount.md new file mode 100644 index 00000000..48f9fa31 --- /dev/null +++ b/docs/account_data/TransactionAccount.md @@ -0,0 +1,29 @@ +# XeroRuby::AccountData::TransactionAccount + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**id** | **String** | | +**code** | **String** | | [optional] +**name** | **String** | | +**_class** | **String** | | +**type** | **String** | Account type (e.g. `BANK`, `CURRENT`). Reported as `INVENTORY` for inventory asset accounts, regardless of the account's underlying type. | +**status** | **String** | | +**system_account_code** | **String** | System account code, or `NONE` if the account has no system account code. | + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::TransactionAccount.new(id: null, + code: null, + name: null, + _class: null, + type: null, + status: null, + system_account_code: null) +``` + + diff --git a/docs/account_data/ValidationProblem.md b/docs/account_data/ValidationProblem.md new file mode 100644 index 00000000..1a5ac2c6 --- /dev/null +++ b/docs/account_data/ValidationProblem.md @@ -0,0 +1,27 @@ +# XeroRuby::AccountData::ValidationProblem + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**type** | **String** | URI reference identifying the problem type. | [optional] +**title** | **String** | Short, human-readable summary. | [optional] +**status** | **Integer** | HTTP status code. | [optional] +**detail** | **String** | Detailed explanation of the problem. | [optional] +**instance** | **String** | URI reference identifying the specific occurrence. | [optional] +**field_validation_errors** | [**Array<FieldProblem>**](FieldProblem.md) | | [optional] + +## Code Sample + +```ruby +require 'XeroRuby::AccountData' + +instance = XeroRuby::AccountData::ValidationProblem.new(type: null, + title: null, + status: null, + detail: null, + instance: null, + field_validation_errors: null) +``` + + diff --git a/docs/account_data/index.html b/docs/account_data/index.html new file mode 100644 index 00000000..fb92072a --- /dev/null +++ b/docs/account_data/index.html @@ -0,0 +1,4404 @@ + + + + + Xero Account Data API (Beta) + + + + + + xero-ruby AccountData SDK Docs + + + + + + + + + + + + + + + + + + +
+ +
+ +
+
+ + +
+
+ +
+
+ +
+
+
+
+
+ +
+
+
+
+

Xero Account Data API (Beta)

+
+
+
+ +
+
+

AccountData

+
+
+
+

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/or systemAccountCodes. 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).
    • +
  • type values are matched case-sensitively, so use uppercase (for example BANK). Inventory +asset accounts are reported as, and can only be filtered by, INVENTORY; filtering by +their underlying account type does not match them.
    • +
  • trackingItemIds and unassignedToTrackingCategoryIds can be used independently of +the filters above to further narrow which accounts are returned.
    • +
+

Comparison periods

+
    +
  • Supplying comparisonPeriodCount together with comparisonPeriodSize returns +additional balances at prior points in time, in addition to the balance at date.
    • +
  • The n-th comparison date is date shifted back n times comparisonPeriodSize. For MONTH, +QUARTER, and YEAR sizes, a date that falls on the last day of its month keeps landing +on the last day of the shifted month (so comparisons across February behave correctly).
    • +
  • comparisonPeriodCount and comparisonPeriodSize must 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 five class values and nothing else, includes +BANK in type, or lists a bank account in accountIds.
    • +
  • 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

+

+ +
+ +
+ 
xero_client.set_token_set(user.token_set)
+
+accountingBasis = 'ACCRUAL'
+date = "2024-12-31"
+xeroTenantId = '2ae32d9e-4711-4201-9f2a-ac80e5318359'
+comparisonPeriodCount = 3
+comparisonPeriodSize = 'MONTH'
+accountIds = []
+class = []
+type = []
+systemAccountCodes = []
+trackingItemIds = []
+unassignedToTrackingCategoryIds = []
+
+begin
+  response = xero_client.accounting_api.get_account_balances(accountingBasis, date, xeroTenantId, comparisonPeriodCount, comparisonPeriodSize, accountIds, class, type, systemAccountCodes, trackingItemIds, unassignedToTrackingCategoryIds)
+  return response
+rescue XeroRuby::ApiError => e
+  puts "Exception when calling get_account_balances: #{e}"
+end
+
+
+
+

Scopes

+ + + + + + + +
accountdata.balances.readRead general ledger account balances
+

Parameters

+
Header parameters
+ + + + + + + + + +
NameDescription
Xero-Tenant-Id* + + +
+
+
+ + UUID + + + (uuid) + + +
+The ID of the Xero organisation to query. +
+
+
+ Required +
+
+
+
+
Query parameters
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription
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.

+
    +
  • Minimum: 1
    • +
  • Maximum: 100
    • +
+ +
+
+
+
+
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.

+
    +
  • Maximum: 50 account IDs
    • +
  • Validation: Returns 404 if any ID does not exist for the organisation
    • +
+ +
+
+
+
+
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. +
+
+
+
+
+
+
+
+
+
+
+

getAccountMovements

+

Get the net movement of each general ledger account over a date range

+
+
+
+

+

Retrieves account movements between startDate and endDate, optionally +including movements for one or more prior comparison periods of the same length, +and optionally filtered by account class, type, account IDs, system account code, +or tracking item.

+

Filtering

+
    +
  • Filter by class, type, accountIds, and/or systemAccountCodes. 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).
    • +
  • type values are matched case-sensitively, so use uppercase (for example BANK). Inventory +asset accounts are reported as, and can only be filtered by, INVENTORY; filtering by +their underlying account type does not match them.
    • +
  • trackingItemIds and unassignedToTrackingCategoryIds can be used independently of +the filters above to further narrow which accounts are returned.
    • +
+

Comparison periods

+
    +
  • Supplying comparisonPeriodCount together with comparisonPeriodSize returns +additional movements for prior date ranges of the same length, in addition to the +movement between startDate and endDate.
    • +
  • Each comparison range is calculated by moving the primary range back by +comparisonPeriodSize, comparisonPeriodCount times. For MONTH, QUARTER, and +YEAR sizes, range boundaries that fall on the last day of a month keep landing on +the last day of the shifted month.
    • +
  • comparisonPeriodCount and comparisonPeriodSize must be supplied together.
    • +
  • The primary range and every comparison range must not overlap each other. A request +whose periods would overlap is rejected with 400 Bad Request. Ranges that share a single boundary day count as +overlapping, which month-end adjustment can cause when shifting by MONTH, QUARTER, or +YEAR.
    • +
+

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 five class values and nothing else, includes +BANK in type, or lists a bank account in accountIds.
    • +
  • 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.
    • +
+

Pagination

+

This endpoint does not paginate — the full set of matching account movements is +returned in a single response.

+

Results

+

Only combinations of account and date range with non-zero movement are returned; comparison +ranges are not zero-filled. The response is a flat list with no guaranteed ordering.

+

+

+
+ 
/account-movements
+

+

Usage and SDK Samples

+

+ +
+ +
+ 
xero_client.set_token_set(user.token_set)
+
+accountingBasis = 'ACCRUAL'
+startDate = "2024-01-01"
+endDate = "2024-12-31"
+xeroTenantId = '2ae32d9e-4711-4201-9f2a-ac80e5318359'
+comparisonPeriodCount = 3
+comparisonPeriodSize = 'MONTH'
+accountIds = []
+class = []
+type = []
+systemAccountCodes = []
+trackingItemIds = []
+unassignedToTrackingCategoryIds = []
+
+begin
+  response = xero_client.accounting_api.get_account_movements(accountingBasis, startDate, endDate, xeroTenantId, comparisonPeriodCount, comparisonPeriodSize, accountIds, class, type, systemAccountCodes, trackingItemIds, unassignedToTrackingCategoryIds)
+  return response
+rescue XeroRuby::ApiError => e
+  puts "Exception when calling get_account_movements: #{e}"
+end
+
+
+
+

Scopes

+ + + + + + + +
accountdata.movements.readRead general ledger account movements
+

Parameters

+
Header parameters
+ + + + + + + + + +
NameDescription
Xero-Tenant-Id* + + +
+
+
+ + UUID + + + (uuid) + + +
+The ID of the Xero organisation to query. +
+
+
+ Required +
+
+
+
+
Query parameters
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription
accountingBasis* + + +
+
+
+ + String + + +
+Accounting basis for the movement calculation. +
+
+
+ Required +
+
+
+
startDate* + + +
+
+
+ + date + + + (date) + + +
+Start date of the movement range, in ISO 8601 format (YYYY-MM-DD). +
+
+
+ Required +
+
+
+
endDate* + + +
+
+
+ + date + + + (date) + + +
+End date of the movement range, in ISO 8601 format (YYYY-MM-DD). +
+
+
+ Required +
+
+
+
comparisonPeriodCount + + +
+
+
+ + Integer + + + (int32) + + +
+

Number of additional comparison movements to return, each covering a range +further back in time than the last. Must be supplied together with +comparisonPeriodSize.

+
    +
  • Minimum: 1
    • +
  • Maximum: 100
    • +
+ +
+
+
+
+
comparisonPeriodSize + + +
+
+
+ + String + + +
+The unit of time each comparison range 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.

+
    +
  • Maximum: 50 account IDs
    • +
  • Validation: Returns 404 if any ID does not exist for the organisation
    • +
+ +
+
+
+
+
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. +
+
+
+
+
+
+
+
+
+
+
+

getAccountTransactions

+

Get general ledger account transactions between two dates, with pagination and filtering

+
+
+
+

+

Retrieves transactions posted between startDate and endDate (inclusive), +optionally filtered by account IDs, class, type, or system account code, with +cursor-based pagination for large result sets.

+

First call: omit token. Supply accountingBasis, startDate, and +endDate (all required), plus any optional filters.

+

Continuation calls: supply only token, taken from the previous response's +pagination.nextToken. Do not send any other query parameters — they are +ignored if present, since the original request is captured by the token.

+

Pagination

+
    +
  • Results are returned in pages of 200 lines.
    • +
  • Use pagination.nextToken from the response as the token query parameter to fetch +the next page. Send only the token query parameter on continuation requests — all +other query parameters are +ignored on a continuation call, since the original request's parameters are already +captured by the token.
    • +
  • The token value is an opaque string. Treat it as an opaque string only — do not +parse, modify, or construct it yourself. Tokens may expire.
    • +
  • When pagination is null, you've reached the last page.
    • +
  • The API captures a consistent snapshot at the time of the first request (via +maxJournalNumber), so transactions added while you are paginating through a +result set won't appear partway through, and won't cause duplicates or gaps.
    • +
+

Filtering

+
    +
  • Filter by accountIds, class, type, and/or systemAccountCodes. These can be +combined freely — when more than one is supplied, the server returns only +transactions for accounts that match all of the supplied filters (an +intersection, not a union).
    • +
  • type values are matched case-sensitively, so use uppercase (for example BANK). Inventory +asset accounts are reported as, and can only be filtered by, INVENTORY; filtering by +their underlying account type does not match them.
    • +
  • Use systemAccountCodes=NONE to match accounts that have no system account code.
    • +
  • Filters are only read from the first request in a pagination sequence — see +Pagination above.
    • +
+

Bank accounts

+

Bank account transactions are only available to users with bank account view permission for +the organisation.

+
    +
  • If the user lacks this permission and the request includes BANK in type, or lists a +bank account in accountIds, it is rejected with 403 Forbidden.
    • +
  • For all other requests, including unfiltered requests, bank account transactions are +silently excluded from the results for users without this permission.
    • +
+

+

+
+ 
/account-transactions
+

+

Usage and SDK Samples

+

+ +
+ +
+ 
xero_client.set_token_set(user.token_set)
+
+xeroTenantId = '2ae32d9e-4711-4201-9f2a-ac80e5318359'
+accountingBasis = 'ACCRUAL'
+startDate = "2024-01-01"
+endDate = "2024-12-31"
+accountIds = []
+class = []
+type = []
+systemAccountCodes = []
+include = [["trackingCategories"]]
+maxJournalNumber = 999999
+token = 'token_example'
+
+begin
+  response = xero_client.accounting_api.get_account_transactions(xeroTenantId, accountingBasis, startDate, endDate, accountIds, class, type, systemAccountCodes, include, maxJournalNumber, token)
+  return response
+rescue XeroRuby::ApiError => e
+  puts "Exception when calling get_account_transactions: #{e}"
+end
+
+
+
+

Scopes

+ + + + + + + +
accountdata.transactions.readRead general ledger account transactions
+

Parameters

+
Header parameters
+ + + + + + + + + +
NameDescription
Xero-Tenant-Id* + + +
+
+
+ + UUID + + + (uuid) + + +
+The ID of the Xero organisation to query. +
+
+
+ Required +
+
+
+
+
Query parameters
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription
accountingBasis + + +
+
+
+ + String + + +
+Accounting basis for the transaction query. Required on the first call; +not used (and ignored) on continuation calls made with token. +
+
+
+
+
startDate + + +
+
+
+ + date + + + (date) + + +
+Start date in ISO 8601 format (YYYY-MM-DD). Required on the first call; not +used (and ignored) on continuation calls made with token. +
+
+
+
+
endDate + + +
+
+
+ + date + + + (date) + + +
+End date in ISO 8601 format (YYYY-MM-DD). Required on the first call; not +used (and ignored) on continuation calls made with token. +
+
+
+
+
accountIds + + +
+
+
+ + array[UUID] + + + (uuid) + + +
+

Filter to specific account IDs (GUIDs). Repeat the parameter for multiple +accounts. Only used on the first call.

+
    +
  • Maximum: 20 account IDs
    • +
  • Validation: Returns 404 if any ID does not exist for the organisation
    • +
+ +
+
+
+
+
class + + +
+
+
+ + array[String] + + +
+Account classes to filter by. Can be combined with other filters. Only used +on the first call. +
+
+
+
+
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. Only used on the first call. +
+
+
+
+
systemAccountCodes + + +
+
+
+ + array[String] + + +
+System account codes to filter by (e.g. RETAINEDEARNINGS, +UNREALISEDGAINS). Use NONE to match accounts with no system account code. +Can be combined with other filters. Only used on the first call. +
+
+
+
+
include + + +
+
+
+ + array[String] + + +
+Additional data to include in the response. Only used on the first call. +
+
+
+
+
maxJournalNumber + + +
+
+
+ + Long + + + (int64) + + +
+Maximum journal number to include in results, for point-in-time queries. If +omitted, the server captures the current maximum journal number at the time +of the first request and reuses it for every subsequent page, so the whole +paginated result set is consistent as at the moment you started. Only used on +the first call. +
+
+
+
+
token + + +
+
+
+ + String + + +
+Continuation token from a previous response's pagination.nextToken. When +present, all other query parameters are ignored. Opaque — do not parse, +modify, or construct it. +
+
+
+
+
+
+
+
+
+
+ +
+
+
+ + + + + + + + + + + + + + diff --git a/docs/accounting/index.html b/docs/accounting/index.html index e6249223..59cb3a93 100644 --- a/docs/accounting/index.html +++ b/docs/accounting/index.html @@ -6480,6 +6480,7 @@ +
@@ -6521,7 +6522,7 @@