Xero Integration Setup

Integrating Xero with Ruddr provides numerous benefits as outlined in the Xero Integration Overview article. To install the Xero integration, simply follow the steps below. Note that you must be a Ruddr Workspace Admin to install integrations in Ruddr. Step 1: Prepare your Data Before you install the Xero integration, you should prepare your data in Xero and Ruddr, as follows:

• Client names - Your client names in Ruddr should use the exact same spelling as your contact names in Xero. If the spelling is identical, the Xero integration will automatically map Ruddr clients to Xero contact during the integration setup process. If the spelling is not identical, you will be able to manually map Ruddr clients to Xero contacts.
• Invoice items - Your Invoice Items in Ruddr can be mapped to either Xero Product / Service Types or Xero accounts. However you plan to use them, Invoice Items should use the exact same spelling as your Product/Service types or accounts in Xero. You can manage your Invoice Items in Ruddr by clicking on Settings in the main nav bar, selecting the Lookups tab, and choosing Invoice Items from the drop-down list on the right side of the screen.
• Tax rates - Your Tax Rates in Ruddr should use the exact same spelling as your custom Tax Codes in Xero. If you do not charge sales tax or do not use custom tax rates, then you do not need to configure this area. You can manage your Tax Rates in Ruddr by clicking on Settings in the main nav bar, selecting the Lookups tab, and choosing Tax Rates from the drop-down list on the right side of the screen.

Step 2: Find the Xero Integration To get to the integrations area of Ruddr, simply click on the Settings main nav bar option and then select the Integrations tab (see Integrations for more information). The Integrations tab is separated into two sections which are Active Integrations and Available Integrations. If you have not previously set up the Xero integration, it will be listed in the Available Integrations section. Simply click on the Install button at the bottom of the integration widget (Figure 1). Step 3: Connect the Integration Once you click on the Install button, if you are already logged in to Xero you will be taken to an authorization screen (Figure 2). If you aren’t logged in to Xero, you will be asked to login first. The authorization screen explains the type of information and actions that will be made available to Ruddr through the integration. If you are comfortable with providing the privileges to the Ruddr integration, ensure that your organization is selected in the dropdown provided, and simply click on the Allow access button. Step 4: Automated Mappings Once you connect the integration to Xero, Ruddr will automatically attempt to map correlated data entities as shown below (Table 1):

Ruddr Entity	Xero Entity
Clients	Contacts
Invoice Items	Product/Service or Account
Tax Rate	Tax Code

Table 1 - Entity Mapping between Ruddr and Xero In order for these items to automatically map, they must have the exact same name in both platforms. If they do not have the exact name when the integration is setup, you can manually map the items, as detailed in the next step. NOTE: If you will be mapping Invoice Items to Xero Accounts, you will need to manually provide that mapping, as detailed in Step 5 below. Step 5: Manually Map any Remaining Clients, Invoice Items, and Tax Rates If Ruddr is unable to automatically map some Clients, Invoice Items, or Tax Rates, this will be apparent in the Details column of the integration settings. In the example below (Figure 3), Ruddr has automatically mapped 2 of 12 Invoice Items, which means ten of the Invoice Items will need to be manually mapped. Note that each Ruddr client can only be mapped to one Xero contact. This is because payments that are created in Ruddr can only be applied to one Ruddr client. To manually map the remaining Invoice Items to a Xero Product/Service, simply click the Edit button on the Invoice Items row. This will open up the Invoice Item Mappings drawer (Figure 4) which will show the items that have been automatically mapped and those that need manual mapping, if any. Within this drawer, you can map Invoice Items to either Product / Service Types or to Xero Accounts. It is an either / or mapping, in that an invoice item can be mapped to either a Product / Service or to an Account. Step 6: Set the Default Xero Configuration Items Xero uses the concept of a Product/Service for each invoice line item. This allows you to group the types of products or services that you sell to customers and ensures consistent accounting treatment of those items. As part of the integration, Ruddr needs a default Product/Service configured. This default Product/Service will be used for any Ruddr Invoice Items that are not mapped to a specific Product/Service in Xero. Much like Product / Service Types, you will need to specify a default Xero account. This will be leveraged if a Ruddr invoice item is not mapped to either a Xero Product / Service or Xero account. Additionally, you need to supply a default Ruddr Invoice Item and a default Payment Account in Xero to be associated with Payments created in Ruddr. Note that you can specify the Default Xero Invoice Status that you want Ruddr to set for newly-created Xero invoices. Ruddr defaults to “Authorised” - you can select a status from any of the following:

• Authorised
• Submitted
• Draft

When invoices are saved from Ruddr to Xero, the initial status of the Xero invoice will be set according to this default invoice status. The Configuration drawer also includes the settings that control reimbursable expense syncing:

