The Xero integration syncs based on Advanced Billing statements. Statements are generated at the time of signup, renewal, and when prorated upgrades/downgrades occur. They contain all of the transactions for the billing period.
Each one of your Advanced Billing statements is synced to Xero as a new invoice as follows:
-
A Xero contact is created or updated to match the Advanced Billing customer details
-
All charges (non-tax line items) are assigned to a single Xero account (accounts receivable) of your choice
-
Discounts from coupons are computed as line-item discounts
- Taxes are calculated by Xero and added per-line item as follows:
- Any tax rate in Advanced Billing can be assigned to a Xero system tax rate, i.e. GST, for proper tax reporting
- Any tax rate in Advanced Billing that is NOT explicitly mapped to a Xero system tax rate will be “auto-synced” to Xero and used for the line-item
-
Any discrepancies between the Advanced Billing statement and the Xero invoice totals (due to rounding issues in tax calculations, for example), are reconciled via a special line item assigned to the system rounding account
-
Unpaid (past due) statements in Advanced Billing are properly reflected as Unpaid Invoices in Xero
-
Payments made via Advanced Billing are recorded in Xero, assigned to the account (bank account) of your choosing, and applied to the invoice, marking it as paid
- Credits in Advanced Billing (i.e. negative charges) are synced to Xero as Credit Notes that get attached to the invoice.
We recommend that you test the integration before going live yourself. First, you can connect your test/staging Advanced Billing site to a test Xero organization. Once you are comfortable with the mechanics of the integration, you can connect your production instances.
Contacts
Advanced Billing statements are synced to Xero contacts based on the contact number or contact code. When no matching contact exists, a new one is created with a contact number of Advanced Billing_ followed by the corresponding Advanced Billing customer ID. For example, if an Advanced Billing customer has the ID 123456, the Xero contact code will be set to chargify_123456.
For this reason, if there are already existing contacts in Xero that should be matched to Advanced Billing when the integration is first connected, it will be necessary to add the correct contact number to each contact in Xero. Otherwise the integration will create duplicate contacts and store invoices under them.
As the contact number / contact code field may only be edited via Xero’s API, please feel free to contact Maxio support if you need help updating them.
Additionally, if the integration syncs to an existing contact in Xero by means of manually adding a contact number, Advanced Billing information, such as email address and name, will override information already stored in Xero on the contact.
How it Works
Our Xero integration will automatically sync Advanced Billing billing activity to Xero as invoices.
Although Xero syncs both statements and invoices in Advanced Billing, the integration ultimately relies on the statement for syncing. This means that the reference number on the Xero invoice matches the ID of the statement ID in Advanced Billing. Additionally, we sync transaction data to Xero primarily based on statement events. More detail on the three conditions that we sync are below:
Closed Statements
Any time a new Advanced Billing statement is “closed”: this happens at the time of signup, renewal, or upgrade/downgrade migrations. A closed statement indicates that the billing period associated with the statement has ended and no new charges or payments may be added to it.
Settled Statements
When an Advanced Billing statement is “settled”:
-
For automatic billing, this usually happens simultaneously to the statement being closed, with one exception: when a subscription’s card fails to charge at renewal and the subscription becomes past due, the first event will be a closed statement to push the invoice into Xero. When the statement is paid a statement settled event will sync the payment to Xero.
-
For invoice billing, the statement is settled immediately at the beginning of the billing period without waiting for payment. Please refer to the section on invoice billing for more information on the caveats of invoice billing with Xero.
Refunds
When a successful refund is made in Advanced Billing the Xero integration will sync this information.
Caveats for Negative Balances and Statements
In Advanced Billing, it is possible to have a statement with a negative total. This can happen in the case of a downgrade, where the credit for the unused portion of the more expensive plan is more than the cost of the new, less expensive plan. In the Xero integration, this can create an issue when these situations are present.
Advanced Billing statements work off of a “rolling balance” model. A negative statement just results in an overall negative balance on the subscription, which will be applied towards future charges. In other words, the next statement will have a negative opening balance, and payment will only be due if the new charges exceed the amount of the negative balance, pushing the balance into positive territory.
You can think of an Advanced Billing statement as a snapshot of the journal entries in an account – each entry affects the account balance by pushing it up or down.
In Xero (and accounting, in general) the concept of a negative invoice doesn’t make sense, because the invoice is a record of what an entity owes. So, there is not always a one-to-one mapping between an Advanced Billing statement and a Xero invoice, since a statement may have a negative total but an invoice may not.
To reconcile this, Advanced Billing statements with negative totals are pushed to Xero as credit notes, not invoices. Usually, credit notes would be applied to future invoices to offset the amount due, much like Advanced Billing offsets future charges against a negative starting balance. Where Advanced Billing does this automatically, on a rolling basis, Xero requires an explicit action to link a credit note to an invoice. Xero calls this “allocating” credit notes to invoices, and we do this for you when an invoice contains both positive and negative charges. However, due to system limitations, credit notes created due to negative statement totals are NOT automatically allocated to future invoices. Instead, when a subscription carries a credit into a new statement period (i.e. there is a negative balance), we offset the charges on the Xero invoice with a special line item so that the amount due on the Xero invoice matches the amount due on the Advanced Billing statement. This means that you may end up with “orphan” credit notes in Xero, which you will want to reconcile later by archiving once the credit has been used up.
Refunds
Refund transactions initiated in Advanced Billing are synced immediately to Xero. For refunds, we do not wait for the statement to close or settle, even though the refund itself will appear on an Advanced Billing statement. Refunds are implemented in Xero as a Credit Note with a cash refund applied.