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.

Prerequisites

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 or update accounting information for plans and add-ons price points in Chargebee. There are four accounting fields required to configure the integration between Chargebee and Xero.

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

• SKU/ Product Code/ Item ID: If a product or service is already present in Xero, you can map the products by entering the Item ID or SKU in Chargebee and avoid creating duplicates. Note: When the 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: Enter the General Ledger Account code in Xero. This tells Chargebee which account to post product-related transactions to in Xero.

• Accounting Tracking Category 1, 2: You can provide additional information for tracking purposes, such as class or location. You can also set tracking categories at the customer and subscription level; contact support to set this up.

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/Add-on Price Point ID

You can create a plan or add-on 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, enter an alternative ID as the SKU. To update the ID, navigate to Product Catalog > Select a Plan/Add-on > Select a price point > Edit > Enter an alternate ID in the SKU field.

Configuration

Step 1: Connect Chargebee to Xero

• Log in 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.

• Log in 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 file 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.

Proceed becomes available after all checks are either passed or ignored. While these checks are being conducted, or in the event of failed checks, the Proceed button is 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 creates 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; in the 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 apply exclusively at the line item level.

Step 4: Map Product Catalog

Once the account mapping for payments, invoice line items, and refunds is complete, 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:

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

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

Step 5: Configure Tax Mapping

Chargebee retrieves both the default and custom tax rates 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 automatically creates tax rates in Xero.

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:

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 already created 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:

NON-MOSS REGISTERED

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

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 Run Full Sync if the sync works as expected.

On Triggering Run Full Sync

When you trigger 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 information to Xero. Invoices and related information sync once every 4 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 or 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.

Disconnect

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

Sync Preferences

After you run the sync, you can view the last sync details and any errors found during sync. 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 the Enable Auto Sync option to schedule automatic sync from Chargebee. Subsequent changes in Chargebee, such as subscription creations or updates, payments for existing invoices, refunds, etc., will be synced to Xero once every 4 hours. You can choose to Disable auto-sync if necessary.

Manage Mapping You can edit the sync rules configured as part of the 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.

Unlink If 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, the invoice mapping will not be retained.
• For live sites: When you unlink, the invoice data mapping between Chargebee and Xero will remain intact. If you connect to the same organization again, the data already synced will not be pushed to Xero. If you want to connect to a different organization, contact support.

Offline Payment Sync (Xero to Chargebee)

1. Chargebee syncs all invoices to Xero, including payment due invoices, but 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. To update the due invoice in Chargebee, you would have to manually record a payment against the payment due invoice in Chargebee. However, with the Sync Offline Payments option enabled, Chargebee will read the transaction in Xero and mark the invoice as paid, so you do not need to record a payment in Chargebee manually.

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 will not 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.

Reconciliation

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 to this document for Chargebee's recommended procedure to handle payment reconciliation in Xero.

Revenue Recognition

For recognizing revenue in Xero, you can download the Revenue Recognition or Deferred Revenue Report from Chargebee. The report provides the amount to be recognized; you can create the journal entries manually and update the liability and sales ledgers.

FAQ

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 that 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 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. Log in 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

• Log in to your Chargebee account.
• Attempt to reconnect to Xero by following the integration setup process.