QuickBooks Sync Workflow and Troubleshooting

Use this guide for the current QuickBooks Online workflow in Parcel Pilot.

What the QuickBooks integration does

The current QuickBooks Online integration is accounting-led.

It currently supports:

• OAuth connect, callback, disconnect, and connection testing
• invoice preview and invoice export
• configurable automatic invoice triggers
• optional standalone QuickBooks payment sync against an existing invoice mapping
• shared-customer or per-order customer targeting
• bundle-aware invoice behavior
• accounting catalog review and catalog pull preview/apply workflows

It is not currently an inventory-master integration.

Connecting QuickBooks

Go to Accounting Integrations and create or open a QuickBooks Online integration.

Verified current setup fields and actions include:

• Accounting Platform = QuickBooks Online
• Realm ID (Company ID)
• Redirect URL
• Connect to QuickBooks
• Disconnect
• Test connection

Current audited setup behavior:

• Parcel Pilot can use global QuickBooks app credentials for sandbox or production
• a specific integration can also override those credentials with custom Intuit app credentials
• Realm ID (Company ID) is normally filled by OAuth and becomes effectively read-only after connection
• Disconnect revokes the remote token when possible, then clears the local OAuth tokens

What is synchronised today

Current outbound sync

The audited QuickBooks workflow is mainly outbound accounting sync.

Current live capabilities include:

• invoice preview
• invoice export
• optional payment export after an invoice exists
• catalog review / pull workflows for accounting item mapping

What is not treated as live inventory sync

The current implementation does not treat QuickBooks as the stock master.

QuickBooks QtyOnHand can be shown as read-only accounting metadata, but it does not update Parcel Pilot inventory tables.

When an order is synchronised

The current Sync Settings include:

• Invoice sync trigger
• Virtual order trigger

Verified trigger options are:

• Manual only
• On order import
• On fulfilled/dispatched

Current audited behavior:

• physical orders can auto-queue QuickBooks invoice export on import or at the safe fulfilled boundary, depending on the configured trigger
• virtual orders have their own trigger setting
• manual sync is also available from the order edit screen for eligible admin users

Manual sync versus automatic sync

Manual sync

Current admin order actions include:

• a manual QuickBooks invoice sync action
• a manual QuickBooks payment sync action when a connected QuickBooks integration exists

Manual sync is useful when:

• the order was intentionally set to manual
• a prerequisite was fixed after the original event
• you want to retry after a failed run that did not create a mapping

Automatic sync

Automatic invoice sync depends on the integration settings and the order type.

Current verified examples:

• an eligible physical order can queue on order creation when the trigger is On order import
• a fully fulfilled physical order can queue on the fulfilment boundary when the trigger is On fulfilled/dispatched
• a partial fulfilment does not queue the fulfilled-path export

Customer matching and creation

The current QuickBooks workflow supports two main customer strategies.

Customer Sync Mode

Verified current setting label:

• Customer Sync Mode

Verified current options:

• Individual customers
• Single accounting customer

In practice:

• Single accounting customer uses the configured shared QuickBooks customer target
• Individual customers uses the order/customer context and the current customer-sync logic

If a required customer prerequisite is missing, the preview and sync-run context can block export before the invoice is created.

Products, items, and mappings

QuickBooks invoice export depends on accounting item mapping.

Current verified behavior:

• Parcel Pilot includes accounting catalog review tools
• operators can preview or apply catalog pull behavior from the integration page
• QuickBooks catalog review rows can be linked, ignored, ignored forever, or restored

This is accounting mapping behavior. It does not make QuickBooks the warehouse stock master.

Invoice versus Sales Receipt behavior

This area needs careful wording.

Current implementation:

• Parcel Pilot's live QuickBooks execution path creates invoices
• the preview and policy layers can recommend Sales Receipt for some paid cash-sale scenarios
• that recommendation does not currently switch the live export path away from invoice creation

Treat Sales Receipt as a current policy recommendation or future-capability signal, not as the normal live execution path unless you have confirmed a later implementation change.

Paid versus unpaid handling

Current paid-order behavior is split into two parts.

Document policy

Paid orders can influence the document-policy preview and may trigger a future-facing Sales Receipt recommendation.

Payment sync

Current payment sync is a separate QuickBooks payment workflow.

It only proceeds when the audited prerequisites exist, including:

• payment sync is enabled on the integration
• an invoice mapping already exists
• a QuickBooks deposit account is configured
• a QuickBooks payment method is configured or resolved
• a QuickBooks customer ID is resolved
• the order has a positive payment amount and payment date

Bundle and component accounting behavior

Current QuickBooks bundle settings are live and configurable.

Verified current setting labels include:

• Bundle invoice line mode
• Bundle component value mode

Current behavior:

• Parent line only keeps the bundle parent as the invoice line
• Expand to component lines expands the invoice into mapped component items
• component value allocation can use first-component, proportional-cost, equal-split, or weighted-component logic

These settings affect QuickBooks accounting lines only. They do not change warehouse quantities or Parcel Pilot inventory behavior.

Duplicate prevention and idempotency

Current sync behavior includes duplicate protection.

• existing invoice mappings block duplicate invoice export
• pending or in-flight sync runs can block repeat queueing
• sync runs keep an idempotency key and retry numbering
• payment sync also blocks unsafe retry cases, for example when a previous successful payment exists but the local payment mapping is missing

Do not try to force a rerun by manually deleting mappings unless you fully understand the accounting consequences.

Common sync failures

Connect or Test connection is unavailable

Check whether the integration has valid OAuth configuration for the selected environment.

Invoice sync did not queue automatically

Check:

• the integration is Enabled
• the trigger matches the order type and event
• the order actually reached the configured fulfilment or import boundary
• the order is not blocked by a prerequisite such as an existing invoice mapping

Payment sync did not run

Check:

• payment sync is enabled
• an invoice mapping already exists
• deposit account and payment method are configured
• the order has a resolvable customer, payment amount, and payment date

The preview says customer review is required

The order is missing the customer information needed for the configured customer strategy. Fix the customer prerequisite first, then retry.

A bundle export is blocked

Check the QuickBooks item mappings for the component items and confirm the selected bundle line mode matches the accounting requirement.

A sync failed after sending to QuickBooks

Check Accounting Sync Runs for the exact run status and error context. Failed runs are recorded so you can review what happened before retrying.

How to retry or recover safely

Use this order of operations:

1. identify the failed prerequisite or run status
2. fix the missing customer, mapping, trigger, deposit account, or payment method
3. use the manual sync action for that order if the previous run did not create a conflicting mapping
4. review Accounting Sync Runs and Accounting Mappings before attempting repeated retries

What not to change directly

• Do not treat QuickBooks as the live stock master.
• Do not delete and recreate the integration just to retry a single order.
• Do not manually remove invoice or payment mappings just to bypass duplicate protection.
• Do not expect editing QuickBooks QtyOnHand metadata to change Parcel Pilot stock.

Current limitations

The audited implementation still has conservative boundaries.

• invoice creation is live, but Sales Receipt execution is not the normal live path
• refunds and credit notes are not current live workflow topics here
• closed-period detection and tax-lock detection are not current supported safeguards
• partial invoicing is not supported in the conservative capability model
• QuickBooks inventory is not used as Parcel Pilot's inventory truth

Related guides

• Accounting Integrations - Create, Edit & Delete