Turvo's Xero integration

Xero is a cloud-based accounting application that allows its users to accept business payments, manage and pay bills, and carry out payroll functions. Integrating your Turvo tenant with your Xero account, ensures any changes to your system of record will automatically reflect in the other platform.

This article covers the steps to enable the Xero integration in Turvo:

• How the integration works
• Enablement prerequisites
  • Step 1: Configure the App settings in Xero
  • Step 2: Enable the integration in Turvo
• Mapping Turvo to your Xero chart of accounts
  • Carrier costs
  • Customer costs
  • Payment types
  • Carrier payment mapping
  • Shipper ID and Carrier ID
• Tips once your integration is complete

How the integration works

With Turvo’s Xero integration, Turvo serves as the system of record for reporting carrier and customer payments. All payments are recorded in the Turvo platform and, once recorded, they sync to Xero.

Important notes:

• Any payments recorded in Xero will not sync to Turvo via the integration.
• If you do not use your Xero for 60 days, your Xero account token will expire.
• If your Xero account token expires, you will need to re-authorize your Xero account in Integration hub using your clientId and clientSecret. See the "Enabling the Xero integration" section below for instructions.

To learn how information syncs across the two platforms, when it syncs, and where you can see indicators of the integration in a shipment, see this article: Turvo’s Financial Management System integrations.

Enablement prerequisites

Before enabling Turvo’s Xero integration, your organization needs a Xero account with at least Standard User permissions to enable the integration. 

You will need to enter your Xero username and password into Turvo in the following step.

Enabling the Xero integration

Configure the App settings in Xero

1. Navigate to the Xero developer dashboard and login with your Xero credentials. Select Add new app and add the following information in the appropriate fields:
   • App Name: Turvo
   • Integration Type: Web app
   • Company or application URL: https://app.turvo.com/#/auth/login
   • Redirect URL: https://production-app.turvo.com/oauth/app
     
     
     
     
2. Confirm that you agree to the Xero Developer PlatformTerms & Conditions and then click Create App.
   
   
3. On the left pane, Select App details. The App name and Company or application URL should already be populated.
   Privacy Policy URL(optional):https://production-app.turvo.com/
   Terms and conditions URL(optional): https://production-app.turvo.com/
4. Click Save.
5. Select Configuration on the left pane and then add the following redirect URL: https://app.turvo.com/oauth/app.
   
6. Copy the Client ID and the Client secret. You will paste these into the Xero’s integration fields in Turvo’s Integration Hub in the next steps.
   Protip: See Xero’s developer documentation for more information on navigating through their developer dashboard.

Enable the integration in Turvo

1. Log into your Turvo tenant and navigate to the Admin console via the Profile icon at the top right corner of the screen.
   
   
   
   

2. In the Admin console, click the Integration hub tile.
   
   
   
   The Integration hub page opens in the Available Integrations tab.
   
   

3. Click the Xero tile.
   
   
   
   

4. If not already on the tab, click the Integrate tab.
   
   
   
   

5. Paste the Xero Client ID and Client secret from the previous step into the appropriate fields in the Connect block. Then, click CONNECT TO XERO to establish your connection.
   
   A
   
   The allow access pop-up window displays.
   

6. Click Allow access in the popup window to allow Turvo to access Xero.

Note: It may take a few minutes for the connection to complete.

Mapping Turvo to your Xero chart of accounts

After the connection between Turvo and Xero has been established, you need provide the mapping details for Carrier costs, Customer costs, Payment types, Shipper IDs, and Carrier IDs.

To enter the mapping details, click each section to expand and view the different mapping options. Some sections may require you to click the mapping option again to show the description of the field and the mapping drop-downs.

Even if you use a specific carrier/customer cost today, we suggest that you continue to map all items to the desired chart of accounts. That way, if you use a “new” cost in the future, it will map appropriately and minimize any syncing issues.

Carrier costs

The options available under Carrier costs allow you to decide how you would like your Turvo carrier costs to map to your Xero general ledger account(s).

Prior to configuring the individual mapping, you must select the Xero account you consider the default account for all Turvo costs using the Carrier account default. This will be the default account for all cost items, unless otherwise specified in the individual mapping. The account options available in the drop-down menu are automatically pulled from your Xero chart of accounts.

Note: If you don’t see a specific account in the drop-down, you need to create it within your chart of accounts in Xero first and come back to Turvo.

This drop-down will automatically populate the account for every cost item in that section regardless of the account you choose. You can also manually assign different accounts to each cost item using the individual drop-downs in the Xero account column. You can click and select the account from the drop-down menu, or start typing the name of the account and select it from the drop-down.

