QuickBooks Online Integration

Hourli.ai integrates with QuickBooks Online (QBO) to sync time entries and import records. This eliminates double data entry and keeps your books accurate.

Connecting QuickBooks

1. Go to Manage → Integrations
2. Click Connect QuickBooks Online
3. Sign in to your Intuit/QuickBooks account
4. Authorize Hourli.ai
5. You'll be redirected back and the connection status will show as Connected

Sandbox mode

If you want to test with a QuickBooks sandbox company, enable the sandbox toggle before connecting.

What Syncs Automatically

Time Entries → QuickBooks (Outbound)

New and updated time entries are pushed to QuickBooks as TimeActivity records. The sync runs every 5 minutes automatically.

Hourli.ai Field	QuickBooks Field
Date	TxnDate
Hours	Hours + Minutes
Description	Description
Billable	BillableStatus
Rate	HourlyRate
Employee/Vendor	EmployeeRef / VendorRef
Customer	CustomerRef
Service	ItemRef

External IDs required

For entities (employees, vendors), customers, and services to sync correctly, they need matching external IDs linking them to QuickBooks records. Import your records from QuickBooks to set this up automatically.

Sync Statuses

Each time entry has a sync status:

Status	Description
Pending	Queued for the next sync cycle
Synced	Successfully created/updated in QuickBooks
Failed	Sync attempt failed (up to 5 retries)

Failed Syncs

If a sync fails, it's retried automatically up to 5 times. You can also:

1. Go to the Failed Syncs page in the sidebar
2. View the error details
3. Click Retry on individual entries or select multiple for bulk retry

Common failure reasons:

• Missing external ID on customer, service, or entity
• QuickBooks entity was deleted or inactivated
• Token expired (reconnect required)

Importing Records from QuickBooks

You can import the following from QuickBooks into Hourli.ai:

Customers, Services, Employees, Vendors, Tax Codes

1. Go to the respective Manage page (e.g., Manage → Customers, or Manage → Tax Codes)
2. Click Import from QuickBooks
3. Select the records you want to import
4. Click Import

Imported records automatically get their QuickBooks external ID, so future sync works seamlessly. Customer imports also bring in the customer's billing address, which is used as the "Bill To" block on invoices. Tax code imports bring in each code's rate.

Exporting Invoices to QuickBooks

If QuickBooks is connected, you can push your invoices into QuickBooks as QuickBooks Invoices. This is a manual, on-demand export — invoices are not synced automatically.

1. Go to Invoices and click Export to QuickBooks
2. You'll see every invoice. Invoices not yet exported are pre-selected; already-exported ones are shown but not selected (each notes that re-exporting will overwrite the QuickBooks invoice).
3. Adjust the selection and click Export
4. Each invoice is processed independently, and you'll get a per-invoice result: exported, skipped, or failed (with the reason).

Exported invoices show a ✓ Exported marker in the invoices list and store a link to the QuickBooks invoice internally.

Re-exporting

Already-exported invoices are skipped by default. To push changes again, tick Allow re-exporting (override) invoices already in QuickBooks — this updates the existing QuickBooks invoice in place rather than creating a duplicate.

What's required (strict mapping)

QuickBooks requires every invoice line to reference a QuickBooks Item, so an invoice only exports when everything it touches is mapped to QuickBooks:

• The customer has a QuickBooks external ID (import or sync the customer first).
• Every line maps to an item. Time-entry lines use their service's QuickBooks item; custom lines require you to pick an item when building the invoice.
• Any tax code on the invoice is itself mapped to QuickBooks.

If something isn't mapped, that invoice fails with a specific message (e.g. "Item 'Consulting' is not linked to QuickBooks.") while the rest still export. Fix the mapping (import the missing record) and export again.

Tax is recalculated by QuickBooks

The export sends pre-tax line amounts and the line's tax code; QuickBooks computes the tax on its side. The total in QuickBooks should match, but treat QuickBooks as the source of truth for the posted tax.

Time Entries

1. Go to Import Time Entries (via Integrations)
2. Browse by month
3. Filter by customer or employee
4. Select entries to import
5. Click Import

The import view highlights mismatches: entries referencing QuickBooks entities that don't exist in Hourli.ai yet, so you can import those first.

Integration Dashboard

The Integrations page shows a sync summary:

• Synced: entries successfully in QuickBooks
• Pending: entries waiting for next sync
• Failed: entries that need attention

Use the Sync Now button to trigger an immediate sync instead of waiting for the next 5-minute cycle.

Disconnecting

To disconnect QuickBooks:

1. Go to Manage → Integrations
2. Click Disconnect

This revokes the OAuth tokens and stops all syncing. Your existing time entries and imported records are preserved.

Troubleshooting

"Token Error" or "Reconnect Required"

QuickBooks OAuth tokens expire after ~100 days if unused. If you see a token error banner:

1. Go to Manage → Integrations
2. Click Reconnect
3. Re-authorize with QuickBooks

Entries Not Syncing

Check that:

• The integration is connected and enabled
• The entity (employee/vendor) has an external ID matching a QuickBooks record
• The customer and service have matching external IDs
• The entry isn't in failed status (check Failed Syncs page)