Xero Integration Support

Everything you need to know about connecting Hour Cap with Xero for time-based invoicing.

Overview

Hour Cap integrates with Xero to let you turn tracked time into draft invoices and follow their status. The integration handles four things:

  • Push invoices to Xero: Select time entries, preview the invoice, and push it to Xero as a draft. Line items include the descriptions, hours, and rates from your time entries.
  • Sync contacts and items from Xero: Your Xero contacts and inventory items are imported into Hour Cap so you can map clients and configure line items.
  • Sync tracking categories from Xero: If you use tracking categories in Xero for reporting, you can assign them to invoice line items.
  • Sync invoice status from Xero: Drafts created through Hour Cap show when they are approved, sent, part paid, paid, deleted, or voided in Xero.

What data does Hour Cap access?

Hour Cap reads the following from your Xero account:

  • Active customer contacts (names and IDs, plus available email addresses for inbox matching)
  • Items (product/service catalogue)
  • Tracking categories and options
  • Chart of accounts (revenue accounts only)
  • Tax rates
  • Branding themes
  • Status, sent flag, and amount paid for invoices created through Hour Cap

Hour Cap creates draft invoices and can create a new contact when you choose to add one. You can also delete an invoice through Hour Cap while it is still a draft in Xero. Hour Cap does not send invoices or delete approved or paid invoices.

Getting started

The steps below, in thirty-six seconds.

Connecting your Xero account

  1. Go to Settings → Xero and click Connect to Xero.
  2. You will be redirected to Xero to authorize the connection. Sign in with your Xero credentials and approve access.
  3. If your Xero login has access to multiple organisations, you will be asked to choose which one to connect.
  4. After connecting, Hour Cap runs a first-time sync to import your contacts, items, and tracking categories.
  5. The setup wizard walks you through configuring your invoice defaults.

Setup wizard

The setup wizard has three steps:

  1. Invoice defaults: Choose your default revenue account, tax rate, branding theme, payment terms, invoice prefix, and line item grouping.
  2. Tracking categories: If you use Xero tracking categories, choose which ones to include on invoice line items.
  3. Contact mapping: Review the automatic matching between your Hour Cap clients and Xero contacts. Fix any that were not matched or were matched incorrectly.

You can change any of these settings later from Settings → Xero and Settings → Invoice Defaults.

Creating invoices

Selecting entries, choosing how line items group, and pushing the draft to Xero.
  1. Go to Invoices → Create Invoice.
  2. Select a client. Only clients with a linked Xero contact can be invoiced.
  3. Choose the time entries to include. You can filter by date range and project, or switch to retainer period or fixed budget billing mode.
  4. Preview the invoice. Line items are grouped according to your organisation's grouping setting (or you can override it per invoice).
  5. Click Create Invoice. The invoice is queued and pushed to Xero as a draft.
  6. Once pushed, the invoice appears in your Xero account as a draft. Review it in Xero and send it to your client when ready.

Time entries included in an invoice are marked as invoiced and will not appear in future invoice creation flows.

The invoices page follows status changes made in Xero, including sent and paid. You can delete a draft from this page; Hour Cap checks Xero again before deleting it. Once an invoice is no longer a draft, the Delete action is unavailable. If an invoice is deleted or voided in Xero, its associated time and fixed charges become available to invoice again.

Contact mapping

To create an invoice in Xero, each Hour Cap client needs to be linked to a Xero contact. Hour Cap handles this in three ways:

Automatic matching

When you first connect Xero, Hour Cap automatically matches your existing clients with Xero contacts by name. Exact name matches are linked automatically.

Manual linking

For clients that were not auto-matched, you can manually search for and select the correct Xero contact from the client edit page or during the setup wizard.

Creating contacts in Xero

If a client does not exist in Xero yet, you can create them directly from Hour Cap. The client name is pushed to Xero as a new contact, and the link is established automatically.

Configuration

Invoice defaults are configured in Settings → Invoice Defaults and can be overridden per invoice.

Invoice line item grouping

Controls how time entries are combined into invoice line items:

  • By time entry: Each time entry becomes its own line item with its full description.
  • By project: All time entries for a project are combined into a single line item with the total hours.
  • By date: Time entries are grouped by date, with one line item per day.
  • By team member: Time entries are grouped by the person who tracked them.

