Skip to main content
All CollectionsCrunchwork IntegrationsXero
Intro to Xero and Crunchwork
Intro to Xero and Crunchwork

Start here with understanding the integration between Xero and Crunchwork

Dominique Tuck avatar
Written by Dominique Tuck
Updated over 6 months ago

Overview

Throughout this guide I’ve linked lots of external sources to assist with ancillary knowledge.

Functionality

  • Our Xero integration currently is 1 way, Crunchwork 👉🏼 Xero

  • Crunchwork Purchase orders sync with Xero purchase orders

    • You may also convert a Crunchwork purchase order into a Xero vendor bill

  • Crunchwork Invoices sync with Xero invoices

  • Crunchwork accounts will be created as new contacts in Xero if there is not a matching Xero contact

    • Accounts will be attached to invoices as Xero contacts

  • Crunchwork vendors will create as new contacts in Xero if there is not a matching Xero contact

    • Vendors will attach to purchase orders as Xero contacts

Requirements for Syncing to Xero

Below is a list of items you need to collect and discuss with Codafication before engaging a developer to set up Xero.

Turn on Xero Projects Feature

  • The Xero account that you wish to connect to must have the feature “Projects”

    • Crunchwork will create a project in Xero automatically when a Crunchwork job is created

    • Xero users should be able to run reports from Xero on project costs such as a Job WIP report and PNLs.

Xero User

  • We require access to an authenticated Xero user for the API.

  • Follow the steps in this guide on inviting Codafication to Xero.

  • We recommend creating a dedicated user for this purpose, so that we may also provide support to you.

Emails for Notifications

  • A dedicated email address for receiving error notifications and the weekly digest.

  • For more info go to the Emails section in this guide.

Set a date for Go Live

  • A cutover date is required to be set when turning the integration on. This is the date that all jobs from Crunchwork will start creating as Xero projects.

    • This will enable the ‘Sync to Xero’ buttons in invoices and purchase orders

    • This will also enable a read only ‘Xero sync status’ field on invoices, purchase orders and jobs in Pulse

Tracking Categories

  • Tracking categories are applied to each line item on invoices and purchase orders in Xero.

  • The Crunchwork integration provides tracking categories for ‘GEOGRAPHY’ and ‘JOB TYPE’. We do not offer any other tracking category.

  • Click here to understand what a tracking category is.

Contacts

  • When turning on the integration, all of your Crunchwork accounts and vendors will sync to Xero as contacts.

  • Please let Codafication know if you have Xero contacts existing already. If you do, you may want to sync Xero contacts with Crunchwork accounts and vendors beforehand, so that we can avoid creating duplicate records.

  • Please see the contacts section below for more information.

Chart of Accounts

  • Please provide to Codafication a default income code and expense code for your chart of accounts.

  • You may also set income and expense codes in the Crunchwork Catalog per line item, which will override the defaults you have provided.

  • Income codes will be applied against invoices.

  • Expense codes will be applied against purchase orders.

  • You can bulk update your Catalog using the csv import function.

Interactions between Xero and Crunchwork

Crunchwork Action

Xero Action

Notes

Create new Crunchwork job

Create new Xero project

The Crunchwork reference will be used on the Xero project.

Send purchase order, update status with ‘Sent’

Create purchase order under related Xero project.

Crunchwork will create a Xero contact for the purchase order using the assigned vendor if there is no match found.

Purchase order is marked ‘Sent’, click ‘Xero > Sync Vendor Bill’

Create vendor bill under related Xero project.

Crunchwork will create a Xero contact for the purchase order using the assigned vendor if there is no match found.

Send invoice, update status with ‘Sent’

Create invoice under related Xero project.

Crunchwork will create a Xero contact for the invoice using the assigned account if there is no match found.

Key Notes on syncing PO’s

  1. Sync should automatically occur when:

    1. PO reaches status of ‘Sent’

    2. PO reaches status of ‘Reconciled’

  2. When the PO sync status is ‘Synced’, we have successfully created a new Xero PO

  3. After syncing a PO to Xero the option to sync bill to Xero will be made available

    1. This will send the contents of the PO into Xero and create it as a vendor bill.

  4. Users will only use the ‘Sync’ buttons when they want to force a sync. This will be required when:

    1. A sync failed previously (due to missing contact ID, or failures to save the PO status correctly)

Getting Contacts

  • It’s recommended that you setup contacts before connecting Xero to Crunchwork, as the integration will create contacts from Crunchwork in Xero, resulting in potential duplications.

  • Xero allows you to utilize their API to get contact information. All you need to do is click on this link https://api-explorer.xero.com/accounting/contacts/getcontacts and follow the below steps:

  1. Click on the link https://api-explorer.xero.com/accounting/contacts/getcontacts

  2. Login to Xero. After logging in, the page should update to the 'get contacts' page.

  3. Click on the blue 'Make Request' button.

  4. Wait.

  5. Xero may time out a couple of times, just keep clicking 'wait'

  6. A section a tthe bottom should appear, and it will look like code.

  7. Click on the 'copy' icon in the top right corner of the page

I made a video for you here: https://www.loom.com/share/63b38577695040f3b0f814e7cc076d1f with steps at the bottom on how to use it.

Emails for Notifications

When deploying the Xero integration, we request two email addresses for the following email reports.

Weekly Digest

The weekly digest is sent every Sunday at 2am UTC. The email contains a report of Xero Invoices & Bills that are missing project association.

Error report

When a purchase order or invoice fails to sync to Xero, an email will be triggered to this given email address with a list of errors. The errors will provide some guidance on the reason for failure.

You can use the same email address for both if you like.

Takeaways for setting up Xero

  • The provided Xero account must have the ‘projects’ feature.

  • It’s important to match Xero contacts with Crunchwork contacts before turning on the integration, to avoid duplicate records.

  • You must set a ‘cutover date’ for when you’d like to start syncing with Xero, which will also avoid creating duplicate records.

  • You will need to provide access to Codafication to your Xero account with a dedicated API user

FAQs and Troubleshooting

Can the Xero integration update Crunchwork purchase orders and invoices when they are paid?

Not right now.

Is there an API limit for the Xero integration?

Yes, there is a daily limit, however, most accounts do not reach this limit.

Can I have different tracking categories?

Crunchwork only offers job type and geography at this point in time.

Did this answer your question?