Getting Started

Building Blocks

Custom Fields

Subscription Features

Localization

Invoices

Credits

Billing Features

Taxes

Payment Methods

Direct Debit Payments

Configuring Gateways

Fraud Management

Hosted Pages

Notifications

Reports and Analytics

Migration

Open Source Resources

Other Features

API Integration

Third Party Integrations

Xero 

Introduction 

The Chargebee - Xero integration links your Chargebee Site with your Xero account. This integration simplifies your organization's accounting by automatically pushing invoices, payments and related data from Chargebee to your Xero account. This reduces manual data entry, saving you time and increasing accuracy. After the integration is set-up, you will be able to:

  • Sync Invoices, Payments, Credit Notes, Refunds, Customers, Plans, Discounts, and Taxes with Xero.
  • View updated details in the ‘Accounts Receivables' report, Balance Sheet and Profit and Loss statement in Xero.
  • Match payments/invoices in your Xero account with the cash in your bank account.
  • Draw up tax liability reports and file returns to specific tax authorities (if you have a UK/NZ/AUS edition of Xero).
Note

This is a one-way sync, where data from Chargebee will be updated to Xero. Any updates made in Xero will not be synced back to Chargebee.

It is recommended that you update invoice/customer/product/payment related information in Chargebee. Your changes will reflect in Xero after the subsequent sync.

Account Summary Report 

If you are processing large number of invoices and do not prefer to sync each and every invoice to Xero, then you can utilize the Account Summary Report .
The Account Summary Report summarises all the billing transactions and provides the net values to be accounted for:

  • Invoices & Credit Notes
  • Discounts
  • Taxes
  • Bad Debts
  • Payments
  • Revenue to be recognized

You can add consolidated entries in Xero using this report. Additionally, you can refer to the revenue to be recognized for a particular month.

Prerequisites 

1. Setup your Product Catalog

Enter accounting fields for the Plans and Addons in Chargebee:

  • SKU: You can enter a product code/ SKU here and this will be used as your Item Code in Xero. If a product/ service is already present in Xero, Chargebee will map the product to the existing item in Xero and a new item will not be created.

  • Accounting Code: The Chart of Account (or General Ledger) code in Xero should be entered here

  • Accounting Tracking Category 1, 2: If Tracking category is required for Plan/ Addon, the category details can be entered here. Tracking category at customer and subscription levels is possible as well- contact support@chargebee.com  to set this up.

Note

These fields will not be available by default, you should enable these fields at Settings > Site Info > Enable Accounting Fields.

2. Ensure that the base currency in Chargebee and Xero is the same

Integration can begin only if the base currency you've chosen in Chargebee matches the base currency you've chosen in Xero.

You can view your Chargebee Site's base currency by navigating to SettingsSite SettingsCurrencies

The base currency in Xero is determined by the country or currency you selected while adding your organization in Xero.

You can also view the default currency in Xero while creating the invoice:

If you have multiple currencies enabled in your Chargebee site:

Multiple currency setups are possible in Chargebee and Xero. Make sure to address the following in your Chargebee site and your Xero Organization so that your setup is error free:

  • Base Currency: Make sure that the base currency in your Chargebee site and your Xero organization are the same.

  • Other enabled currencies: Make sure that each currency that you have enabled in your Chargebee site is also enabled in your Xero organization.

3. Verify the character length of the Plan ID or Addon ID in Chargebee

Chargebee allows you to enter a plan ID or addon ID of upto 50 characters but Xero supports only upto 30 characters. If there are plans/addons which have an ID which exceeds 30 characters, then you can enter an alternative ID in the SKU field in Plan/Addons page.

4. Check if you have invoices already synced into Xero manually

If you have already synced your invoices with Xero manually, contact support@chargebee.com . We will perform a data migration/mapping procedure to ensure that duplicate records (Customers, Plans) are not created in Xero while running the sync from Chargebee.

5. Setup your Organization Address

Ensure that you have provided your organisation address in the Chargebee Site settings. You can do this by navigating to SettingsSite SettingsOrganisation Address.

