This guide describes how the Setup and other API endpoints can be used by developers building tools to assist converting users from other accounting systems to Xero
|Description||Allows you to replace the chart of accounts for an organisation|
|Allows you to set the conversion date and conversion balances|
Elements for Setup
|The following elements are optional|
|ConversionDate||The date when the organisation starts using Xero|
|ConversionBalances||See Conversion Balances|
Elements for ConversionDate
|The following elements are required when specifying a conversion date|
|Month||The month the organisation starts using Xero. Value is an integer between 1 and 12|
|Year||The year the organisation starts using Xero. Value is an integer greater than 2006|
Elements for ConversionBalances
A <ConversionBalance> element should be supplied for each account code that has a value on the trial balance as at the conversion date.
|AccountCode||The account code for a account|
|Balance||The opening balances of the account. Debits are positive, credits are negative values|
Example for entering conversion data
Follow the steps below to specify conversion details when migrating from another accounting system
1. First you’ll need to create an organisation in My Xero.
3. If your organisation is based in the US you can use the Tax Rates endpoint to setup any tax rates needed. For AU, NZ and UK organisations default Tax Rates are already setup so you can skip to step 4.
4. You’ll need to create the chart of accounts using the Setup endpoint described above.
Below is an example of creating a chart of accounts with the minimum elements required for each account. A set of system accounts will be included in the chart of accounts even if not specified in the request.
<Setup> <Accounts> <Account> <Code>200</Code> <Name>Sales</Name> <Type>SALES</Type> </Account> <Account> <Code>400</Code> <Name>Advertising</Name> <Type>OVERHEADS</Type> </Account> <Account> <Code>610</Code> <Name>Accounts Receivable</Name> <Type>CURRENT</Type> <SystemAccount>DEBTORS</SystemAccount> </Account> <Account> <Code>800</Code> <Name>Accounts Payable</Name> <Type>CURRLIAB</Type> <SystemAccount>CREDITORS</SystemAccount> </Account> </Accounts> </Setup>
5. Once the chart of accounts has been created you can use the Contacts, Invoices and Credit Notes endpoints to enter any customer & supplier details, outstanding invoices and credit notes as at the conversion date. It is crucial you complete this step before trying to enter your conversion balances (step 6 below)
<Invoices> <Invoice> <Type>ACCREC</Type> <Status>AUTHORISED</Status> <Contact> <Name>Equipment Repairers Ltd</Name> </Contact> <Date>2013-12-31T00:00:00</Date> <DueDate>2014-01-20T00:00:00</DueDate> <LineAmountTypes>NoTax</LineAmountTypes> <LineItems> <LineItem> <Description>Website design overhaul as agreed</Description> <Quantity>1</Quantity> <UnitAmount>5000.00</UnitAmount> <AccountCode>200</AccountCode> </LineItem> </LineItems> </Invoice> <Invoice> <Type>ACCPAY</Type> <Status>AUTHORISED</Status> <Contact> <Name>Loud Advertising</Name> </Contact> <Date>2013-12-20T00:00:00</Date> <DueDate>2014-01-20T00:00:00</DueDate> <LineAmountTypes>NoTax</LineAmountTypes> <LineItems> <LineItem> <Description>Print campaign for December</Description> <Quantity>1</Quantity> <UnitAmount>2000.00</UnitAmount> <AccountCode>400</AccountCode> </LineItem> </LineItems> </Invoice> </Invoices>
6. Use the Setup endpoint again to enter the conversion date and conversion balances.
- You’ll need to make sure your totals for Accounts Receivable and Accounts Payable match the outstanding invoices and credits notes (entered at step 5 above)
- Once your conversion balances have been accepted the setup will be marked as complete and a period lock date will be set as at the day before the conversion date.
- If an account is not specified then it’s balance will be assumed to be zero.
- Xero will automatically add a historical adjustments entry if the total of debit and credits do not match.
<Setup> <ConversionDate> <Month>1</Month> <Year>2014</Year> </ConversionDate> <ConversionBalances> <ConversionBalance> <AccountCode>200</AccountCode> <Balance>-5000.00</Balance> </ConversionBalance> <ConversionBalance> <AccountCode>400</AccountCode> <Balance>2000.00</Balance> </ConversionBalance> <ConversionBalance> <AccountCode>610</AccountCode> <Balance>5000.00</Balance> </ConversionBalance> <ConversionBalance> <AccountCode>800</AccountCode> <Balance>-2000.00</Balance> </ConversionBalance> </ConversionBalances> </Setup>
NB : The Setup endpoint is currently released in beta. The response format is subject to change and will be finalised shortly.
What is the “conversion date”?
The conversion date is the month and year that an organisation starts day-to-day use of Xero. For example, reconciling bank transactions and raising invoices.
How much historical data can I import into Xero?
- full transactional data up to one year prior to conversion date
- 3 years of monthly P&L comparative figures prior to the conversion date
Alternatively, yearly comparatives can be entered manually from the conversion balances screen.
How do I enter monthly P&L comparative figures?
You can enter monthly comparatives by importing in a series of monthly manual journals for revenue and expenses.
In the year prior to using Xero a business had the following P&L figures
- 12 months x $1,000 revenue = $12000 total revenue in the prior year
- 12 months x $900 expenses = $10800 total expenses
A typical monthly comparative manual journal posted at 30 April 2014 would look something like this:
|Historical Revenue||Sales||No GST||1,000.00|
|Historical Expenses||Lighting, Heating & Power||No GST||900.00|
|Adjustment||Historical Adjustment||No GST||100.00|
The imbalance between debits and credits ($100) can be journaled to the Historical Adjustments system account which is a balance sheet account so will not be shown on the P&L. The result of this means the organisation will have ‘clean’ comparative monthly P&L figures.
Do I have to import conversion balances if I have journaled historical transactions?
Yes. It is important the conversion balances are confirmed as Xero automates balancing of the accounts at the conversion date. The conversion balance journal (posted when conversion balances are successfully imported) will post any relevant adjustments to ensure the ledger is correct as per the finalised accounts. You can review the conversion balance journal posted by running the Journal Report
How do I add tracking to comparative balances?
You can do this by way of a manual journal too, learn more.