How Xero Contact Sync Down Works

Source: xero_controller.rb

• Three sync modes exist: normal (sync new/changed), skip existing (only create new contacts), and check all (re-evaluate every contact)
• Sync is skipped entirely if both customer sync-down and vendor sync-down are disabled in settings
• The first-ever sync downloads ALL contacts from Xero; subsequent syncs filter by last_xero_sync_down timestamp to only pull changes
• Contact matching logic: tries ContactNumber first, then falls back to ContactID — if a contact was manually created in both systems with different identifiers, duplicates can result
• Opening balance is only imported from Xero if the customer or vendor has zero existing invoices in Workshop; once they have invoices, balance is never overwritten
• Phone numbers containing non-numeric characters (e.g. brackets, dashes, plus signs) are placed in the notes field instead of the phone field
• STREET address type takes priority over POBOX when both are present on a Xero contact
• Contacts that are neither flagged as vendor nor customer in Xero are imported as TemporaryXeroContacts for manual assignment
• After sync, the last_xero_sync_down timestamp is set to the last contact's updated timestamp plus 1 second, to avoid re-syncing the same record
• "Ignore Sync Before" button sets the sync starting point to the current time, effectively skipping all historical changes

Support scenarios

• "Xero sync created duplicate customers" → Contact matching relies on ContactNumber then ContactID. If the customer was created manually in Workshop before sync, and the Xero contact lacks a matching ContactNumber, the system creates a new record instead of linking.
• "Phone numbers from Xero aren't showing in the phone field" → Numbers with non-numeric characters (brackets, country codes, dashes) get redirected to the notes field. Clean the number format in Xero and re-sync.
• "Customer balance from Xero didn't come through" → Balance is only imported on contacts with zero existing invoices in Workshop. If any invoice exists, the balance is never overwritten to avoid double-counting.
• "Some contacts came through as Temporary Xero Contacts" → Those contacts are not flagged as customer or vendor in Xero. They need to be manually assigned a type in Workshop via the Temporary Xero Contacts screen.