Connecting Xero with Chargebee 

If you have not already consulted your Accounting advisor, we strongly recommend that you do so before beginning the integration.

Step 1: Connect to Xero

To connect to Xero, go to SettingsThird Party Integration › Click Xero.

Once you have selected Xero, click the Connect button to link your Xero Organization to Chargebee.

Note

The base currency in Chargebee and Xero will be verified. If the base currencies are different, then you will not be allowed to proceed. The base currency in the Chargebee site and Xero organisation must match in order for the data sync to begin.

Log into your Xero account.

Select the Xero Organization to be linked and click Authorise.

Step 2: Validate prerequisite checks before you begin your integration

Once you have authorized your Xero organization, Chargebee will perform compatibility checks to ensure the invoices don't fail later when the invoice sync has been started.

The list of checks are:

  • Plan/Addon ID check: If your plan/addon ID in Chargebee exceeds 30 characters, you can enter an alternate ID in the SKU field when configuring the plan/addon. To accommodate Xero's 30 character limit on item codes, the SKU you enter in Chargebee will appear as your item code in Xero.

    If the SKU field is left blank, Chargebee will use your plan ID to create an item code in Xero.

  • Plan/Addon Accounting Code check: Make sure your plans/addons are equipped with an accounting code. This allows each of them to be mapped to individual accounts in Xero.

    You can enter the accounting code for a plan/addon by navigating to the plan/addon's configuration page (Product Catalog > Plan > Plan Name or Addon Name).

  • Currencies check: The list of currencies you have enabled in your Chargebee site should also be enabled in your Xero Organization. For instance, if USD, GBP and NZD are available in your Chargebee site, then these currencies should be available in Xero.

    When you have updated the list of currencies in Xero, you can click on Refresh option and proceed to the next step of integration.

Step 3: Configure Accounts

Once the compatibility check is passed, you can proceed to mapping your accounts across the following categories:

Select an account for each category:

Account Description
Payments & Refunds Map payment and refund transactions to a Bank account or a Payment enabled account in Xero.

Note: In case you need to map multiple Payment accounts like Bank Account, Paypal account, contact support@chargebee.com  and we will set it up for you offline.
Rounding Account Map rounding corrections to a specific Rounding Account in Xero.

In case you don't have a specific account, you can select a "Sales" option and proceed.
Bad Debt Account Select a Bad debt account to map Write-off Credit notes to Xero.

What is a Bad Debt in Chargebee?
Credit Notes created with Write Off as the reason code will be mapped to this account.

In case you don't have a specific account, you can select a "Sales" option and proceed..
Adhoc (or One Time Charges) Select an account to map Adhoc/One time charges in Xero.

In case you don't have a specific account, you can select a "Sales" option and proceed.
Plan Setup Select an account to map Plan's setup charges in Xero.

In case you don't have a specific account, you can select a "Sales" option and proceed.
Note

Find out more about how write-offs work at Chargebee.

  • Plans and addons can be mapped to individual accounts in Xero for easy accounting. This mapping is captured on the plan's specific page (Product Catalog > Plan > Plan Name)

  • During the integration process, if you want to create a new account in Xero, use the Create option.

  • If you have made any Account related changes in Xero, you can click the Refresh link to retrieve the updated list of accounts from Xero.

Step 4: Configure Taxes

Note

This step in the integration process will be available only if you have set up taxes in Chargebee.

Select a tax rate from the list of default rates created by Xero or your own tax rates and map it to the categories mentioned.

Chargebee will refer to this mapping, and when a sale happens, the taxes will be used while invoices are created in Xero.

If you are using a USA or Canada edition of Xero

Chargebee will create Tax Rates in Xero automatically since tax mapping for the USA/Canada involves a complex process and doing this manually will be a tedious process.

You can utilize the tax reports in Xero - Sales Tax Report and Sales Tax Audit Report - for calculating tax liability.

Find out more about Sales Tax Reports .

If you are using an NZ, AUS, Singapore, South Africa edition of Xero

You can select from the list of Tax Rates from Xero and map them to 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

