How Xero Invoice Upload and Sync Works

Source: xero_controller.rb

• Invoice upload is rate-limited by checking for existing delayed jobs — if a sync job is already queued, a new one will not be created
• The first sync after connection delays 15 minutes to allow initial contact sync to complete; subsequent syncs delay only 3 minutes
• Upload requires both a valid Xero connection AND a company email address configured — missing email silently prevents upload
• Invoice numbers follow the format WI-{prefix}{number} for invoices or WVI-{prefix}{number} for vendor invoices; branch companies get a store prefix prepended
• Rounding adjustment line uses the Xero payment type default account; if no default is set, it falls back to CASH
• Single invoice upload is blocked if the record already has a xero_id (i.e., it has already been synced) — prevents duplicate invoices in Xero
• Invoice JSON payload filters records by voided/authorised status and invoice type to ensure only appropriate records are sent

Support scenarios

• "My invoices aren't uploading to Xero" → Check three things: (1) is the Xero connection valid, (2) is a company email configured, and (3) is there already a sync job queued (rate-limiting). Also confirm the invoice is closed/finalised.
• "I'm getting duplicate invoices in Xero" → The single upload blocker only applies when xero_id is already set. If a batch sync and manual upload overlap before xero_id is written back, duplicates can occur.
• "The invoice number in Xero doesn't match Workshop" → Branch companies get a store prefix added. The format is WI-{store prefix}{number}. Check the company's store prefix setting.