Important : Please Read There are a number of elements that you need to configure, all of these come with some level of caution and you should not attempt these without your Accountant or a Company Director taking responsibility for any decisions you make.  Software Add-ons Limited – The Home of OpenCRM are a certified App partner in the Xero marketplace and understand the development aspects of Xero Accounting Software but are not accounting specialists – you should seek independent advice from a Xero specialist when making any changes to your Xero Accounting installation and any integrations. Integration between Xero and OpenCRM shares sensitive financial information which should be treated appropriately. When you push a new Invoice to Xero it has the potential to create duplicates if the original Contact information does not match, you should plan how you will integrate the two data sets to avoid any duplication arising. If you have any concerns about your own ability to setup the systems to work together please speak with your OpenCRM Account Manager to schedule some time with our professional services team.

 

Now that we have that over, on to the main article. In this FAQ, we're going to cover:

1. Using the OpenCRM to Xero integration, including

a. Sending to Xero

b. Updating from Xero

c. How to handle payments

3. Some other options you have for managing this integration, 

4. Using parent/child companies with Xero

5. What to do if something goes wrong and

6. Some general notes you should be aware of.

We recommend that you read ALL of the below before you start using this integration, just to make sure it is all familiar to you.

 

If you still need to set up your integration between OpenCRM and Xero, please see this article.

 

 

 

 

Using Xero Integration

On Invoice home screen, there are two buttons - Send to Xero and Update From Xero. These buttons are only visible if integration is enabled, and the current connection has not expired.

 

You will then see a page that shows you what it is doing and any errors encountered. 

It will send items to Xero in the following order: 

1. Product items needed for the invoices selected
2. *Contacts needed for the invoices selected 
3. Invoices
4. Credit Notes.

*NOTE: Xero has a single record type "Contact" which is a combination of contact and company details from OpenCRM. Your invoice in OpenCRM requires a linked Company in order to be sent to Xero.

Any errors encountered are displayed at the bottom of each section. If there are any errors, at the end of the process, the screen asks you to review these before continuing. If no errors are found, you will be automatically redirected back to the invoice list. 

 

Sending/Updating Invoices

There is no change when sending invoices/updating invoices from Xero with multiple organisations connected. Simply select all the ones you wish to send/update and click the relevant button as before. The system decides based on the Accounts Company field on the invoice which Xero organisation the invoice is sent to or updated from. If you are not using Xero with multiple organisations then the Accounts Company field will be hidden by default and will be populated automatically.

 

 

 

 

Send to Xero

This button will send selected invoices (and associated company and contact information) to Xero. It will send all invoices even if they have already been sent to Xero, so long as the outstanding balance matches the total amount. As soon as the outstanding balance is below the total amount (i.e. payments have been made in Xero), the invoice is no longer sent to Xero. The invoice status is ignored, so this will send Pending and Paid invoices so long as the outstanding and total balance matches.

Information synced from the Company record in OpenCRM into the Contact record in Xero includes Company Name, Xero Reference and Address details. On the Contact screen in Xero the Company name is displayed at the top, and Company Address/ Contact details are displayed down the right hand side.

As well as the Company, Xero also picks up details from the linked Contact - Contact Name and Email Address.

 

 

 

Update From Xero

This button will update selected invoice balances from Xero, and update associated companies with their Xero reference. It will NOT update company balances. It will only get updates for invoices not marked as Paid or cancelled and where the Sent to Accounts field is checked. 

Once an Invoice has been updated from Xero, the status will be updated from Created to Live. The Invoice will also be marked as having been Sent to Accounts, with the Date on which it was sent, you'll this this information in the following two fields:

 

 

 

Payments

With this integration, it is important that the payment side is managed in Xero.

Once Payments (in Xero) have been logged, these will be reflected in OpenCRM if the Update from Xero option is selected. It will show part-payments and full payments, updating the status to either "Part Paid" or "Paid", and the Amount Outstanding field will be adjusted accordingly. 

How does Xero handle payments, does it sync use the payments tab on OCRM?

No - we don't sync Xero payments to payment records in OpenCRM.

