Docs
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.
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.
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.
Caution!
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.
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.
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.
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.
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 support@chargebee.com.
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.
In this section, you must perform account mapping for payments, invoice line items, 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 involves assigning specific accounts or categories to each line item on an invoice.
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.
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.
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 |
Description |
Additional Info |
|---|---|---|
| PRODUCT_ID |
Unique identifier for Chargebee's item prices. |
|
| PRODUCT_NAME |
Name of the item price in Chargebee's product catalog. |
|
| SKU |
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. |
| ACC_CODE |
The accounting code associated with the item |
The Accounting code field should be filled for all the plans and addons. |
| ACCOUNTING_FIELD1 |
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_FIELD2 |
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.
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.
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.
MOSS REGISTERED
(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. |
NON-MOSS REGISTERED
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.
You can choose to sync invoices from Chargebee to Xero from a particular date by selecting the relevant date from the drop-down.
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, the sync dashboard appears, where you can view or manage settings.
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.
For on-demand sync, you can sync data from Chargebee to Xero immediately.
You can edit the configurations or use the GL Account mapping provided during setup.
You can add/update the mappings for the Chargebee records (Invoices, Customers, Credit notes, and Transactions.
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.
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.
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.
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:
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.
Unlink
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:
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.
Scenario
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.
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.
If the previously connected organization appears grayed out under Connected Apps, proceed with the following steps.
Disconnecting Xero
Reconnecting in Chargebee
