Recurly for Xero

Introduction

Recurly for Xero provides a robust integration of Recurly billing data with Xero automatically transferring customer accounts, plans, invoices, payments, and refunds to make your revenue accounting process more accurate and streamlined.

You’ll also be able to reconcile in real-time data from customer accounts, payments, and receivables. By consolidating this data in a single solution, you’ll have a more complete view of your recurring revenue and transactions.

Key Integration Criteria

• The integration will support Recurly sites in sandbox mode or production mode.
• The integration is available in the Pro and Elite plans of Recurly. It is not available with the Core plan.
• You can sync multiple Recurly sites to one Xero organisation.
• You can only connect a single Recurly site with one organisation instance; you cannot sync to multiple Xero organizations from one Recurly site.
• We recommend that you do not delete open credit balances on customer accounts within Recurly. This will cause orphaned credit notes in Xero that can never be closed.
• Due to limits that Xero has placed on their API, the integration is limited to syncing about 500 invoices per day. If you have more than 500 subscriptions renewing on a single day, please note that it may take several days for the data to be fully synced to Xero.
• Due to API limits in Xero, we do not recommend syncing very large numbers of customers (>10,000 customer records) as this data will be difficult to sync to Xero.
• Gift Card accounting information is not passed between Recurly and Xero. If you use gift cards, it will look like a normal payment from Recurly.

If you have questions about these limitations, we recommend you reach out to our team before integrating.

Integration Overview

The integration is a one-way sync between Recurly to Xero with five points of integration. Records are synced in the following sequence:

1. Recurly Items, Plans, Setup Fees, and Add-Ons with Xero Inventory Items
2. Recurly Accounts with Xero Contacts
3. Recurly Invoices with Xero. Please note, all Recurly accounts will be synced regardless of the Start Date that you select.
4. Recurly Payments with Xero Payments and Refunds
5. Recurly Credits with Xero Credit Notes

General Sync Behavior

When you set up the integration, you will specify a start date. Records created or updated on or after this date will be synced with Xero. Please note, all Recurly accounts will be synced regardless of the Start Date that you select.

We recommend that you do not use dates before 2016 for your date to begin migrating data with Xero because of limits of the Xero system to accept very large amounts of data through its API. Normally, merchants choose the beginning of a year or a quarter as the start date for the sync (2017-01-01 is by far the most popular) as this allows a clean cutoff between legacy accounting process and new accounting process through the integration.

The Recurly-Xero integration will run once per hour. Each time the sync process runs, it will attempt to sync all records which have been created or updated since the last time the sync process ran.

This integration is only a one-way sync. Records created or updated in Recurly will be synced to Xero. Once they are in Xero, records updated within Xero will not have changes synced back to Recurly.

Setting up Recurly for Xero

Recommendations

We recommend adding your Xero test configuration to a Recurly sandbox for testing prior to connecting to your Recurly Production site.

Contact our Technical Support team right away in the case of an accidental plan or add-on deletion and do not attempt to recreate using the same plan or add-on code as this will generate duplicate object errors.

Setup Video

Prerequisites

• Choose a date on which to cutover between your existing process and new process. We recommend doing this at the beginning of a year or at the beginning of a quarter. This will ensure there is no double-counting of transactions (between the old and new processes).
• Ensure that you have the same Base Currency in both Xero and Recurly.
• Ensure that you have the same currencies set up in both Xero and Recurly, as this will ensure that all objects are able to sync to Xero.

Setting up the Integration

To begin setting up the integration, navigate to Integrations > Xero.

To begin, click the Connect to Xero button. This will take you to a screen where you can log in to Xero. If you have several organizations set up in Xero, you will need to choose which one you want to sync with Recurly.

After you click Allow Access, you will be taken back to Recurly to configure the sync settings.

Sync Settings

The final step in initializing the integration is setting up sync settings. The following options are available:

• Income Account: this setting will specify the account that is credited when an invoice is sent to Xero (Accounts Receivable will be debited). We recommend that you choose a Deferred Revenue account for this option if your company needs revenue recognition.

• Payment Account: this setting will specify the account that will be debited when a payment is brought from Recurly to Xero (Accounts Receivable will be credited). We recommend that you set up a Recurly suspense account for this setting to reconcile against your bank feed at the end of each month.

• Sync Start Date: This is the date after which transactions will sync from Recurly to Xero. All accounts and plans, no matter when created, will sync from Recurly to Xero. We recommend that you do not use dates before 2016 for your date to begin migrating data with Xero because of limits of the Xero system to accept very large amounts of data through its API.

