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

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

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>

NB : The Setup endpoint is currently released in beta. The response format is subject to change and will be finalised shortly.