Xero Reference

This integration is currently in beta status.

Our Xero integration will automatically sync Chargify billing activity to Xero as invoices.

Due to limits that Xero has placed on their API, the integration is limited to syncing about 500 invoices per day. If you have more than 500 subscriptions renewing on a single day, please note that it may take several days for the data to be fully synced to Xero.

How it Works

Charges and credits added during the billing period, including component allocations, will not sync to Xero until the statement settles or closes at the end of the period.

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 3 conditions that we sync are below:

Closed Statements

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.

Settled Statements

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, that will fire a statement settled event to push the payment in.

  • For invoice billing, the statement is always 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”.

Begin the process to authenticate your Xero account for use in Chargify
Follow directions in Xero and enter required information
Grant access to Chargify

Configuring the Integration

Example view of configuration of your Xero account

Invoice Account

The “Invoice Account” is the Xero account (from the Chart of Accounts) that will be assigned to all invoice line items (i.e. transactions). We populate this drop down selection with your accounts from Xero classified as either sales, revenue, or other income.

Payment Account

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 then 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.


When your Chargify and Xero currencies match

Usually, your Chargify Site and your Xero Organization will use the same currency. In this case, your “Chargify Currency” will match your “Xero Base Currency” and you’ll see checkmarks next to each.

Note: If you have connected the integration before, but disabled continuous exporting, you’ll need to re-enable this to export your data. To start exporting data to Xero, click the “Enable Continuous Xero Exporting” button.

Currency configuration in Chargify matches Xero

When your Chargify and Xero currencies do not match

It is possible to set a currency in Chargify that differs from your base currency in Xero. It is required, however, that the currency of your Chargify site has been enabled in your Xero settings.

When the Chargify currency is not supported by your Xero Organization, you will see a warning and a link to the settings page in Xero where you can make this change.

Currency configuration in Chargify does not match Xero

Once you have added the currency to your Xero-supported currencies, you will see the appropriate checkmarks.

When your Chargify and Xero base currencies do not match, we supply the Chargify-originated currency code to Xero when creating Invoices and Credit Notes. Xero will handle all currency conversions, and your invoices and payments in Xero will be represented in the correct currency.

Note: If you enabled the Xero integration before Jan 15, 2015, and would like to make use of this currency code support, you will need to re-visit the Xero configuration within Chargify so that we can recognize the currencies your Xero Organization supports.

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.

Please do not delete or modify the taxes we create in Xero!

These taxes have names in the format of CFYnnn: X% - Tax Name, where nnn is a 3 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.

Tax configuration

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 is up to you. If you map a 15% tax rate in Chargify to a 10% system tax rate in Xero, then Chargify will calculate and charge the 15% correctly, but the Xero invoice will calculate the rate at 10%. Then, 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 then 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 about this feature, in general, 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 is a prorated credit for a taxable component.

Syncing Chargify Statements to Xero Invoices

Example invoice in Xero

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:

  1. A Xero “contact” is created or updated to match the Chargify customer details.
  2. 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.
  3. Discounts from coupons are applied to the invoice line items, as applicable.
  4. Chargify sends taxation information to Xero, but allows Xero to calculate taxes itself based on rates Chargify supplies:
  5. 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
  6. Unpaid (past due) statements in Chargify are properly reflected as Unpaid Invoices in Xero
  7. 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
  8. 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

We strongly recommend not turning the Chargify created items into "Tracked Items" in Xero. If an invoice would cause the item to fall below 0 it will cause the invoice to not sync and stall out the integration.

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:

  1. Click the “Settings” tab and choose “General Settings”
  2. On the right side of the screen click the “Chart of Accounts” link
  3. Click “Add Account” button
  4. The account type must be one of the options under “Revenue” (Other Income, Revenue, Sales)
  5. Give it a unique code number
  6. Give it a name
  7. Click the “Save” button

Next is to set the products and components to map to these sales accounts.

  1. Click the “Accounts” tab at the top of the screen and select “Inventory”
  2. Click on the name of the component or product you want to map
  3. Click “Edit Item” at the top of the screen once viewing the component or product
  4. In the “I sell this item” section use the dropdown to select the sales account you want this item associated with
  5. 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!