Note: If you choose to set a default account for each section, but need to change the mapping for individual items, you can always restore to the default account by clicking Restore default to the right of the drop-down.

Once you’ve entered all of the appropriate mapping, click SAVE PROGRESS in the bottom right corner to move onto the next section. You will not be able to move on to the next step without clicking this button.

Protip: You don’t need a 1:1 relationship with each cost item. For example, all carrier cost items, regardless of their grouping (accessorial, freight, fuel, etc), can map to all cost of goods sold (COGS).

Customer costs

The available fields in Customer costs allow you to decide how your Turvo customer costs will map to specific income account(s) in Xero.

Like with the Carrier costs section, you must choose which Xero service should be considered the default account for those cost items using the Customer account default section before configuring individual costs. The options in the available drop-downs are automatically pulled from your Xero chart of accounts.

Note: If you don’t see a specific account in the drop-down, you need to create it within your chart of accounts in Xero first and then return to Turvo.

Once you’ve entered all of the appropriate mapping, click SAVE PROGRESS in the bottom right corner to move to the next section. You will not be able to move on to the next step without clicking this button.

Payment types

In the Payment types section, you map Turvo’s payment types to your Xero chart of accounts. The Payment types section is split into Carrier payment mapping and Customer payment mapping.

Carrier payment mapping

In the Carrier payment mapping section, map Turvo’s payment types to your Xero chart of accounts.

Note: If you haven’t already, you can configure the payment terms, methods, and advances settings for your tenant through the Admin console. See our How to adjust payment terms, methods, and advances in Admin Console for more information.

Carrier payment mapping is split into the following:

• Payments
• Prepayments
• Deductions
• Holding account

The account options available in the Xero account drop-downs for Payments, Deductions, and Holding account are automatically pulled from your Asset accounts configured in Xero. Prepayments pull the bank accounts you have configured in Xero. For each section, select the appropriate account from the drop-down menu.

After you have entered all of the appropriate mapping, click SAVE PROGRESS in the bottom right corner to move to the next section.

Customer payment mapping

In the Customer payment mapping section, map Turvo’s payment types to your Xero chart of accounts. 

Customer payment mapping is split into payments.

The account options available in the Xero account drop-downs for Payments are automatically pulled from your Xero chart of accounts. Select the appropriate option from the drop-down menu and, once you’ve entered all of the appropriate mapping, click SAVE PROGRESS in the bottom right corner to move onto the next section.

Shipper ID and Carrier ID

The Shipper and Carrier ID sections allow you to map historic shipper and carrier IDs from any existing Xero data with your Turvo shipper and carrier IDs. Each section gives the option to map your Xero IDs via Turvo’s TDI, or you can import a mapping on this screen by selecting I want to import a mapping now.

Selecting I want to import a mapping now displays the Download shipper import documents link. Click the link to download the import documents.

Turvo will download two documents - one containing the Turvo ID and Turvo name of the shipper or carrier and the other contains the list of Xero IDs and names. Copy and paste the correct Xero ID into the Xero ID column of the Turvo ID and name document, then save as a .csv before uploading.

Once you’ve made your selection and uploaded the required documents, click PROCESS in the bottom right corner.

Protip: Not ready to map carrier and/or shipper IDs right now? Select I have already mapped the Xero IDs via TDI to proceed with the connection. You can update IDs in the future.

Shipper and carrier IDs can be updated in the future either by re-importing the mapping documents in Integration Hub (which is best for updating multiple IDs at the same time), or by updating the IDs individually at the account level.

To access Xero IDs at the account level, you’ll first navigate to the customer or carrier account by using the global search bar, or using Accounts > Customer or Accounts > Carrier in the left navigation bar.

Then, click the Details tab and scroll down to the Accounting section. Expanding this section will show any imported Xero IDs, and you can edit them in this section as well.

Complete setup

Once all the mappings are complete, the COMPLETE SETUP button at the bottom right corner of the page will change from grey to blue. Click COMPLETE SETUP to finish the connection.

Important note: The connection will not be successful without clicking this button.

Protip: See our Turvo’s Financial Management System integrations article for more information on what information is added or updated with the enabled integration and where to find visual proof in a shipment that indicate the FMS is working as intended.

Tips to remember after your Xero integration is complete:

• Advance payments in Xero:
  • Carrier advances in Turvo will be routed to Xero as Direct Payments.
  • Customer advances in Turvo will be routed to Xero as Bank Accounts > New Receive Money.
• In terms of configuration, Xero considers Credit Cards as Bank accounts, so there will not be a difference in integration based on the payment methods.
• When editing a carrier invoice in Turvo, the same information should be updated in the Xero bill.