QuickBooks Online Order-to-Invoice Sync (sandbox-verified)

Part of my eCommerce-ERP integration toolkit (spec work, own tooling, no client involved): an adapter that takes an order from a store and creates the matching invoice in QuickBooks Online.

The goal is narrow on purpose: an order becomes exactly one invoice. Not zero, not two, and never with the wrong amount.

Search before create. Each invoice carries a document number derived from the store's order ID. Before creating, the adapter looks it up. A retry after a timeout finds the existing invoice instead of issuing a second one.

Nothing half-done. Items are checked before the customer is touched, so an order with an unknown SKU is rejected without leaving an orphan customer behind.

Errors sorted by cause. A rejection on the data (bad SKU, invalid amount) goes straight to a dead-letter queue for a human. Expired credentials, rate limits and server errors are retried, because the order itself is fine.

Token rotation handled. QuickBooks replaces the refresh token on renewal. The adapter saves the new one to disk and refreshes once, even when several orders are processed in parallel.

I ran the adapter against an Intuit sandbox company. All tests against a mocked server were passing, and two real defects still showed up:

Silent currency mismatch. Without multi-currency enabled, QuickBooks accepts an invoice in another currency and quietly stores it in the company's own. An order for 20 EUR would have become an invoice for 20 USD. The adapter now reads the company's currency settings and rejects the order instead.

SKU lookup returned nothing usable. QuickBooks filters items by SKU but leaves the SKU out of the response unless the whole record is requested. The adapter found the item, could not match it back, and rejected every order. Fixed, and the mocked server now behaves like the real one.

Also confirmed live: sending the same order twice produces one invoice; document numbers over 21 characters are rejected, so long order IDs are shortened with a hash; line amounts must equal quantity times unit price, so the unit price is recalculated when a store's rounded total doesn't add up.

Verified on a US sandbox company only. Not yet tested: non-US companies (VAT handling), companies with multi-currency enabled, and refresh-token expiry over weeks. Shipping and discounts are recorded as a note, not as invoice lines.

TypeScript on Node.js, no SDK: plain HTTP against the QuickBooks Accounting API with OAuth 2.0. 43 automated tests for this adapter, plus a repeatable script that re-runs the live checks against any sandbox.