Configuring Xero 

Integrating your Xero account with Chargebee automates the synchronization of Invoices, Customers, and other crucial data from Chargebee to Xero for your financial management and analysis.

We recommend that you consult your accounting advisor before configuring the integration. You can test the integration on the Test Site before setting up the integration on the Live Site.


Enable Accounting Fields 

Ensure that you have enabled Accounting fields for Xero. You can enable this by navigating to Settings > Configure Chargebee > Billing LogIQ > Enable Accounting Fields for integration.

Set up Product Catalog 

Enter/update accounting information for Plans and Addons price points in Chargebee. There are four accounting fields required to be filled to configure the integration between Chargebee and Xero.

They are SKU, Accounting Code, Accounting Category 1 (Optional) and Accounting Category 2 (Optional)

  • SKU/ Product Code/ Item ID: If a product/ service is already present in Xero, you can map the products by entering the Item ID/ SKU in Chargebee and avoid duplicates from being created.
    Note: When Xero sync error - Price List Item Code must not be more than 30 characters long error appears during sync. Ensure to use the SKU for the item instead of the ID. This is necessary when the item ID exceeds 30 characters. Using the SKU ensures the item syncs correctly, allowing associated invoices and credit notes to process without errors.

  • Accounting Code: The General Ledger Account code in Xero should be entered. This lets Chargebee know in which Account the product related transactions should be posted to, in Xero.

  • Accounting Tracking Category 1, 2: You can provide additional information for tracking purposes, such as Class or Location. Tracking category can be set at customer level as well, contact support  to set this up.

When you add new plans, addons, and price points in Chargebee anytime after the integration is set up, do not forget to enter the GL Account Name and SKU fields.

Check Currency settings 

If you have multiple currencies enabled in Chargebee, ensure that these currencies are enabled in Xero as well. You can view your currencies in Chargebee by navigating to Settings > Configure Chargebee > Currencies.

Verify character length of Plan/Addon Price Point ID 

You can create a plan/addon price point with an ID of up to 50 characters in Chargebee. However, Xero supports an Item ID of up to 30 characters only. If there are price points with an ID exceeding 30 characters, then you should enter an alternative ID as the SKU. In order to update the ID, navigate to the Product Catalog > Select a Plan/Addon > Select a price point > Edit > Enter an alternate ID in the SKU field.


Step 1: Connect Chargebee to Xero 

  • Login to your Chargebee site.
  • Connect to the Xero application listed on Chargebee's app marketplace by selecting Apps > Marketplace > Xero.
  • Click Connect to get started with the integration.
  • Login to your Xero account.

  • In your Xero account, you can manage multiple organizations. Select an Xero organization and click Allow access to provide access to data. The Demo Company (Global) organization is selected and currently displayed in this image. You can choose which Xero organization you want to connect with.

Step 2: Check Prerequisites 

Chargebee performs a list of checks in Xero to verify whether the accounting codes, customers, and their currencies in Xero are available in Chargebee before proceeding with the integration.

  • Customer duplicate check: If invoices from Chargebee are already available in Xero, customers will also be present. To avoid duplicates, you must map the customer records between both systems. Once the setup is complete, you can download the list of customers as a CSV file, map the customers, and upload the updated sheet using Record mapping.

  • Currency check: The currencies present in Chargebee must also be in Xero. Chargebee does not compare the currencies via API. You should manually compare and add the currencies in Xero.


If customer data exists in Xero, the following error message will be displayed. In such cases, you can contact

Proceed will be allowed after all checks are either passed or ignored. While these checks are being conducted, or in the event of failed checks, the Proceed button will be disabled. Click Proceed to move to the next step.

Step 3: Sync Preferences 

In this section, you must perform account mapping for payments, invoice line items, and refunds.

Account Mapping for Payments and Refunds

Map Payment transactions recorded in Chargebee to payment accounts in Xero. For reconciliation purposes, you can select a clearing or undeposited funds account. You can choose specific payments or checking accounts if you have multiple currencies, payment gateways, or payment methods enabled.