• Contact Display Name Format: This setting will specify how the Contact Name is populated in Xero. We advise that you select this setting based on the data you have in Recurly. For example, if you have duplicate customer accounts (two John Smiths) in Recurly, one of them will error in syncing to Xero. However, if they represent different companies and different Company Names, you can use Company Name to populate this field.

• Invoice Number Prefix: This will populate as the prefix in the Invoice Number field. If you use Xero for different lines of business, this will separate Recurly information from other lines of business.

• Credit Note Number Prefix: This will populate as the prefix in the Credit Note field. If you use Xero for different lines of business, this will separate Recurly information from other lines of business.

After you populate the Sync Settings, the integration will begin syncing within two hours. The below instructions contain information on the objects which will sync between Recurly and Xero.

Plans and Items

Items, plans, add-ons, and setup fees in Recurly are synced as Inventory Items in Xero. Items in Xero must have a unique Item code. All plans, add-ons, and setup fees will be synced with Xero, regardless of the sync start date that you select in setup.

When an invoice has a usage-based add-on, the usage will be tied to the Item in Xero reporting.

For your sync to work properly, Recurly plan codes, item codes, and add-on codes MUST BE UNIQUE AND DISTINCT. This is because Recurly plan codes, item codes, and add-on codes all sync to Xero as Item codes, and Xero Item codes are unique identifiers. This must be true not only within a category (i.e., DO NOT make an Add-On code for two different Plans with the code 'add_on_1'), but also across categories (i.e., DO NOT make an item with the item code 'attachment_1' and an add-on with the add-on code 'attachment_1').

Additionally, the Xero Item name and Item code fields have character limits of 50 characters and 30 characters, respectively. Any Recurly object codes that are longer than 30 characters will be truncated (i.e., two codes ending in '30_char_code_1' and '30_char_code_2' may both be truncated to end in '30_char_code'), which can lead to uniqueness errors.

As part of the setup process, you must define an account to populate on the item records within Xero. If you do not do this, the sync will not begin. This can be either an Income account or a Liability account. We recommend you choose a Liability account (e.g. Deferred Revenue).

When items are synced with Xero, they will include the default account that you set. Once the item is in Xero, you can edit the income account. This income account will be populated on any invoice line items which reference a given item.

One way that this can work well is that if you use a deferred revenue account as the default revenue account, you can use Recurly's revenue recognition solution or a spreadsheet to calculate your recognized revenue each month.

You also have the option to attribute different products to different revenue accounts, so that when invoices are integrated your accounting will hit different accounts as you like. When the plans are imported from Recurly into Xero, we need to specify one account by default. After the integration runs for the first time, you are able to specify which account you would like to be applied to which Item in Xero. You can navigate to Accounts > Inventory and then choose the item for which you would like to set the account. When invoices are synced with these items, they will be booked to the account specified in this Inventory list.

Customers

Customers will be synced from the account record type in Recurly to the customer record type in Xero.

• All Recurly accounts will be synced regardless of the Start Date that you select.
• Because Recurly syncs the email address for customers with Xero, you will have the ability to send emails to them from within Xero. We recommend that you do not use both Recurly and Xero to send automated email communications to your customers.
• Billing address will be synced
• Multiple shipping addresses will not be synced
• Account Address will not sync (only billing address associated with Payment Information)

The Recurly for Xero integration will sync the following fields from the account in Recurly to the customer record in Xero:

• Account Number (see configuration instructions in setup above)
• Contact Person (First / Last Name)
• Email Address
• Postal Address (from Billing Address in Recurly)
• Phone Number

Customer Naming

Xero enforces uniqueness on the "Contact Name" field. In Recurly's Xero setup, we give you the option to select between the following fields to use as your Account Name in Xero:

• First Name + Last Name (i.e. Jeffrey Smith)
• Account Code (unique ID in Recurly). We will also integrate this field with Account Number in Xero.
• Company Name
• Email address

When you choose one of these options on setup, we will send it to the Contact Name field on the Xero customer record.

We recommend that B2C companies use Account Code or First + Last Name, and B2B companies use Company Name for this feature.

NOTE that of these fields, only Account Code is required in Recurly. If you choose a non-required field and create an account in Recurly in which that field is not populated, the account will not be able to sync to Xero and we will display an error. For example, if you choose Email Address as your Contact Name in Xero and create an account in Recurly without an Email Address, that account will fail to create a Customer record in Xero.

Merging Customers

To control for duplicate customer accounts, Xero gives you the ability to merge accounts within its tool. This is a useful tool for ensuring good data integration.

We recommend that BEFORE integrating Recurly with Xero that you conduct an audit of your customers in Xero to ensure that there are no duplicate customer accounts. If you need to merge accounts, you can follow instructions here.

After you have integrated customer accounts from Recurly to Xero, you can still use the merge function. Here are two guidelines to follow:

