QuickBooks Desktop integration¶

Connect QuickBooks Desktop so Zora can push invoices straight into your accounting system and pull your existing customer list in — no more keeping two copies of the same records by hand.

Before you begin

A Conductor account with a secret key issued
QuickBooks Desktop installed, with its company file reachable by the Conductor connector
A Conductor end user provisioned for that company file
Both credentials deployed to the platform API environment — see How the connection works
billing: update to configure the provider (see Permissions)
A service item and an A/R account already set up in QuickBooks for invoices to post against

QuickBooks Desktop only

QuickBooks Desktop is the only billing provider implemented today. QuickBooks Online and Xero appear as placeholders in the codebase but aren't available.

The connection runs through Conductor, a hosted service that bridges the web platform and the QuickBooks Desktop application running on your machine or server. QuickBooks Desktop has no public cloud API of its own, which is why a bridge is required.

This page covers administrator setup. For the day-to-day customer import workflow, see Customer management. For invoicing itself, see Billing and invoicing.

How the connection works¶

graph LR
    A[Zora Platform] -->|invoice export| B[Conductor]
    B -->|QuickBooks Desktop API| C[QuickBooks Desktop]
    C -->|customer list| B
    B -->|customer import| A

Two credentials, held server-side, authorize this path:

Credential	Purpose
Conductor secret key	Authenticates the platform to Conductor
Conductor end-user ID	Identifies which QuickBooks Desktop company file to act against

Both credentials are server-side configuration

These are supplied to the API as environment configuration by whoever deploys the platform — they are not entered through the admin interface. If the connection test reports that a credential is not configured, this is a deployment task, not something you can fix from Settings. Contact your platform administrator.

Step 1: Connect the provider¶

Go to Settings, or go directly to Billing → Settings.
Find the Billing Provider panel.
Choose the action to add a provider.
Set Provider Type to QuickBooks Desktop.
Give it a Name — a label for your own reference, for example QuickBooks Desktop - Main.
Save.

The provider shows a status of Connected or Disconnected.

One provider at a time

The platform tracks a single active billing provider. Adding a new one replaces the existing configuration rather than running two in parallel.

Testing the connection¶

Choose Test Connection on the provider panel. The panel then shows:

Field	Shows
Last tested	The timestamp of the most recent test
Connection error	The failure reason, when a test fails

Run this after any credential change on the deployment side.

Step 2: Configure invoice defaults¶

A connected provider is not yet able to export invoices. Two settings must be chosen first, both under QuickBooks Configuration on the same panel:

Setting	What it does
Default Service Item	The QuickBooks service item every exported invoice line is booked against
A/R Account	The Accounts Receivable account exported invoices post to

Each field loads its options live from QuickBooks — use the refresh control beside the field to pull the current list. Save when both are set.

Until both are configured, the panel displays:

Setup required: Select a default service item and A/R account from QuickBooks to enable invoice exports.

Invoice exports attempted before this is done fail with a MISSING_SETTINGS error naming the missing field.

Choosing a service item

Every exported line uses this one item, so pick a general item such as Warehousing Services rather than something narrow. Line-level detail from Zora carries across in the line description, not in the item.

Step 3: Map customers¶

QuickBooks and Zora identify customers differently, so each Zora customer you intend to invoice needs its QuickBooks identifier recorded.

To map a customer manually:

Go to Catalog → Customers.
Edit the customer.
Enter their QuickBooks ID in the Billing System ID field.
Save.

An invoice export for an unmapped customer fails with a MISSING_BILLING_ID error naming the customer.

Import instead of mapping by hand

Customers brought in through customer import are mapped automatically. Manual mapping is for customers that already existed in Zora before the integration was connected.

Importing customers from QuickBooks¶

With the provider connected, the Customers page gains an import action that pulls your QuickBooks customer list into Zora. The platform stages the fetched records, flags likely duplicates, and lets you choose which to commit.

The full step-by-step workflow is documented in Customer management. In summary:

