Overview

This article provides a detailed overview of the integration between Emersion and the Xero accounting software system.

The Emersion and Xero systems communicate via an API (application programming interface). Most of this module does it's work 'under the hood' and with little interaction with users of the system. To aid understanding, these terms used in the articles covering this module is defined as follows:

To 'pull' data means to download data from Xero into Emersion.
To 'push' data means to uploading data from Emersion to Xero.

Below is a list of features that are available when Emersion and Xero are connected via the integration layer.

Automatic Account Creation in Xero

When creating a new account in the Emersion system, the user can:

choose the customer from an existing contact list pulled from Xero.
create the contact in Xero automatically.

Users are also able to invoke these options after a new account has been created in Emersion.

See this article to see what data is transferred from Emersion → Xero during this process.

Do not update account information in Xero once a link has been established. Any changes made in Xero to a Xero contact will not be pushed back to Emersion.

Invoice Synchronisation

When an invoice is approved in Emersion, the invoice is pushed to Xero in an Authorised status, along with all cardlines and charges. All invoices generated from Emersion that are approved will be pushed to Xero.

When changes are made to an invoice in Xero and the invoice is an Emersion generated invoice, these changes are pulled into Emersion. These changes might also include:

credit notes
payments
over payments

Emersion will not pull invoices and invoice data for any invoices that were not generated in Emersion.

Credit Note Synchronisation

If the invoice has a negative (or CR) balance, the invoice will be pushed to Xero as a 'Credit Note'. Some examples include:

a credit invoice resulting from a dispute
an invoice where the sum of credits is greater than sum of all charges.

When an Emersion Invoice = APPROVED

amount >= 0 - Creates an invoice in Xero

amount < 0 - Create a credit note in Xero

Payment Synchronisation

When a payment is received in Emersion, it is pushed to Xero. In Xero, this is called an overpayment. At this point in time, the overpayment is not allocated to any invoices. As the payment is allocated (either wholly or partly) to an invoice(s) in Emersion, it will draw down on the corresponding Xero overpayment and reflect the same position in Xero.

If a payment is created in and allocated against an invoice in Emersion, the system will create an overpayment in Xero and immediately allocate it to the linked invoice.
If an overpayment (from Emersion) is detected to have been manually applied against an invoice in Xero, and the invoice was generated in Emersion, the system will create an allocated payment against the corresponding invoice in Emersion.
If an overpayment (from Emersion) is detected to have been manually applied against an invoice in Xero, and the invoice was not generated in Emersion, then it will be imported into Emersion as a refund with a reference to the Invoice 'Number' in Xero it was applied against.
If a credit note is applied to an Emersion generated invoice in Xero, it will create an allocated payment in Emersion.

The Emersion ledger journal entry that is linked to the payment record will store the GUID against it as a flag for the system to know that it has been pushed, and to not push it again.

Users must never delete or void a transaction in Xero that relates to an Emersion account/contact, invoice or payment. Damaging your data may result from these actions.

This table shows how payments are treated depending on where they originate and where the item exists.

	Source of Overpayment = Emersion	Source of Overpayment= Xero
Allocated item does not exist in Emersion	Create refund for account	Ignore
Allocated item exists in Emersion	Allocate the payment against the Emersion item	Allocate the payment against the Emersion item

Payment Reversals and Voiding Payments

Payment reversals and voids are ignored by the Xero module. Emersion's integration with Xero will not synchronise either of these payment activities automatically.

To ensure the customer account balances correctly in both systems, users must perform both steps below.

perform a payment reversal, or void a payment in Emersion
perform the same action in Xero.