You make the payment in Xero, which updates the balance on the invoice in Xero which is updated in OpenCRM by the sync. No payment record is recorded in OpenCRM.

If you delete payments on OpenCRM does this update the "outstanding" balance on the invoice in OpenCRM?

Yes. It recalculates the outstanding amount based on the remaining payments against the Invoice. This would override the value that had been set from the Xero sync.

What about part payment? If an Invoice is marked as Part Paid in OpenCRM, what happens then?

The total value of the invoice would not match the outstanding amount and Xero would have no reference for a payment being made. Xero would just reject the record. 

Ergo, the payments need to be made in Xero. 

 

 

 

Other Options

In the tools section, there are links to send all live invoices (that is all invoices where the outstanding amount is equal to the due amount),and update all live invoices (all invoices not marked as Paid and which have previously been sent to Xero).

 

 

Send All Outstanding Invoices to Xero

Sends all invoices where the outstanding amount is equal to the due amount, and the status is not Paid or Pending

 

 

Update all Outstanding Invoices from Xero

This will go through all invoices not marked as Paid or Cancelled and which have previously been sent to Xero and query Xero for an updated balance. It will update associated companies with their reference in Xero. Additionally, at the end it will update all company balances following the invoice update. This could take some time to complete, during which time your OpenCRM session on that browser will be locked and unusuable. 

 

 

Billing a Parent Company for Invoices made out to Child Companies

Sometimes you deal with hierarchical organisations. That means there is a Head Office (Parent Company) and subsidiary Companies (Child Company). To understand how this function (Member Of) works within OpenCRM, please take a look at this FAQ.

If you are using our Xero integration, you will need to decide whether any invoices you raise for these entities should be against the Child Company, or against the Parent Company. Bear in mind that each time you invoice against a new Child Company, it will create a new Contact Account in Xero.

Invoices should be billed to the Child Company

This is the out-of-the box set up. There is no additional configuration required here.

Invoices should be billed to the Parent Company

If you are raising invoices against Child Companies in OpenCRM, but want to associate those with the Parent Company record in Xero, then you need to enable the following:

Go to Settings > Default Organisation Field Access > Company Field Access and ensure the Use Member Of For Xero field is enabled:

Note that if you are using Layouts, you will need to add this field to your Layouts.

Once the field is enabled, it will be visible on the Company record:

In that example, you can see there is a Child Company called "New Foundation East Division", and they are a member of "New Foundation Media". As the Use Member Of For Xero field is ticked, any Invoices raised against the Child Company record will be linked to the Parent Company when the Invoice is pushed to Xero.

In addition, you will probably want to enable the following option under Additional Settings > Company Settings:

This will ensure that the Invoices are set with the correct billing address.

 

 

Logging / Error Checking

* In order to create an Invoice in Xero, the sync will first add the Products. This is so it can link any existing or new Products to the Invoices in Xero. If there is a problem with any Product row, this will not send any invoices, until the error has been corrected. An error message will be displayed which outlines the problem Product(s).

* When sending multiple invoices, each invoice will be sent separately to ensure any errors only affect the relevant invoice. For example, if you send three invoices and two send successfully and one fails, the two which are sent successfully will be marked sent to Xero.

* A separate log table "xero_log" is updated on any successful attempt to send the invoice and any errors are logged in here too.

 

 

Important Notes and Info

* Invoices and credit notes sent currently go into the "Drafts" section in Xero where they can then be approved.

* OpenCRM's integration with Xero allows you to create a new Client record, with a Primary Person linked (first name, last name, email address). If you sync a subsequent invoice for the same client, but with a different Person linked, it will not add a second Person, but will overwrite the first Person.

* Finance and System admins only are able to access the Xero settings page and send invoices to Xero or update balances from Xero.

* Line amounts are passed through as the full undiscounted amount. The discount rate is calculated to a percentage per line and passed through to Xero which then calculates the actual line total.

* Credit notes are transferred with list prices as the discounted amount because Xero does not support discount on credit notes.

* Update of balances on credit notes is not yet supported.

* Product (Inventory) Name in Xero is limited to a length of 50 characters. If your products are set up in OpenCRM with a longer name (in excess of 50 characters), you will need to modify the name to allow the integration to work.