• Reimbursable Expenses Sync - When this is enabled, approved reimbursable expenses will be synced to Xero as bills. Once per hour, Ruddr will check for new approved reimbursable expenses. If a member has one or more approved reimbursable expenses, those will be added to a single bill in Xero for that member.
• Reimbursable Expenses Sync Start Date - If the reimbursable expenses sync is enabled, Ruddr will only sync reimbursable expenses with a date on or after this date. A sync start date is required when the sync is enabled.
• Default Xero Expense Account - When adding a reimbursable expense item to a bill, Ruddr will use this Xero expense account if the expense category for the item is not mapped to a specific expense account.

To set these default values in Ruddr, simply click on the Edit icon on the Configuration row of the integration settings (Figure 3) and select the desired mappings (Figure 5). Step 7: Create a Product/Service in Xero for Expenses All items that Ruddr publishes to a Xero invoice must have an Invoice Item in Ruddr that maps to a Product/Service in Xero. Since you will likely be charging clients for expenses in addition to services, you will need to create a Product/Service in Xero for those expenses. You may not think of billable expenses as either a product or a service, but proper accounting treatment of billable expenses requires them to be captured as revenue on the income statement. Given this, Ruddr needs a Product/Service created in Xero for the billable expenses income. To bring up the Product/Service screen (Figure 6) in Xero, click on the Business menu option at the top of the Xero screen and choose the Products and Services option. This will bring up a screen that will show your current Products and Services (Figure 6). It is likely that this screen will include product and services items but not expense items. To add a Product/Service for expenses, click the New Item button and uncheck the Track Inventory Item option. This will show a drawer (Figure 7) that will allow you to name the Product/Service and select the associated income account from the Xero chart of accounts. Name this new Product/Service “Expenses”, give it a Code, and select the Sell option to display the options for selecting the Sales account and Tax rate. Select the Reimbursable Expense sales account. Note that for proper gross profit calculation, billable expenses should be captured as revenue and offset with a corresponding Cost of Goods Sold (or Cost of Services Sold) account. Step 8: Set the Invoice Item for each Project Type Ruddr allows you to set an Invoice Item for each Project Type within your workspace. This allows you to group different types of revenue on your income statement in Xero. For example, if your company has consulting revenue and managed services revenue, you can associate each project type in Ruddr to one of those two Invoice Items. Then, those Invoice Items can map to a correlating Product/Service in Xero which will have an associated income account from the Xero chart of accounts. To set the Invoice Item for each Project Type, click on the Settings main nav bar option and select the Custom Data menu option (Figure 8). Select Project Types from the list of custom data in Ruddr (for more information, view the Custom Data help article). The current Invoice Item for each project type will be shown in the list (Figure 9). You can change the invoice item by clicking on the Edit button on the given row. Note that it is common to have multiple Project Types mapped to the same Invoice Item. If you only have one type of revenue (such as “Consulting”), you may choose to map all Project Types to that single Invoice Item. Step 9: Set the Invoice Item for each Expense Category Similar to how you mapped an Invoice Item to each Project Type, you can also map an Invoice Item to each Expense Category. By default, each Expense Category is mapped to the built-in “Expenses” Invoice Item in Ruddr. This is likely sufficient for most companies but if you need to break out billable expenses into separate income accounts on your income statement, you will need to map your Expense Categories in Ruddr to specific Invoice Items. To map an Expense Category to an Invoice Item, click on the Settings main nav bar option and select the Custom Data menu option (Figure 8). From this screen, select Expense Categories from the list of custom data in Ruddr. This will bring up the list of expense categories within the workspace. To edit the Invoice Item associated with a given Expense Category, simply click the edit button on the category and set the Invoice Item drop-down (Figure 10). Step 10: Map Members If you have enabled the Reimbursable Expenses Sync option within the Configuration area of the Xero integration, you should map Ruddr members to Xero contacts. This is done by clicking the Edit button on the Members row within the Xero integration in Ruddr. Ruddr will attempt to automatically map each member to a Xero contact with an exact name match. Any members that are not automatically mapped can be mapped manually within this drawer. After you initially map members to contacts when configuring the Xero integration, you will not need to manually map members in the future. Step 11: Map Expense Categories Each line item in a Xero bill must have an associated expense account. Ruddr allows you to easily map Expense Categories in Ruddr to expense accounts in Xero. This is done by clicking the Edit button on the Expense Categories row within the Xero integration in Ruddr. Any expense category that is not mapped to a specific expense account will use the Default Xero Expense Account from the Configuration drawer.

​

Need Some Help?

Properly configuring the Xero integration can seem a bit daunting, but it is vital in order to have accurate financial statements. If you are having difficulty with any of the steps above, just reach out to us at help@ruddr.io and we’ll help you get set up (at no cost).