Account Mapping for Invoice Line Items

Account mapping for invoice line items involves assigning specific accounts or categories to each line item on an invoice.

Offline Payment Configuration

Offline Payment Configuration offers flexibility for automatically syncing offline payments from Xero to Chargebee. You can enable Offline Payment Configuration using the toggle button. If offline payment sync is enabled, Chargebee will create transactions during the sync when you apply a payment to a Chargebee invoice in Xero. Any further updates to the transaction in Chargebee will not be synced for this transaction. You can enable this to allow sync to handle offline payments automatically or disable it, and in that latter case, you need to record offline payments in Chargebee manually.

Tracking Categories

You can enable Tracking Categories using the toggle button on the Sync Preferences page. When the button is enabled, you can send tracking category information from Chargebee for Invoice line items. Tracking categories are applied exclusively at the line item level.

Step 4: Map Product Catalog 

Once the account mapping for payments, invoice line items, and refunds is done, click Proceed to move to the next step.

You can upload a CSV file containing mapping details of products. Within these mappings, you can specify accounting codes for each entry.

The sample downloaded CSV file contains the following fields:

CSV Field Name


Additional Info


Unique identifier for Chargebee's item prices.



Name of the item price in Chargebee's product catalog.



SKU of the product

 This field maps the existing items from Xero to the respective plan/addon in Chargebee. It can be used as an alternative name for plan/addon and its character limit should not exceed 30 characters.


The accounting code associated with the item

 The Accounting code field should be filled for all the plans and addons.


Accounting Category 1

If you've classified Dimensions for your products in Xero, and would like to sync data specific to it, enter the information here.


Accounting Category 2

If you've classified Dimensions for your products in Xero, and would like to sync data specific to it, enter the information here.

If there are any errors during validation, an error message is displayed. To fix this, re-upload the file with the correct mapping.

View the successfully mapped records as shown below upon successful validation.

  • Once the product catalog mapping is completed, accounting configurations such as account codes, SKUs, and item price details will no longer be applicable.
  • If you prefer not to create multiple items and instead use a single item for all business entities, ensure that the SKU remains consistent and upload the CSV file accordingly.
  • To streamline the process and save time, we pre-fill the CSV file with information from the UI filled on the item prices page's accounting details tab. Even if there are no changes, the CSV file must be re-uploaded initially.

Step 5: Configure Tax Mapping 


This step will be available only if you have enabled taxes in your Chargebee site.

Chargebee retrieves both the default and custom tax rates that are created in your Xero account. You can select a tax rate from the drop-down list and map for each category and region.

If you are using a US edition of Xero [International Edition]

Chargebee creates tax rates in Xero automatically.

If you are using a Canada, India, New Zealand, Australia, Singapore, or South Africa version of Xero
You can select from the list of tax rates from Xero for the following categories:

Category Select a tax rate from Xero
Sales Select a tax rate to map all your taxable sales, for instance, New Zealand - 15% GST.
Exempt Select a tax rate to map exempt sales (either the Customer is exempt or the Product is exempt).
Export Select a tax rate to map sales to any other country outside taxable regions.

If you are using the UK edition of Xero
EU VAT Returns filing is supported from within Xero. Xero creates default tax rates to facilitate accurate VAT Liability reporting. While configuring the integration, you can select from the default rates created in Xero already.

See also

Click here to learn more about how Xero supports UK merchants in filing VAT Returns for UK Merchants.
List of default Tax types in Xero.


(What is MOSS?)
In case you are selling Digital subscriptions across the EU region and have registered for MOSS, you should setup taxes for the following categories:

Category Select a tax rate from Xero
Sales Select a tax rate to map all your taxable sales.

Tip: You can also utilize the MOSS Reporting feature in Xero for filing returns.
Exempt Sales Select a tax rate to map exempt sales (either the Customer is tax exempt or the Product is tax exempt). Taxes of type ‘Exempt' are retrieved from Xero for selection.
Export Sales Select a tax rate to map sales from UK to a country outside the EU.


