Hour Cap

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. The integration handles three 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.

What data does Hour Cap access?

Hour Cap reads the following from your Xero account:

  • Contacts (names only, active customers)
  • Items (product/service catalogue)
  • Tracking categories and options
  • Chart of accounts (revenue accounts only)
  • Tax rates
  • Branding themes

Hour Cap writes only one thing to your Xero account: draft invoices. It can also create new contacts in Xero when you choose to push a client that does not have a Xero contact linked. Hour Cap never modifies or deletes existing Xero data.

Getting started

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

  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.

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: When you log in, contacts, items, and tracking categories are synced in the background.
  • Webhook-driven: When a contact is created or updated in Xero, Hour Cap receives a webhook notification and syncs contacts automatically.

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, or tracking categories), the sidebar will show a warning indicator. 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 contacts (names only), items, tracking categories, chart of accounts (revenue accounts), tax rates, and branding themes. It only writes draft invoices and optionally creates new contacts. It never modifies or deletes existing data in Xero.

How often does data sync?

Data syncs automatically on each login and when Xero sends a webhook notification (for contact changes). You can also trigger a manual sync from Settings at any time.

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.