Preview. The platform fetches customers from QuickBooks, up to 100 per batch.
Review duplicates. Records matching an existing Zora customer are flagged, not blocked.
Select and import. You choose which staged records to create.
Review results. A summary reports what was created and what was skipped.

The preview reports three counts: total found, duplicates, and available to import.

You can also export the QuickBooks customer list to CSV from the billing provider endpoints if you want to review it outside the platform before importing.

Import history¶

Every import is recorded as a session you can revisit. From the import history you can:

List past imports with their outcomes
Open a single import to see exactly which records it staged and created
Cancel a pending import that has not yet been committed

Only pending imports can be cancelled

Cancelling applies to an import that's still pending. You can't undo an import that already completed — remove or deactivate the created customer records individually instead.

Exporting invoices¶

Once the provider is connected, the defaults are set, and the customer is mapped, you can push invoices to QuickBooks.

What gets sent:

Transaction date and due date
Invoice reference number
The A/R account from your provider settings
One line per Zora invoice line, each carrying description, quantity, and rate, booked to the default service item
The invoice memo

What comes back: the QuickBooks internal ID and reference number, stored against the Zora invoice so you can trace it.

Run exports for a single invoice or in bulk. Each invoice also carries:

Field	Shows
Export status	Whether it's been exported, and how the last attempt ended
Export history	Every attempt made against that invoice
Can-export check	Whether the invoice is currently eligible

Exports are not automatic

Generating an invoice in Zora doesn't send it to QuickBooks. Export is a deliberate action. Export on a fixed cadence, or invoices will pile up un-posted.

Monitoring the connection¶

The provider panel is the single place to check integration health. It reports:

Indicator	Meaning
Connected	Credentials valid and QuickBooks reachable at last test
Disconnected	No working connection
Last tested	When the connection was last verified
Connection error	The reason the last test failed

Test the connection after QuickBooks upgrades, company file moves, and Conductor credential rotations — none of these announce themselves in the platform until an export fails.

Permissions¶

Provider configuration is governed by the billing permission module:

Action	Required permission
View provider status, test connection, view service items and accounts	`billing: view`
Enable a provider, change settings, export invoices, run and cancel imports	`billing: update`
Disable a provider	`billing: delete`

See Roles & Permissions.

Troubleshooting¶

Problem	What to do
`CONDUCTOR_SECRET_KEY is not configured` or `CONDUCTOR_END_USER_ID is not configured`	The API deployment is missing a credential. This can't be fixed from the admin interface — contact whoever deploys the platform.
Connection test fails with an authentication error	The Conductor secret key is wrong, revoked, or expired. Have the deployment credential re-issued and redeployed, then test again.
Invoice export fails with `MISSING_SETTINGS`	The default service item, the A/R account, or both are unset. Go to Step 2 — the error message names the missing field.
Invoice export fails with `MISSING_BILLING_ID`	The customer named in the error has no Billing System ID. Map it as described in Step 3.
Export fails with `RATE_LIMITED`	QuickBooks Desktop's API rate limit was exceeded. The error carries a retry-after hint. Wait and retry — bulk exports of large batches are the usual cause, so split them.
Export fails with `BAD_REQUEST` or `QBD_ERROR_<status>`	QuickBooks rejected the request itself; the message carries the reason. Common causes: a service item or A/R account deleted or made inactive in QuickBooks after you selected it, or a customer ID that no longer exists there.
The service item or account dropdown is empty	The platform couldn't query QuickBooks. Test the connection first — an empty list is usually a connection failure, not an empty QuickBooks file.
The import button doesn't appear on the Customers page	No billing provider is connected, or your role lacks `billing: update`.
Fewer customers imported than expected	Customer queries return up to 100 records per batch. Run the import again to bring in the next batch.

Billing and invoicing — billing events, rate cards, and invoice generation
Customer management — the customer import workflow in full
Roles & Permissions — granting billing access
System Settings — where the billing provider panel lives