In case you have not registered for EU VAT MOSS, setup taxes for the following categories:

Category Select a tax rate from Xero
Sales Select a tax rate to map Sales tax
Taxes of type ‘OUTPUT' will be retrieved from Xero for selection.
Exempt Sales Select a tax rate to map exempt sales (either the Customer is exempt or the Product is exempt). Taxes of type ‘Exempt' will be retrieved from Xero for selection.
Export Sales Select a tax rate to map sales from UK to anywhere outside EU. Taxes of type ‘Exempt' will be retrieved from Xero for selection.
Reverse Charges When a B2B sale is made and the customer has provided a VAT Registration Number, based on reverse charge mechanism, the tax will not be applied. Select a Zero Rated Tax Rate for B2B Sales. Taxes of type ‘Zero Rated' will be retrieved from Xero for selection.
Sales to outside EU Select a tax rate to map sales from UK to a country outside the EU.

Note - For Non-MOSS registered merchants, Xero does not provide a Tax type or rate, but suggests the following work-around: For sale of physical goods from one EU Member state to another, the tax will be created of type MOSS_SALES. You can then manually update the sale amount in Box 6 and Box 8 in the VAT Return report. Read more about this approach in detail

If you are using global version of Xero
You can refer to the above steps and do tax mapping for each country as required.

Step 6: Configure Sync Rules 

You can choose to sync invoices from Chargebee to Xero from a particular date by selecting the relevant date from the drop-down.

Step 7: Run Sync 

Once the configuration is complete, click Run Initial Sync to begin the sync. Chargebee will sync the first 10 invoices, to ensure that mapping, conventions, and sync criteria align with your requirements.

You need to review these invoices in Xero. Click the Run Full Sync, if the sync works as expected.

On triggering Run Full Sync

On triggering Run Full Sync, the sync dashboard appears, where you can view or manage settings.

Enable/Disable Auto Sync

After setting up the integration, you can configure the daily schedule to automatically sync all the information to Xero. Invoices and related information will sync once every 24 hours. You can choose to disable auto-sync if required.

Sync Now

For on-demand sync, you can sync data from Chargebee to Xero immediately.

Configure Sync Rules

You can edit the configurations or use the GL Account mapping provided during setup.

Manage Record Mapping