UK country organisation in Xero supports EU VAT Returns filing from inside Xero. Hence Xero creates default Taxes to facilitate accurate VAT Liability reporting.

While configuring taxes in Chargebee, you can select from one of the default Tax rates created in Xero UK version. For a non-UK based organisation in Xero, please refer the section below .

See also

How Xero assists in VAT Return filing   for UK Merchants.
The default Tax types in Xero  .

Based on whether you have registered for MOSS or not, the selection will vary as follows:

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 Chargebee will create a Tax rate for sale to each EU member state automatically

Scenario 1: For a sale from UK to UK by a MOSS registered merchant, Chargebee will create a tax rate by name: CB_GB @20% of type: MOSS_SALES.

Scenario 2: For a sale from UK to Germany by a MOSS registered merchant, Chargebee will create a tax rate by name: CB_DE @ 19% of type: MOSS_SALES.

Tip: You can also utilise 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' will be retrieved from Xero for selection]
Export Sales Select a tax rate to map sales from UK to any other country outside the EU.

[Taxes of type ‘Exempt' will be retrieved from Xero for selection]

Non-MOSS registered

In case you have not registered for EU VAT MOSS, select the tax rates across 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 Select a Zero Rated Tax Rate for B2B Sales.

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]

Read more about Chargebee EU-VAT Reverse charge mechanism
Sales to outside EU Scenario 1: If a sale is made to a taxable region outside UK, say Spain, where the merchant has registered, Chargebee will automatically create a tax rate: CB_Spain @21% of type MOSS_SALES

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

