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 should use the exact same spelling as your Product/Service types 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).
Figure 1 - Click Install to Begin the Xero Integration in Ruddr
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.
Figure 2 - Authorize Xero and Ruddr Connection / 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 |
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.
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.
Figure 3 - View the Status of Your Entity Mappings between Ruddr and Xero
To manually map the remaining two 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.
Figure 4 - Manage the Ruddr / Xero Mappings for a Specific Entity
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.
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.
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).
Figure 5 - Set the Configuration Default Value for Product/Service as part of the Ruddr and Xero Integration
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.
Figure 6 - Products and Services in Xero
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.
Figure 7 - Create a Product/Service for Expenses in Xero
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.
Figure 8 - Custom Data in the Settings Area
Figure 9 - Managing Project Types and Associating to Invoice Items
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).
Figure 10 - Associate an Invoice Item with a Ruddr Expense Category
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).