• If you have a new account that was created as part of the Recurly sync and you want to merge it with an account in Xero that was manually created, we highly recommend that you merge the manually created customer INTO the automatically created customer. This will ensure that Recurly will keep the association between Recurly customer and Xero account. This means that you should edit the account NOT created by Recurly to match the account that was created by Recurly.

• If you have a significant amount of duplicate accounts in your Xero instance before integrating with Recurly, please contact our support team and we can assist you in preparing to integrate.

Resolving Duplicate Customer Errors

The most common error in Recurly for Xero is duplicate customer records. This error message normally appears as such:

📘

Duplicate Name Exists Error

The name supplied already exists. : Another customer, vendor or employee is already using this name. Please use a different name.

This error is caused by a collision with the Display Name in Xero. For example, if you match customers based on First + Last Name and there is already a customer with the First + Last Name of a new customer in Recurly, that customer will fail to sync.

To make this a real life scenario, say you have a customer named Jane Doe that has already been synced from Recurly to Xero. Jane then signs up for another account with your company and a new Jane Doe account record is created in Recurly. You would see the following error:

To resolve it, click the Resolve Error button in the upper right hand corner. The next screen will show you all similar customers in Xero. Once you select a customer to utilize in Xero, your customer account in Recurly will be linked and all related transactions will be sent to Xero using this customer record.

Invoices

Invoices within Xero will reference customer accounts and Xero items. Each invoice line item from Recurly will be synced to Xero.

The individual line items will carry the revenue treatment that is applied to the item, plan, add-on, or setup fee for that line. For example, if an invoice contains line items for a plan, setup fee, and add-on, each will get its own attribution to revenue based on the revenue account on its Item.

There will also be a link on the invoice in Xero to the invoice in Recurly.

The Recurly for Xero integration will sync the following fields from the invoice in Recurly to the invoice record in Xero:

• Customer Reference (the customer to which the invoice applies)
• A hyperlink to the invoice record in Recurly
• Invoice Date
• Due Date
• Line Item: Item Code, Description, Quantity, Unit Price, Disc %, Account, Tax Rate, Amount, Currency
• Subtotal
• Tax
• Total
• Whether or not the invoice has been paid, and how much of it has been paid. This helps to calculate Amount Due.

Taxes

We support the taxation of customers within Recurly, but not the taxation of Recurly customers using Xero functionality. The integration will send invoices and credit notes with tax information from Recurly to Xero.

When you have an invoice that has tax in Recurly, it will be synced to Xero according to the tax rate that applies to each line item. This will allow you to use native tax reporting functionality in Xero. An invoice with tax will appear as below in Recurly and Xero:

📘

Mixed-Tax Pricing

Note that we do not currently support the integration of mixed-tax invoices from Recurly to Xero. There are inherent differences between how Recurly and Xero use tax that renders us unable to use the native tax reporting capabilities in Xero.

Coupons

• Fixed-amount coupons will transfer the amount to Xero.
• Percentage-based coupons will calculate the coupon amount and transfer the amount to the line item amount on the invoice in Xero.
• Multiple Coupons on one invoice will be summed and reflected as one total on the invoice in Xero.
• A list of coupon redemption records will not be synced with Xero.
• For more information on coupons, please visit our Recurly Coupons documentation page.

The following is an example of a fixed-rate coupon applied to a Recurly invoice:

One-Time Charges and Credits

Recurly gives you the ability to create charges and credits that are not part of a subscription. Until they are invoiced, these charges or credits will not be synced to Xero. Once they are invoiced, they will sync as invoice line items.

We create a Recurly One-Time Charge inventory Item in Xero which will be mapped to your default Income Account. If you'd like the income account on one-time charges and credits to be different than your default item, you can change it on the Accounts > Inventory > Recurly One-Time Charge screen.

If you sell the one-time transaction using an item, the item will be reflected on the invoice in Xero.

Transactions

Transactions from Recurly will be mapped with the payment object within Xero. If the transaction is a payment (positive amount) it will map to the payment object, which will be associated with the invoice that the payment pays. If the transaction in Recurly is negative, it will create a payment on the corresponding credit note within Xero.

• Payments will be applied to the payment account which you specify in setup.
• Payments within Xero will reference the invoice which the transaction pays.
• Auth transactions will not be synced with Xero as these do not have financial impact.
• Refunds will be synced with the payment object in Xero and associated with a credit note to offset the accounting impact of the invoice.
• Refunds will be applied to the payment account which you specify in setup.
• Transaction number will be written to the Reference field on the transaction record.

The Recurly for Xero integration will sync the following fields from the transaction in Recurly to the transaction record in Xero:

