Conversions guide


Overview

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

URL https://api.xero.com/api.xro/2.0/Setup
Methods Supported POST
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
Accounts See Accounts
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.

Required elements
AccountCode The account code for a account
Balance The opening balances of the account. Debits are positive, credits are negative values
Required Elements for Multi-Currency Balances
BalanceDetails A collection to specify multiple currency balances of an account
Elements for BalanceDetails
Balance The opening balances of the account. Debits are positive, credits are negative values
CurrencyCode The currency of the balance (Not required for base currency)
CurrencyRate (Optional) Exchange rate to base currency when money is spent or received. If not specified, XE rate for the day is applied

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.

2. Next you'll need to authorise access to the organisation via a Public or Partner application

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.

POST Setup

<Setup>
  <Accounts>
   <Account>
    <Code>200</Code>
    <Name>Sales</Name>
    <Type>SALES</Type>
    <ReportingCode>REV.TRA.GOO</ReportingCode>
   </Account>
   <Account>
      <Code>400</Code>
      <Name>Advertising</Name>
      <Type>OVERHEADS</Type>
      <ReportingCode>EXP</ReportingCode>
   </Account>
   <Account>
    <Code>610</Code>
    <Name>Accounts Receivable</Name>
    <Type>CURRENT</Type>
    <SystemAccount>DEBTORS</SystemAccount>
    <ReportingCode>ASS.CUR.REC.TRA</ReportingCode>
   </Account>
   <Account>
    <Code>800</Code>
    <Name>Accounts Payable</Name>
    <Type>CURRLIAB</Type>
    <SystemAccount>CREDITORS</SystemAccount>
    <ReportingCode>LIA.CUR.PAY</ReportingCode>
   </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)

POST Invoices

<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.

POST Setup

<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>

Multi-Currency Conversion Balances

If the balance of Accounts Receivable and Accounts Payable accounts comprise of multiple currency balances, you can enter it through setup endpoint.

Instructions

  • The general steps and rules to enter multi-currency balances are same as your base currency balances described earlier in this document.
  • Make sure your foreign currency balance matches the balance of your outstanding invoices and creditnotes in the same currency.
  • The additional elements for a multi-currency balance is <CurrencyCode> and <CurrencyRate>. If you do not provide a CurrencyRate, XE rate for the day of conversion is applied.
  • You don't need to provide CurrencyRate for base currency balance.
  • Balances must be specified in the <BalanceDetails> collection which is introduced to allow you supply multiple balances for the same account.

Example to post multicurrency conversion balances

<Setup>
  <ConversionDate>
      <Month>2</Month>
      <Year>2018</Year>
  </ConversionDate>
  <ConversionBalances>
      <ConversionBalance>
      <AccountCode>610</AccountCode>
        <BalanceDetails>
          <BalanceDetail>
            <Balance>5000.00</Balance>
            <CurrencyCode>USD</CurrencyCode>
            <CurrencyRate>0.735490</CurrencyRate>
          <BalanceDetail>
          <BalanceDetail>
            <Balance>2500.00</Balance>
            <CurrencyCode>AUD</CurrencyCode>
            <CurrencyRate>0.906751</CurrencyRate>
          <BalanceDetail>
        <BalanceDetails>    
      </ConversionBalance>
      <ConversionBalance>
        <AccountCode>800</AccountCode>
        <Balance>-5700.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.

Frequent Questions

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.

Example

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:
Description Account Tax Rate Debit Credit
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.