You can add/update the mappings for the Chargebee records (Invoices, Customers, Credit notes, and Transactions.

Manage Tax Mapping

Adjust the tax mapping configured during the setup process. When you add new tax regions to Chargebee settings, update the tax mapping in this section accordingly.

Map Product Catalog

Manage and update the product catalog.


Disconnecting will unlink this integration; to reconnect, you must perform all setup steps again.

Integration setup is now complete.

Abort Sync Functionality 

The Abort Sync functionality in Chargebee enables you to halt ongoing sync jobs, providing greater control over your sync processes and configurations. When you click Abort Sync, the current batch of processed records will be completed. Subsequently, the sync job will stop, and the remaining batches will not be processed. Any records skipped in this sync will be included in the next sync batch.

For domains with auto-sync enabled, sync resumes 15 minutes after the abort action. This ensures that all records, including those halted by the abort action, are synchronized in the next sync cycle. You can monitor the status of sync jobs in the Recent Syncs table.

The Abort Sync functionality is useful when updating specific records between syncs or pausing the sync process to verify or modify records in Chargebee before syncing to NetSuite.

Sync Preferences 

After you run the sync, you can view the last sync details, errors found during sync if any. You can choose to ignore the errors, if required. Chargebee will not sync the ignored records.

Sync Now
In case you need to push data from Chargebee to Xero immediately, you can do so by clicking Sync Now option.

Auto Sync
After setting up the integration, you can click on the Enable Auto Sync option to schedule automatic sync from Chargebee. Subsequent changes in Chargebee, such as subscriptions creations or updates, payments for existing invoices, refunds etc., will be synced to Xero once, every 24 hrs. You can choose to Disable auto-sync if necessary.

Manage Mapping
You can edit the sync rules configured as part of integration setup process:

  • Edit the GL Account mapping
  • Enable or disable Offline payment sync from Xero to Chargebee
  • Edit tax mapping
  • Edit tracking categories

Manage Tax Mapping
You can modify the tax codes selected during the setup process. If you have added tax regions in your Chargebee settings, you can provide the new tax codes here.

In case you want to stop syncing data from Chargebee to Xero, you can click the Unlink option. Chargebee will stop sending data to Xero and:

  • Remove authentication details
  • Invoices already synced to Xero will not be updated
  • FOR TEST SITES: When you unlink the integration, the configuration and mapping data will be deleted and if you reconnect to the Xero organization, then the invoice mapping will not be retained.
  • FOR LIVE SITES: When you unlink, the invoice data mapping between Chargebee and Xero will remain intact. In case you connect to the same organization again, the data already synced will not be pushed to Xero. In case you want to connect to a different organization, contact support .

Offline Payment Sync (Xero to Chargebee) 

  1. Chargebee syncs all the invoices to Xero including PAYMENT DUE invoices, but the invoices that are in PENDING status are not synced to xero.
  2. The bank statement is downloaded into Xero regularly, for reconciliation.
  3. When you reconcile offline payments against payment due invoices in Xero, Xero marks the invoice as Paid.
  4. In order to update the due invoice in Chargebee, you would have to manually record a payment against the payment due invoice in Chargebee. But with the Sync Offline Payments option enabled, Chargebee will read the transaction in Xero and mark the invoice as PAID, so you need not record a payment in Chargebee manually.

The exchange rate applied in Xero is not imported into Chargebee when the offline payment is imported.

Overpayments applied to invoices in Xero will not sync back to Chargebee as part of the offline payment sync feature.
If the Invoice is $100 and the offline payment made against the invoice is $120.
The Invoice for $100 is PAID, and the Chargebee status is changed to PAID, but it won't have an excess of $20. When an excess payment is made in Xero via the offline payment method, the invoice gets updated back to Chargebee and set to PAID, but the excess $20 is not synced back to Chargebee.



Applicable only if you have Stripe gateway enabled.

You can download the payment gateway statement from here and upload it in Xero.
You can also update the clearing account if required (via Manage Mapping option)

Refer this document on Chargebee's recommended procedure to handle payment reconciliation in Xero.

Revenue Recognition 

For recognizing revenue in Xero, you can download the Revenue Recognition / Deferred Revenue Report from Chargebee. The report will provide the amount to be recognized, you can create the journal entries manually and update the Liability and Sales ledgers.


Can you connect multiple Chargebee sites to a single Xero account?

Yes, you can connect multiple Chargebee sites to a single Xero account. Additionally, if you have multiple Chargebee sites, you can connect each site to corresponding Xero accounts. Note, you cannot connect one Chargebee site to different Xero accounts or different Organizations in a Xero account.

Can I enable multiple tax regions for Chargebee - Xero integration?

Xero can report taxes in a single country and only the global edition of Xero supports multiple tax regions. We recommend users to either update to Xero's global edition or create different tax accounts and tax codes in Xero to support multiple tax regions. Click here for more information on how Xero supports tax returns in multiple regions.

How do I relink the Xero integration to the same organization it was previously connected to?
When relinking the Xero integration, ensure that you connect to the same organization it was previously associated with.

  1. Login to your Chargebee site.
  2. Go to Apps > Xero > Click RECONNECT.

If the previously connected organization appears grayed out under Connected Apps, proceed with the following steps.
Disconnecting Xero

  • Log in to your Xero account.
  • Navigate to Settings > Connected Apps.
  • Locate the Chargebee app and click Disconnect.

Reconnecting in Chargebee

Was this article helpful?