Getting Started

Building Blocks

Subscription Features

Localization

Invoices

Credits

Billing Features

Taxes

Payment Methods

Direct Debit Payments

Configuring Gateways

Fraud Management

Hosted Pages

Attach Additional Data

Migration

Open Source Resources

Other Features

API Integration

Third Party Integrations

Xero 

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.

Prerequisites 

1. 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 Settings > Site Settings > Currencies

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.

2. 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 you want to use a Plan ID or an Addon ID that is greater than 30 characters in Chargebee, write to support@chargebee.com  with alternate Plan Ids and Addon IDs and we will help you with setting them up in the backend.

You can check the length of the ID by navigating to Product Catalog > Plans or Product Catalog > Addons

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

4. Setup your Organization Address

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

5. Setup Chart of Accounts

Ensure that you have the right accounts setup in Xero to be mapped to invoices and payments. Chargebee supports mapping data to the following accounts:

  • Invoice/ Credit Notes (to map Sales invoices, Credit notes)
  • Payments (to map payments and refunds)
  • Rounding (to map rounding corrections)
  • Bad Debts (to map write-off credit notes)
See also

Find out more about setting up your Chart of Account in Xero:

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 Settings > Third Party Integration > Click on 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 ID or Addon ID in Chargebee should not exceed 30 char (as Chargebee allows you to enter an ID upto 50 characters long but Xero does not allow anything more than 30).

    If you want to use an ID longer than 30 characters in Chargebee, send an alternate ID across to support@chargebee.com  and we will use it to help you integrate with Xero. Your data will not be altered in Chargebee.

  • 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
Invoice and Credit Map invoices to a Sales/Revenue account in Xero.

Note: If you want to map products to specific Sales Accounts, contact support@chargebee.com  and we will set it up for you offline.
Payments and 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 your Bank Account and 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.
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. If you don't have a bad debt account, you can select the Sales Account and proceed.
Note

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

  • 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

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

    • Currency exchange rate is not set in Xero. You can set a currency rate (or let Chargebee set a currency rate for you) at Settings > Currencies.
    • 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…