Scenario 2: If a sale is made to a taxable region outside UK, say Greece, but the merchant has not registered in that country, Chargebee will automatically apply the source country's related Tax rate, in this case, the UK's Sales Tax rate (as selected in the ‘Sales' dropdown)
Note

If you have created tax rates in Xero already, please contact support@chargebee.com , and we will help you with the mapping offline.

See also

How Chargebee handles EU VAT

If you are using any other EU Member edition in Xero


In other EU member organisations of Xero, Tax types are not available, hence Chargebee will create the Taxes with the following naming convention (the naming convention follows the UK's style for easy reporting).

  • CB_Country @ Rate%, where, Country - will be the country considered for applying tax and Rate is the % Tax rate applied.
  • CB_Reverse Charge when a B2B sale is made from one EU member state to another EU member state
  • CB_Exempt if a sale is made to a Tax exempted Customer or if a product sold is exempt from Tax.
  • CB_Export - for sales to any other country outside the EU.

In this manner, even though types are not available, the invoices/payments in these categories can be viewed together under the naming convention followed.
Hence you can better report VAT manually as well.

If you are using any other country edition of Xero

If you are using the Global edition of Xero (for any other country other than the list of countries mentioned above, Chargebee will create the tax rates in the using the following naming convention):

  • CB_Country @ Rate%, where, Country will be the country considered for applying tax and Rate is the % Tax rate applied.
  • CB_Exempt if a sale is made to a Tax exempted Customer or if a product sold is exempt from Tax.
  • CB_Export for sales to any other country outside the source country.

Step 5: Select a Date

Select a date from which invoices generated in Chargebee should be synced to Xero.

This will be helpful if you want to sync only a specific set of invoices to Xero.

If you have previously synced invoices manually to Xero, you can select a date from which the rest of the invoices need to be synced to Xero.

Step 6: Initial Sync (10 invoices only)

Once the configuration settings are provided, you can begin with syncing first 10 invoices from the date provided.

This is to ensure the mapping, naming conventions, and the related sync settings align with your requirements.

We recommend that you take a look at the 10 invoices and related information in Xero. If it looks good, you can click on the Sync All Records option and sync the rest of your invoices records with Xero.

Step 7: Check how data reflects in Xero

After you run the sync, you can view the following details:

  • The count of invoices that were synced successfully.
  • The count of invoices that failed to sync.
  • Details of the last time the sync was run.

If there are any errors, Chargebee will provide a report of errors that occurred during the sync, with the Invoice details.

On-demand Sync:

In case you need to push data from Chargebee to Xero immediately, you can do so by clicking on the Sync Now button and the information which is not yet pushed from the last sync (say renewed invoices, new payments, update customer information and so on).

Note

Once data is pushed to Xero, we recommend not making any further edits in Xero (to details like Customer name or Item details for instance) as Chargebee maintains an internal mapping. This mapping is used to perform duplicate checks. If details are updated after data is pushed, the mapping will not be maintained anymore and duplicate records might be created in Xero at the next sync.

If you want to update details, please do so in Chargebee; the modifications will be synced to Xero in a subsequent update.

Automatic Updates

After setting up the integration, you can click on the Enable Auto Sync option to start scheduling the automatic sync from Chargebee.

Hence, subsequent updates made in Chargebee, such as when new subscriptions are created, payments are recorded for existing payment due invoices, subscriptions are renewed, customer information updated, refunds made, etc., will be identified and synced to Xero on a daily basis.

Unlink

In case you want to stop auto-syncing any data from Chargebee to Xero, you can click Unlink. Chargebee will stop sending Chargebee data to Xero.

You can Connect to Xero again later if required.

Note

You have to provide the configuration details again to unlink and re-link Xero with Chargebee

Offline Payment Sync (Xero to Chargebee) 

Chargebee syncs all invoices to Xero.

When you reconcile offline payments against payment due invoices in Xero, Xero reconciles the payment against the bank statement entry and marks the invoice as Paid automatically.

Chargebee will record this update and you need not record an offline payment in Chargebee.

Note
  • Contact support@chargebee.com  to enable this feature for your site.
  • The exchange rate applied in Xero is not imported into Chargebee when the offline payment is imported.

Limitations 

  • API Limits

    Xero supports only 1000 API hits per day per Organisation. During the sync process, if the limit is exceeded, the invoices and related records will not be pushed to Xero. When the sync runs next day, the pending records will be pushed to Xero. Read more about Xero's API limits .

  • Invoices

    If an invoice or credit note is deleted in Chargebee, it will be voided in Xero.

  • Multi-Currency

    Xero does not process invoices that are generated in a currency that does not match the bank account currency associated with the Organization or the base currency of the Organization.

  • Customers

    • Xero does not support the multiple Contacts with the same name (so John Carter cannot exist twice in Xero). On the contrary, Chargebee allows multiple customers with the same name. Such customers from Chargebee will be synced with sequential suffixes (1), (2), etc. to differentiate between the duplicates.
    • If a customer is deleted in Chargebee, the customer record will be archived in Xero.
  • Shipping Address

    Xero does not allow the Shipping Address to be captured. So shipping address in Chargebee will not be synced to Xero.

  • Plans

    If you modify the Plans or Addons in Chargebee after syncing invoices with Xero, the updates will not be synced to Xero. Updates should be made manually in Xero as well.

  • Coupons

    Chargebee supports %discounts and fixed amount discount coupons - at line item level and invoice level. But Xero supports %discounts at line item level only. Hence fixed amount discounts and invoice level discounts will be converted to %discount (at line item level) and synced with Xero.

  • Subscriptions

    You can delete a subscription in Chargebee and the corresponding invoices will be deleted as well. Currently this will not be synced to Xero. User should manually void each invoice in Xero.

  • Payments

    Payment mode details (such as payment made via Credit card/Cash/Check/ACH etc.) cannot be pushed to Xero, as Xero does not accept this at the moment. Only the gateway transaction ID or offline payment reference number will be sent to Xero.

  • Credit notes

    • Xero does not support discounts in Credit Notes, hence the discount amounts will be proportionately distributed across the Credit note line items.
    • Credit note once allocated cannot be reversed via Xero API. So if a credit note allocation is reversed in Chargebee, then user should manually de-allocate it in Xero as well.
    • In Chargebee, once a Credit Note is created, a Refund transaction will be mapped to the Credit Note (similar to a Payment transaction being mapped to an Invoice). But if the refund transaction is removed from the Credit Note, this will not be removed automatically via Xero API, this should be done manually.
Loading…