Before You Start

This guide assumes you have administrator access to both Gusto and Xero. A basic understanding of your general ledger and payroll accounts in Xero is also helpful.

Overview

20 min
Estimated Time
Intermediate
Difficulty
Monthly
Maintenance

What You’ll Learn

  • Diagnosing common Gusto-Xero API connection errors
  • Resolving General Ledger (GL) account mapping issues
  • Preventing and fixing duplicate payroll entries
  • Best practices for ongoing payroll reconciliation

1. Preparation Steps

Before troubleshooting, ensure your Xero Chart of Accounts is ready for Gusto’s payroll data:

Required Accounts

  • Payroll Expense (Expense)
  • Payroll Liabilities (Liability)
  • Bank Account (for Gusto payouts/withdrawals)
  • Tax Payable (Liability)

Optional (but recommended)

  • Employee Benefits Expense (Expense)
  • Gusto Fees Expense (Expense)
  • Superannuation/401k Payable (Liability)

2. Understanding Your Sync Method

You have two main approaches to getting Gusto data into Xero.

This is the official integration built by Gusto and Xero.

Pros:
  • Automated data transfer.
  • Reduces manual entry errors.
  • Often provides detailed transaction data.
Cons:
  • Can be opaque when errors occur.
  • Requires precise GL mapping setup.
  • Reliance on API stability.

Method B: Manual Journal Entries

This involves manually extracting payroll reports from Gusto and entering them into Xero.

Expert Tip: We strongly recommend using the direct API integration for efficiency and accuracy. This guide focuses primarily on troubleshooting issues that arise from this automated method. If you’re currently using manual entries, consider setting up the direct integration to streamline your process.

3. Step-by-Step: Diagnosing Sync Issues

Effective troubleshooting begins with systematically identifying the problem. Here’s a high-level workflow to start your diagnosis.

The most common issues stem from mapping mismatches or API disconnections. Always check both platforms.

{
  "sync_status": "error",
  "error_code": "GL_ACCOUNT_MISSING",
  "message": "Required General Ledger account 'Payroll Expense' not found or not mapped.",
  "timestamp": "2025-10-28T14:30:00Z"
}

4. Resolving Common Errors

  1. 1

    GL Account Mapping Errors

    Ensure all Gusto payroll categories (gross pay, taxes, benefits, etc.) are correctly mapped to corresponding accounts in your Xero Chart of Accounts. Check for new payroll items in Gusto that might not yet be mapped.

  2. 2

    Duplicate Entries

    If payroll has synced multiple times, you’ll see duplicate journal entries. Identify the correct entry and void or delete the duplicates in Xero. Be cautious and always verify totals before deleting.

  3. 3

    API Connection Failures

    Check the integration status in both Gusto (Integrations > Xero) and Xero (Settings > Connected Apps). If disconnected, try reconnecting. Sometimes, simply revoking and re-establishing the connection resolves transient issues.

  4. 4

    Date Range Discrepancies

    Ensure the payroll period in Gusto aligns with the posting dates in Xero. Mismatched dates can lead to transactions not appearing in the expected period, affecting reconciliation.

Important Precaution

Always back up your Xero data before making significant changes, especially when dealing with duplicate entries or extensive account re-mapping. This provides a safety net if issues arise.

5. Verifying Your Setup

Verification Checklist

  • Post a small test payroll (if possible) or review a recent one
  • Verify all journal entries appear correctly in Xero
  • Check all payroll accounts (expenses, liabilities) are balanced
  • Reconcile Gusto bank withdrawals with Xero bank feed

Need Help?

Get Support

Having trouble with your Gusto-Xero sync? Our team specializes in payroll integrations and can provide expert assistance.

Contact Us