The Xero integration syncs based on Chargify 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 Chargify statements is synced to Xero as a new invoice as follows:
A Xero contact is created or updated to match the Chargify 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 Chargify can be assigned to a Xero system tax rate, i.e. GST, for proper tax reporting
- Any tax rate in Chargify 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 Chargify 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 Chargify are properly reflected as Unpaid Invoices in Xero
Payments made via Chargify are recorded in Xero, assigned to the account (bank account) of your choosing, and applied to the invoice, marking it as paid
- Credits in Chargify (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 Chargify site to a test Xero organization. Once you are comfortable with the mechanics of the integration, you can connect your production instances.
Chargify 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 chargify_ followed by the corresponding Chargify customer ID. For example, if a Chargify customer has the ID 123456, the Xero contact code will be set to
For this reason, if there are already existing contacts in Xero that should be matched to Chargify 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 Chargify 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, Chargify 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 Chargify billing activity to Xero as invoices.
Although Xero syncs both statements and invoices in Chargify, 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 Chargify. Additionally, we sync transaction data to Xero primarily based on statement events. More detail on the three conditions that we sync are below:
Any time a new Chargify 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.
When a Chargify 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.
When a successful refund is made in Chargify the Xero integration will sync this information.
How to Enable the Integration
The Xero integration tab is found within the main Integrations tab on each of your sites. To start using the integration, click “Connect to Xero”.
Configuring the Integration
The “Invoice Account” is the Xero account (from the Chart of Accounts) that will be assigned to all invoice line items. We populate this drop-down selection with your accounts from Xero classified as either sales, revenue, or other income.
The “Payment Account” is the Xero account (from the Chart of Accounts) that will be assigned to payments. We populate this drop-down selection with your accounts from Xero classified as either bank accounts or accounts that have payments enabled.
Create Item Codes in Xero
The “Sync product and component names as item codes” option allows you to toggle on/off the integration creating item codes within Xero. If this option is selected we will automatically create item codes in Xero based on your component and product names. These created item codes will be used on all future Xero invoices. After the first sync of an item you can associate a specific sales account with it, outlined later in this documentation. This option can be turned on/off after the configuration has been completed.
Your Xero account must contain all currencies configured within your Chargify site. If your Chargify site makes use of a currency that is not yet configured in Xero, an error message will be displayed and you’ll be prompted to add the missing currencies in your Xero account settings.
Once you have added the currency to your Xero-supported currencies, you will see the appropriate checkmarks.
Taxes (US & Global Versions)
For the US and Global versions of Xero, no tax configuration is necessary. We “auto-sync” the taxes generated by Chargify by automatically creating matching tax rates within Xero.
These taxes have names in the format of
CFYnnn: X% - Tax Name, where
nnn is a three digit number and X represents the effective tax rate.
If you do delete one of these rates in Xero, we will recreate it so the integration will not be broken. However, your tax reporting may be affected, in that the same logical tax will be split across several different Xero tax rates (some of them archived).
If you modify one of these rates in Xero, we will continue to use it, which will cause your Xero invoices to show a “rounding adjustment” to account for the discrepancy.
Taxes (AU, NZ, and UK Versions)
Xero maintains a set of “System Tax Rates” for certain taxes (like GST) in the AU, NZ, and UK versions. In order to make use of these tax rates, you will need to tell us which Chargify taxes map to which Xero system taxes.
For each of your Chargify-defined tax rates, you may pick a system tax from Xero to which it maps or allow us to sync the tax automatically (as described in the section US versions, above). If you wish to use the Xero system tax rates, you must select a specific tax rate – do not select “Sync Automatically” in this case.
Note that, if you choose a tax mapping here, we do not make sure that the rates match - this will be up to you. If you map a 15% tax rate in Chargify to a 10% system tax rate in Xero, Chargify will calculate and charge the 15% correctly, but the Xero invoice will calculate the rate at 10%. As a result, your Xero invoice will show a “rounding adjustment” for the 5% discrepancy. In this case, both sides will show the same totals, but you will not have the tax revenue properly accounted on the Xero side.
Chargify and Xero Tax Information
Chargify supplies tax rate information to Xero and the taxation status of each line item and lets Xero calculate the actual taxes. Differences in totals due to rounding issues are accounted for by adding adjustments via the system rounding account.
Whether you use Chargify Custom Taxes or Avalara Managed Taxes on the Chargify side, we handle the conversion to Xero taxes for you.
Chargify Custom Taxes
Chargify allows you to create multiple taxes, each of which can have multiple tax rules. Depending on your configuration each transaction in Chargify is potentially taxable by multiple taxes and multiple tax rules.
Xero only allows a single tax rate per line item. To account for this, Chargify taxes for any given transaction are “combined” into a single Xero tax rate composed of several Tax Components. Overall, the tax rate we sync to Xero will have the same effective rate as the individual taxes and rules in Chargify.
The lowest available “resolution” for Chargify custom taxes is at the state level. County and local tax jurisdictions cannot be created. If you require tax resolution at the local level, please use the Avalara Managed Taxes described below.
Avalara Managed Taxes
Avalara Managed Taxes allow you to apply specific sales tax rates, down to the local level, for all of your customers. For more general information about this feature, please see the Avalara Managed Sales Tax documentation.
When Avalara Managed Taxes apply to a transaction we record the individual components of that tax. For example, most counties in North Carolina have a 6.75% sales tax rate, which is comprised of a 4.75% state tax, and 2.0% county tax.
We sync such a tax to Xero as a single tax rate with two components – one for the state tax and one for the county tax. These taxes are intelligently labeled on the Xero side, so there will never be a question of what tax was applied.
Mapping to Special Xero System Tax Rates
For the AU, NZ, and UK version of Xero, we allow you to map each Chargify tax to a corresponding system tax rate in Xero. More information on this feature can be found in the section on AU, NZ, and UK Tax Configuration, above.
Taxes on Refunds and Credits
Please note that refunds are always synced to Xero as tax exempt. If the original charge that is being refunded included taxes, you will need to record a Journal Entry to adjust the tax amount.
Most Credit Notes will also sync as tax exempt because there are no taxes associated with the credit in Chargify. An exception to this rule is a prorated credit for a taxable component.
Syncing Chargify Statements to Xero Invoices
A Xero invoice is created whenever a Chargify statement is closed (i.e. at signup, renewal, or upgrade/downgrade). Here are the steps we take when we create an invoice:
- A Xero “contact” is created or updated to match the Chargify customer details.
- All charges (non-tax line items) are assigned to a single Xero sales/revenue account (that you choose during configuration) and added to a new invoice.
- Discounts from coupons are applied to the invoice line items, as applicable.
- Chargify sends taxation information to Xero, but allows Xero to calculate taxes itself based on rates Chargify supplies.
- Any discrepancies between the Chargify 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 Chargify are properly reflected as Unpaid Invoices in Xero.
- Payments made via Chargify are recorded in Xero, assigned to the account (bank account) of your choosing and applied to the invoice, marking it as paid.
- Credits in Chargify (i.e. negative charges) are synced to Xero as Credit Notes that get attached to the invoice.
Payment data is not pushed to Xero until a Statement is “settled” in Chargify. This happens when the statement is successfully paid, which could be when the renewal happens, or perhaps later after the payment is retried.
Chargify Invoice Billing
When an invoice is generated in Chargify at renewal, it will be synced to Xero immediately. Invoices that are issued mid-period will not be synced to Xero until the current billing period ends and the statement is settled.
When a payment is applied to the Chargify invoice, this payment is not synced to Xero. If you are using Invoice Billing, you will need to manually record the payments in Xero.
Additionally, charges and credits applied to Chargify Invoices are not synced to Xero. These will need to be manually recorded in Xero.
It is important to note that even if you are using Invoice billing, the basis for syncing data to Xero is statements, which are tied to the billing period. Please review the “How It Works” section for more information on when data will be synced to Xero.
Caveats for Negative Balances and Statements
In Chargify, 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.
Chargify 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 a Chargify statement like 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 a Chargify statement and a Xero invoice, since a statement may have a negative total but an invoice may not.
To reconcile this, Chargify 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 Chargify offsets future charges against a negative starting balance. Where Chargify 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 Chargify 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.
Refund transactions initiated in Chargify 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 a Chargify statement. Refunds are implemented in Xero as a Credit Note with a cash refund applied.
Linking products and components to sales accounts
If you have the “Sync product and component names as item codes” enabled, you will be able to set the products and components associated with the invoices to be in a specific sales account. Once set all future syncs will get moved into the correct sales account.
The first step would be to setup the sales accounts you want to set for the products and components if they aren’t already created. To do so, complete the following steps in Xero:
- Log into your Xero account
- Click Accounting->Chart of Accounts under the Advanced options.
- Click “Add Account” button
- The account type must be one of the options under “Revenue” (Other Income, Revenue, Sales)
- Give it a unique code number
- Give it a name
- Click the “Save” button
Next is to set the products and components to map to these sales accounts.
- Click Business->Products and Services.
- Click on the name of the component or product you want to map
- Click “Edit Item” at the top of the screen once viewing the component or product
- In the “I sell this item” section use the dropdown to select the sales account you want this item associated with
- Click “Save” on the bottom of the pop-up
Repeat the above process for each product and component. Once this is completed it will continue to map with all future syncs!
Can I merge my existing Xero contact with one Chargify created?
As described in the overview section, we require that the contact number / contact code 1) exist on the contact and 2) match the format we expect in order to sync to it. This means that the existing Xero contact must be merged into the Chargify-created one.
If this is done the other way around, the Chargify-created contact will become archived. However, the integration is unable to sync to archived records, and no invoices will be able to be synced until the Chargify-created contact is restored or edited. Please feel free to contact Chargify support if you would like help merging contacts.
Why does Chargify create duplicate contacts?
If the contact existed in Xero prior to your enabling Chargify’s Xero integration, then unfortunately, this is going to happen.
We have no way of knowing that a “John Smith” in your Xero Organization is in fact the same one that we have in Chargify, so we must create a new contact. A way around this would be edit the Xero contact’s number via API as described in the overview section.
Are old statements & transactions synced to Xero?
The integration does not have an option for a historical sync. In other words, only new statements and invoices that are created after you enable the integration will be sent to Xero.
That said, if the Xero integration becomes disconnected for any reason after it was previously enabled, when you reconnect, all statements that were missed during during that period will be synced over automatically. The Xero API has a limit on the number of invoices that may be synced in a given day; depending on the number of invoices that were missed, it may take a few days for all of them to sync over.
Can I associate different transactions with different sales or revenue accounts in Xero?
No, at this time, you can only pick one account for all of your invoice line items.
What happens if a Chargify-created tax rate is deleted in Xero?
The short answer is: nothing too bad. We detect that the tax rate has “gone away”, and we re-sync it with Xero. However, this will have the effect of creating a different tax rate in Xero, with a different name, but with the same rates. Since this will segment your tax reports unnecessarily we recommend that you do not delete the rates we create in Xero.
Can I connect multiple Chargify Sites to my Xero Organization?
Yes, you can connect more than one Chargify Site to the same Xero Organization.
What if I need to change the Xero Organization that my Chargify Site is connected to?
If you have connected a Chargify Site to a Xero Organization and later need to switch to a different Xero Organization, please contact support.
Why does Chargify append a number to the Contact Name?
Xero currently requires that Contact Names be unique within an Organization, which is why we append the Chargify Customer ID in parentheses.
Does the integration sync custom field data?