• Payment Date
• Credit Card Reference
• Invoice number to which the payment applies
• Payment Amount
• Payment Account (based on the configuration of the integration section)

Credits

Credits in Recurly are synced with the Credit Note object in Xero.

• Account-level credits are not synced until they are invoiced
  *When you have an invoice with a credit line item, it will create an invoice record, credit note record, and payment record to associate them in Xero.
• Credits which have taxes credited will be included and will subtract from your Recurly Sales Tax account.
• Note that if you have a carryforward credit that is uninvoiced, it will sync to Xero. It is possible to delete this credit in Recurly. If you do so, the deletion will not carry over to Xero. You will need to also delete this record manually within Xero.

The Recurly for Xero integration will sync the following fields from the credit invoice in Recurly to the credit memo record in Xero:

• Customer Reference (the customer to which the invoice applies)
• A hyperlink to the invoice record in Recurly
• Invoice Date
• Due Date
• Line Item: Item Code, Description, Quantity, Unit Price, Disc %, Account, Tax Rate, Amount, Currency
• Subtotal
• Tax
• Total
• Whether or not the credit has been applied to an invoice, and how much of it has been applied.

Using Revenue Recognition with Xero

As Xero does not support revenue recognition functionality, we recommend that customers using Xero should take advantage of Recurly Revenue Recognition.

For users that use accrual-based accounting, we recommend that you set up Recurly products to sync to Xero using a deferred revenue account. At the end of each month, we recommend making a journal entry to recognize revenue.

*Note: This documentation is intended to provide best practice guidelines. Recurly is not an accounting firm, and the foregoing should not be construed as accounting advice. You should consult with an accountant before setting up any accounting policies or procedures.

Ignoring Sync Errors

Recurly provides the ability to see sync errors between Recurly and Xero. These are meant to give merchants the peace of mind that all objects are synced between systems.

However, it is not always realistic to expect that all objects will always be integrated between the two systems. There are a number of issues that can cause data to fail to sync.

Because of this, we allow merchants to ignore sync errors on the Invoice and Transaction objects. We recommend that if there is an error that is not easily resolved on Invoices or Transactions, you manually re-create the invoice or transaction in Xero and Ignore the error in Recurly.

Xero in Recurly Sandbox

Clear Test Data

Using the Clear Test Data button, available in Site Settings while in a Recurly sandbox, will remove your Xero configuration.

Enabling Production

You should always connect to a fresh Xero company when moving from sandbox to production in Recurly. We will automatically remove Xero from your integrations when you move to production.

FAQ

The following are answers to common questions about the Xero integration:

1. Do you send subscription information to Xero?

No, we only send Invoices, Credit Notes, Payments, and Refunds.

2. What are the accounting entries made by the integration?

By default:

• Invoices debit accounts receivable and credit an account that you select under "Income Account" in the integration setup.
• Payments debit Undeposited Funds and credit accounts receivable.
• Credit Notes (negative invoices) debit an account that you select under "Income Account" in the integration setup and credit Accounts Receivable.
• Refunds debit Accounts Receivable and Credit Undeposited Funds.

3. How do I manage my revenue with this integration?

While we are not accountants and cannot advise you on exactly how to handle your accounting to become compliant with GAAP or IFRS, we can suggest a process to handle revenue. We recommend that you set up the integration with a deferred revenue account. When invoices are posted to Recurly, they will transfer to Xero using this deferred revenue account. You can then use Recurly Revenue Recognition (see above) or another process to calculate the amount of deferred revenue which should be recognized each month, and prepare a journal entry. This is how most of our merchants handle rev rec in Xero. Again, this is not a hard and fast accounting rule, but a suggestion on process.

4. Am I able to alter the Income accounts on a product-by-product basis?

Yes! All items, plans, add-ons, and setup fees are transferred to Xero as non-inventory items, and by default are applied the Income account you set up in the integration setup. However, you can change these accounts on an item-by-item basis.

5. I am getting an error that foreign currency refunds are failing for an exchange rate problem?

If you have several currencies set up in Xero and Recurly, you may run into issues with refunds syncing to Xero because of a system limitation in Xero. Unfortunately, Recurly is not able to provide an exchange rate properly for these refunds automatically. We recommend that what you do in this case is manually create the refund in Xero, and Ignore the error in Recurly.

6. I use Stripe as my gateway, and I see transactions marked with a pi_ value, why is that?

Stripe's newest API version uses Payment Intents, which Recurly migrated all merchants over to March 25th, 2021 or earlier. The new PI integration updated the transaction value that maps back to a Stripe transaction using a pi value. The old charges endpoint is not their supported API version, and may be deprecated at some point. Previous transactions will still be marked with the previous ch ID in Recurly, which would be reflected in Xero.