API providing access to financial statements, balance sheets, profit and loss reports, and cash flow summaries for Xero organizations. Supports bank statement accounting, account usage, and lock history for financial analysis and reporting applications.
openapi: 3.0.0
info:
version: 11.1.0
title: Xero Finance API
description: The Finance API is a collection of endpoints which customers can use in the course of a loan application, which may assist lenders to gain the confidence they need to provide capital.
termsOfService: https://developer.xero.com/xero-developer-platform-terms-conditions/
contact:
name: Xero Platform Team
email: [email protected]
url: https://developer.xero.com
license:
name: MIT
url: https://github.com/XeroAPI/Xero-OpenAPI/blob/master/LICENSE
servers:
- description: Xero API servers
url: https://api.xero.com/finance.xro/1.0
paths:
/CashValidation:
parameters:
- $ref: "#/components/parameters/requiredHeader"
get:
security:
- OAuth2:
- finance.cashvalidation.read
tags:
- Finance
summary: Xero Get cash validation
operationId: getCashValidation
description: Summarizes the total cash position for each account for an org
parameters:
- name: balanceDate
x-snake: balance_date
in: query
description: "date, yyyy-MM-dd \r\n\r\nIf no parameter is provided, the current date will be used.\r\n\r\nThe ‘balance date’ will return transactions based on the accounting date entered by the user. Transactions before the balanceDate will be included.\r\nThe user has discretion as to which accounting period the transaction relates to.\r\n\r\nThe ‘balance date’ will control the latest maximum date of transactions included in the aggregate numbers. Balance date does not affect the CurrentStatement object, as this will always return the most recent statement before asAtSystemDate (if specified)"
schema:
type: string
example: "2021-09-15"
- name: asAtSystemDate
x-snake: as_at_system_date
in: query
description: "date, yyyy-MM-dd \r\n\r\nIf no parameter is provided, the current date will be used.\r\n\r\nThe ‘as at’ date will return transactions based on the creation date. It reflects the date the transactions were entered into Xero, not the accounting date.\r\nThe ‘as at’ date can not be overridden by the user. This can be used to estimate a ‘historical frequency of reconciliation’.\r\n\r\nThe ‘as at’ date will affect the current statement in the response, as any candidate statements created after this date will be filtered out. Thus the current statement returned will be the most recent statement prior to the specified ‘as at’ date. Be aware that neither the begin date, nor the balance date, will affect the current statement.\r\n\r\nNote; information is only presented when system architecture allows, meaning historical cash validation information will be an estimate. In addition, delete events are not aware of the ‘as at’ functionality in this endpoint, meaning that transactions deleted at the time the API is accessed will be considered to always have been deleted."
schema:
type: string
example: "2021-09-15"
- name: beginDate
x-snake: begin_date
in: query
description: "date, yyyy-MM-dd \r\n\r\nIf no parameter is provided, the aggregate results will be drawn from the user’s total history.\r\n\r\nThe ‘begin date’ will return transactions based on the accounting date entered by the user. Transactions after the beginDate will be included.\r\nThe user has discretion as to which accounting period the transaction relates to."
schema:
type: string
example: "2021-09-15"
responses:
"200":
description: Success
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/CashValidationResponse"
example:
- accountId: 73151de8-3676-4887-a021-edec960dd537
statementBalance:
value: 100
type: DEBIT
statementBalanceDate: "2021-03-01"
bankStatement:
statementLines:
unreconciledAmountPos: 4577
unreconciledAmountNeg: -2367
unreconciledLines: 8
avgDaysUnreconciledPos: 112.265531
avgDaysUnreconciledNeg: 149.298992
earliestUnreconciledTransaction: "2019-03-01"
latestUnreconciledTransaction: "2021-03-01"
deletedAmount: 50
totalAmount: 189
dataSource:
directBankFeed: 0
fileUpload: 300
manual: -188
directBankFeedPos: 0
fileUploadPos: 2223
manualPos: 0
directBankFeedNeg: 0
fileUploadNeg: -1890
manualNeg: -500
otherPos: 0
otherNeg: 0
other: 100
earliestReconciledTransaction: "2019-03-01"
latestReconciledTransaction: "2020-03-01"
reconciledAmountPos: 0
reconciledAmountNeg: -288
reconciledLines: 3
totalAmountPos: 2245
totalAmountNeg: -1995
currentStatement:
startDate: "2021-03-01"
endDate: "2021-03-01"
startBalance: 0
endBalance: 0
importedDateTimeUtc: "2021-03-09T05:22:14.3Z"
importSourceType: Manual
cashAccount:
unreconciledAmountPos: 1440
unreconciledAmountNeg: -1000
startingBalance: 0
accountBalance: 0
balanceCurrency: NZD
"400":
description: BadRequest
content:
application/json:
schema:
$ref: "#/components/schemas/Problem"
example:
type: invalid-request
title: InvalidRequest
status: 400
detail: "Invalid BalanceDate: '2020-01'"
/FinancialStatements/BalanceSheet:
parameters:
- $ref: "#/components/parameters/requiredHeader"
get:
security:
- OAuth2:
- finance.statements.read
tags:
- Finance
operationId: getFinancialStatementBalanceSheet
summary: Xero Get Balance Sheet report
description: The balance sheet report is a standard financial report which describes the financial position of an organisation at a point in time.
parameters:
- name: balanceDate
x-snake: balance_date
in: query
description: "Specifies the date for balance sheet report.\r\n\r\nFormat yyyy-MM-dd. If no parameter is provided, the current date will be used."
schema:
type: string
example: "2020-06-30"
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/BalanceSheetResponse"
example:
balanceDate: "2021-05-12"
asset:
accountTypes:
- accountType: INVENTORY
accounts:
- code: "630"
accountID: abcdeabc-80bb-47f5-9418-d1fc2241b838
name: Inventory
reportingCode: ASS.CUR.INY
total: 3
total: 3
- accountType: CURRENT
accounts:
- code: "610"
accountID: abcdeabc-b4d1-45a5-82f7-19deda692a31
name: Accounts Receivable
reportingCode: ASS.CUR.REC.TRA
total: 100
total: 100
- accountType: BANK
accounts:
- accountID: abcdeabc-3a6d-4c53-ba82-ea1c92d02ef4
name: Buz Acc
reportingCode: ASS
total: -42.3
total: -42.3
total: 60.7
liability:
accountTypes:
- accountType: CURRLIAB
accounts:
- code: "820"
accountID: abcdeabc-40f7-49f1-ad89-1930c1366e5b
name: GST
reportingCode: LIA.CUR.TAX.GST
total: 1.59
- code: "860"
accountID: abcdeabc-2877-4c00-be7d-475b1ded30d7
name: Rounding
reportingCode: LIA.CUR
total: -0.1
- code: "800"
accountID: abcdeabc-80ba-4b58-8d72-f8e9ca0f2f00
name: Accounts Payable
reportingCode: LIA.CUR.PAY.TRA
total: 44.4
total: 45.89
total: 45.89
equity:
accountTypes:
- accountType: EQUITY
accounts:
- accountID: 00000000-0000-0000-0000-000000000000
name: Current Year Earnings
total: 14.81
total: 14.81
total: 14.81
"400":
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/Problem"
example:
type: invalid-request
title: InvalidRequest
status: 400
detail: Organisation xxx does not exist
"503":
description: Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/Problem"
example:
type: service-unavailable
title: ServiceUnavailable
status: 503
detail: Cannot process org xxx at this time. Apologies for inconvenience.
/FinancialStatements/Cashflow:
parameters:
- $ref: "#/components/parameters/requiredHeader"
get:
security:
- OAuth2:
- finance.statements.read
tags:
- Finance
operationId: getFinancialStatementCashflow
summary: Xero Get Cash flow report
description: The statement of cash flows - direct method, provides the year to date changes in operating, financing and investing cash flow activities for an organisation. Cashflow statement is not available in US region at this stage.
parameters:
- name: startDate
x-snake: start_date
in: query
description: "Date e.g. yyyy-MM-dd\r\n\r\nSpecifies the start date for cash flow report.\r\n\r\nIf no parameter is provided, the date of 12 months before the end date will be used."
schema:
type: string
example: "2020-09-15"
- name: endDate
x-snake: end_date
in: query
description: "Date e.g. yyyy-MM-dd\r\n\r\nSpecifies the end date for cash flow report.\r\n\r\nIf no parameter is provided, the current date will be used."
schema:
type: string
example: "2021-09-15"
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/CashflowResponse"
example:
startDate: "2018-07-01"
endDate: "2019-06-30"
cashBalance:
openingCashBalance: 5000
closingCashBalance: -50000
netCashMovement: -55000
cashflowActivities:
- name: Operating Activities
total: -41000
cashflowTypes:
- name: Receipts from customers
total: 34000
accounts:
- accountId: abcdefab-4d1e-4d1a-9e4c-68b2c2a278e2
accountType: REVENUE
accountClass: REVENUE
code: "455"
name: Cellar Door - Till Variance
reportingCode: EXP
total: -1000
- accountId: abcdefab-4d1e-4d1a-9e4c-68b2c2a278e2
accountType: CURRENT
accountClass: ASSET
code: "123"
name: Loan - Darleen's
reportingCode: ASS
total: 35000
- name: Payments to suppliers and employees
total: -75000
accounts:
- accountId: abcdefab-4d1e-4d1a-9e4c-68b2c2a278e2
accountType: CURRENT
accountClass: ASSET
code: "123"
name: Loan - Darleen's
reportingCode: ASS
total: -75000
- name: Investing Activities
total: -35000
cashflowTypes:
- name: Payment for property, plant and equipment
total: -36000
accounts:
- accountId: abcdefab-4d1e-4d1a-9e4c-68b2c2a278e2
accountType: FIXED
accountClass: ASSET
code: "138"
name: Motor Vehicles at Cost
reportingCode: ASS
total: -1000
- accountId: abcdefab-5353-9d4b-7cad-51b2c2a2754a
accountType: FIXED
accountClass: ASSET
code: "140"
name: Equipment at cost
reportingCode: ASS
total: -35000
- name: Proceeds from sale of property, plant and equipment
total: 1000
accounts:
- accountId: abcdefab-4d1e-4d1a-9e4c-68b2c2a278e2
accountType: FIXED
accountClass: ASSET
code: "138"
name: Motor Vehicles at Cost
reportingCode: ASS
total: 1000
- accountId: abcdefab-5353-9d4b-7cad-51b2c2a2754a
accountType: FIXED
accountClass: ASSET
code: "140"
name: Equipment at cost
reportingCode: ASS
total: 0
- name: Financing Activities
total: -14000
cashflowTypes:
- name: Proceeds from borrowings
total: 1000.5
accounts:
- accountId: abcdefab-4d1e-4d1a-9e4c-68b2c2a278e2
accountType: TERMLIAB
accountClass: LIABILITY
code: "244"
name: Loan - Shellcoll Distribution 2019
reportingCode: LIA.CUR.LOA
total: 1000.5
- name: Repayment of borrowings
total: -15000.5
accounts:
- accountId: abcdefab-4d1e-4d1a-9e4c-68b2c2a278e2
accountType: TERMLIAB
accountClass: LIABILITY
code: "244"
name: Loan - Shellcoll Distribution 2019
reportingCode: LIA.CUR.LOA
total: -15000.5
"400":
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/Problem"
example:
type: invalid-request
title: InvalidRequest
status: 400
detail: Organisation xxx does not exist
"503":
description: Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/Problem"
example:
type: service-unavailable
title: ServiceUnavailable
status: 503
detail: Cannot process org xxx at this time. Apologies for inconvenience.
/FinancialStatements/ProfitAndLoss:
parameters:
- $ref: "#/components/parameters/requiredHeader"
get:
security:
- OAuth2:
- finance.statements.read
tags:
- Finance
operationId: getFinancialStatementProfitAndLoss
summary: Xero Get Profit & Loss report
description: The profit and loss statement is a standard financial report providing detailed year to date income and expense detail for an organisation.
parameters:
- name: startDate
x-snake: start_date
in: query
description: "Date e.g. yyyy-MM-dd\r\n\r\nSpecifies the start date for profit and loss report\r\n\r\nIf no parameter is provided, the date of 12 months before the end date will be used."
schema:
type: string
example: "2020-09-15"
- name: endDate
x-snake: end_date
in: query
description: "Date e.g. yyyy-MM-dd\r\n\r\nSpecifies the end date for profit and loss report \r\n\r\nIf no parameter is provided, the current date will be used."
schema:
type: string
example: "2021-09-15"
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/ProfitAndLossResponse"
example:
startDate: "2020-07-01"
endDate: "2021-06-30"
netProfitLoss: 123
revenue:
total: 20922.46
accountTypes:
- total: 20825.41
title: Trading Income
accounts:
- accountID: abcdefab-2006-43c2-a5da-3c0e5f43b452
accountType: REVENUE
code: "200"
name: Sales
reportingCode: REV
total: 20825.41
- total: 97.05
title: Other Income
accounts:
- accountID: abcdefab-4d63-4af8-937f-04087ae2e36e
accountType: OTHERINCOME
code: "270"
name: Interest Income
reportingCode: REV.OTH
total: 97.05
expense:
total: 1282.06
accountTypes:
- total: 1137.59
title: Direct Cost
accounts:
- accountID: abcdefab-d381-4bd6-ba47-7af927d25825
accountType: DIRECTCOSTS
code: "300"
name: Purchases
reportingCode: EXP.DC
total: 1137.59
- total: 144.47
title: Operating Expenses
accounts:
- accountID: abcdefab-f897-4168-b5d1-2279bf74bb82
accountType: EXPENSE
code: "453"
name: Office Expenses
reportingCode: EXP
total: 144.47
"400":
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/Problem"
example:
type: invalid-request
title: InvalidRequest
status: 400
detail: Organisation xxx does not exist
/FinancialStatements/TrialBalance:
parameters:
- $ref: "#/components/parameters/requiredHeader"
get:
security:
- OAuth2:
- finance.statements.read
tags:
- Finance
operationId: getFinancialStatementTrialBalance
summary: Xero Get Trial Balance report
description: The trial balance provides a detailed list of all accounts of an organisation at a point in time, with revenue and expense items being year to date.
parameters:
- name: endDate
x-snake: end_date
in: query
description: "Date e.g. yyyy-MM-dd \r\n\r\nSpecifies the end date for trial balance report \r\n\r\nIf no parameter is provided, the current date will be used."
schema:
type: string
example: "2021-09-15"
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/TrialBalanceResponse"
example:
startDate: "2020-07-01"
endDate: "2021-06-30"
accounts:
- accountId: abcdefab-3bbf-4f2a-9e4c-20ec7b8e6b41
accountType: ASSET
accountCode: ASS
accountClass: BANK
status: ACTIVE
reportingCode: ASS
accountName: Everyday transactions
balance:
value: 100
entryType: DEBIT
signedBalance: -23
accountMovement:
debits: 0
credits: 0
movement:
value: 123
entryType: CREDIT
signedMovement: 0
"400":
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/Problem"
example:
type: invalid-request
title: InvalidRequest
status: 400
detail: Organisation xxx does not exist
/FinancialStatements/contacts/revenue:
parameters:
- $ref: "#/components/parameters/requiredHeader"
get:
security:
- OAuth2:
- finance.statements.read
tags:
- Finance
operationId: getFinancialStatementContactsRevenue
summary: Xero Get revenue by contacts report
description: The revenue by contact report provides a year to date profit and loss for customers and suppliers for a given organisation, including detailed contact information.
parameters:
- name: contactIds
x-snake: contact_ids
in: query
description: "Specifies the customer contacts to be included in the report.\r\n\r\nIf no parameter is provided, all customer contacts will be included"
schema:
type: array
example:
- 00000000-0000-0000-0000-000000000000
- 00000000-0000-0000-0000-000000000000
items:
type: string
format: uuid
- name: includeManualJournals
x-snake: include_manual_journals
in: query
description: "Specifies whether to include the manual journals in the report.\r\n \r\nIf no parameter is provided, manual journals will not be included."
example: true
x-example-python: "True"
schema:
type: boolean
- name: startDate
x-snake: start_date
in: query
description: "Date yyyy-MM-dd\r\n\r\nSpecifies the start date for the report.\r\n \r\nIf no parameter is provided, the date of 12 months before the end date will be used.\r\n \r\nIt is recommended to always specify both a start date and end date; While the initial range may be set to 12 months, this may need to be reduced for high volume organisations in order to improve latency."
example: "2020-09-15"
schema:
type: string
- name: endDate
x-snake: end_date
in: query
description: "Date yyyy-MM-dd\r\n\r\nSpecifies the end date for the report.\r\n\r\nIf no parameter is provided, the current date will be used.\r\n \r\nIt is recommended to always specify both a start date and end date; While the initial range may be set to 12 months, this may need to be reduced for high volume organisations in order to improve latency."
example: "2020-09-15"
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/IncomeByContactResponse"
example:
startDate: "2019-10-17"
endDate: "2020-10-16"
total: 1200
totalDetail:
totalPaid: 400
totalOutstanding: 1000
totalCreditedUnApplied: 200
totalOther:
totalOutstandingAged: 1000
totalVoided: 150
totalCredited: 10
contacts:
- id: 1f580fe2-0659-31ee-eeb4-5c49d15d8bfa
name: FirstContact
total: 1400
totalDetail:
totalPaid: 400
totalOutstanding: 1000
totalCreditedUnApplied: 0
totalOther:
totalOutstandingAged: 1000
totalVoided: 150
totalCredited: 0
transactionCount: 3
accountCodes:
- "090"
- "200"
- 09-BANK
- id: 20e94281-4751-fb7e-ee5e-96b43ae93c8a
name: SecondContact
total: -200
totalDetail:
totalPaid: 10
totalOutstanding: 20
totalCreditedUnApplied: 200
totalOther:
totalOutstandingAged: 2
totalVoided: 3
totalCredited: 4
transactionCount: 1
accountCodes:
- "900"
manualJournals:
total: -100
"400":
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/Problem"
example:
type: invalid-request
title: InvalidRequest
status: 400
detail: Organisation xxx does not exist
/FinancialStatements/contacts/expense:
parameters:
- $ref: "#/components/parameters/requiredHeader"
get:
security:
- OAuth2:
- finance.statements.read
tags:
- Finance
operationId: getFinancialStatementContactsExpense
summary: Xero Get expense by contacts report
description: The expense by contact report provides a year to date profit and loss for customers and suppliers for a given organisation, including detailed contact information.
parameters:
- name: contactIds
x-snake: contact_ids
in: query
description: "Specifies the customer contacts to be included in the report.\r\n\r\nIf no parameter is provided, all customer contacts will be included"
schema:
type: array
example:
- 00000000-0000-0000-0000-000000000000
- 00000000-0000-0000-0000-000000000000
items:
type: string
format: uuid
- name: includeManualJournals
x-snake: include_manual_journals
in: query
description: "Specifies whether to include the manual journals in the report.\r\n \r\nIf no parameter is provided, manual journals will not be included."
example: true
x-example-python: "True"
schema:
type: boolean
- name: startDate
x-snake: start_date
in: query
description: "Date yyyy-MM-dd\r\n\r\nSpecifies the start date for the report.\r\n \r\nIf no parameter is provided, the date of 12 months before the end date will be used.\r\n \r\nIt is recommended to always specify both a start date and end date; While the initial range may be set to 12 months, this may need to be reduced for high volume organisations in order to improve latency."
example: "2020-09-15"
schema:
type: string
- name: endDate
x-snake: end_date
in: query
description: "Date yyyy-MM-dd\r\n\r\nSpecifies the end date for the report.\r\n\r\nIf no parameter is provided, the current date will be used.\r\n \r\nIt is recommended to always specify both a start date and end date; While the initial range may be set to 12 months, this may need to be reduced for high volume organisations in order to improve latency."
example: "2020-09-15"
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/IncomeByContactResponse"
example:
startDate: "2019-10-17"
endDate: "2020-10-16"
total: 1200
totalDetail:
totalPaid: 400
totalOutstanding: 1000
totalCreditedUnApplied: 200
totalOther:
totalOutstandingAged: 1000
totalVoided: 150
totalCredited: 10
contacts:
- id: 1f580fe2-0659-31ee-eeb4-5c49d15d8bfa
name: FirstContact
total: 1400
totalDetail:
totalPaid: 400
totalOutstanding: 1000
totalCreditedUnApplied: 0
totalOther:
totalOutstandingAged: 1000
totalVoided: 150
totalCredited: 0
transactionCount: 3
accountCodes:
- "090"
- "200"
- 09-BANK
- id: 20e94281-4751-fb7e-ee5e-96b43ae93c8a
name: SecondContact
total: -200
totalDetail:
totalPaid: 0
totalOutstanding: 0
totalCreditedUnApplied: 200
totalOther:
totalOutstandingAged: 2
totalVoided: 3
totalCredited: 4
transactionCount: 1
accountCodes:
- "900"
manualJournals:
total: -100
"400":
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/Problem"
example:
type: invalid-request
# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xero/refs/heads/main/openapi/xero-finance-openapi.yml