Tracking categories

If you use tracking categories in Xero (e.g. departments, cost centres, regions), you can assign a default tracking option to invoice line items. This is configured during the setup wizard and can be changed in settings.

Other settings

  • Revenue account: The Xero account code used for invoice line items (e.g. "Sales" or "Consulting Revenue").
  • Tax rate: The default tax type applied to line items.
  • Branding theme: The Xero branding theme applied to invoices, controlling their visual appearance.
  • Payment terms: The number of days until the invoice is due (1 to 365).
  • Invoice prefix: A custom prefix for invoice reference numbers (e.g. "INV-").

Syncing data

Automatic sync

Hour Cap automatically syncs your Xero data in several ways:

  • On login and daily: Contacts, items, tracking categories, and open invoice statuses are synced in the background.
  • On the invoices page: At most once every five minutes per organisation, Hour Cap tries to refresh open invoice statuses before showing the page. The Xero API call has a three-second timeout. If it times out, the access token needs refreshing, or more than 100 invoices need checking, the refresh runs in the background instead.
  • Webhook-driven: Xero contact changes trigger contact sync. When invoice events are enabled for the Xero app, changes to an invoice created through Hour Cap trigger a status refresh for that invoice.

Invoice statuses are retrieved in batches. Paid invoices are left out of routine checks; a later invoice event can still refresh one if a payment is reversed.

Manual refresh

You can manually trigger a sync from Settings → Xero using the refresh buttons for contacts, items, and tracking categories.

Troubleshooting

Connection shows "Needs reconnect"

This means Hour Cap's access to your Xero account has been revoked or expired. This can happen if:

  • You or another user disconnected Hour Cap from within Xero's Connected Apps settings.
  • The OAuth tokens expired and could not be refreshed.

To fix this, go to Settings → Xero and click Connect to Xero to re-authorize. Your existing client-to-contact mappings and invoice settings will be preserved.

Sync failures

If a sync fails (contacts, items, tracking categories, or invoices), the connection will show a warning. Common causes:

  • Temporary Xero API outage. Try refreshing manually from Settings.
  • Authorization issue. Reconnect your Xero account.

Invoice push failures

If an invoice fails to push to Xero, it will show a "Failed" status with an error message. Common causes:

  • The linked Xero contact was archived or deleted in Xero. Update the client's contact mapping.
  • The revenue account or tax rate is no longer valid in Xero. Update your invoice defaults in Settings.
  • Xero API rate limit reached. The system retries automatically up to 3 times with exponential backoff.

Frequently asked questions

How do I disconnect Xero?

Go to Settings → Xero and click Disconnect from Xero. This revokes the OAuth token, removes the connection record, clears all client-to-contact mappings, removes Xero item and tracking references from projects, and deletes synced tracking categories. Your time entries, clients, projects, and invoices in Hour Cap are not affected. You can reconnect at any time, but you will need to re-map your clients.

What data does Hour Cap access?

Hour Cap accesses customer contacts (including available email addresses for inbox matching), items, tracking categories, chart of accounts (revenue accounts), tax rates, branding themes, and the status of invoices created through Hour Cap. It creates draft invoices and optional new contacts, and deletes a draft invoice only when you request it. See Xero Privacy & Data Security for the fields and retention details.

How often does data sync?

Contacts, items, tracking categories, and open invoice statuses sync on login and daily. Opening the invoices page can refresh invoice statuses once every five minutes per organisation. Contact webhooks and enabled invoice webhooks trigger targeted updates. Paid invoices are excluded from routine checks.

Can multiple team members use the integration?

Yes. One team member connects the Xero account, and it is shared across your organisation. All team members can track time. Managers, administrators, and the owner can create and push invoices to Xero. Role-based access controls who can manage the Xero connection and invoice settings.

What happens if I disconnect and reconnect?

Disconnecting revokes and removes OAuth tokens, clears all Xero-specific references from your clients and projects, and deletes synced tracking categories. When you reconnect, your contacts are synced again and you go through the setup wizard to re-configure defaults and re-map clients. Your time entries, projects, and historical invoices in Hour Cap are not affected.

I need more help

If you are experiencing an issue not covered here, please contact us at [email protected] and we will be happy to help.