QuickBooks Online Sync for OpenCart

Overview

QuickBooks Online Sync books the orders of your OpenCart shop in your own QuickBooks Online company. A customer places an order, the order reaches the status you chose, and a few minutes later the customer, the invoice (or sales receipt) and the payment are in QuickBooks, with your items and tax codes. A refund or a product return becomes a refund receipt or a credit memo.

What it does

• Connection. You connect your own Intuit developer app (OAuth 2.0 authorization code flow, accounting scope) and the company you pick on the Intuit consent page. Sandbox and production keys are kept side by side. Keys and tokens are stored encrypted; the refresh token (it rotates on every use) is renewed by the extension and kept alive weekly.
• Customers. Found by e-mail address or created once, updated only when the customer data changed. Guests are handled; a duplicate display name gets the e-mail address added.
• Invoices or sales receipts. Your choice in the settings. One document per order with the number prefix you set (for example WEB-1042), product lines (with options), shipping, fees and discounts, on the items you map, with a tax code on every line. Due days, optional QuickBooks items created from product SKUs.
• Payments. Recorded against the invoice and deposited to the account mapped to the payment method of the order. In sales receipt mode the receipt is booked when the order is paid.
• Refunds. A paid order gets a refund receipt (money paid back from the mapped account); an unpaid invoice gets a credit memo applied to it. A product return does the same for the returned product and quantity.
• US and non-US tax. US companies with automated sales tax get the tax amount of the OpenCart order as the total tax; companies in other countries get a tax code on every line and QuickBooks calculates the tax.
• Mapping page. Default, shipping and discount items, an income account, a deposit account per payment method, a tax code per OpenCart tax rate. Items, accounts and tax codes are loaded from your QuickBooks; US tax codes are suggested.
• Reliable. Every create call carries a requestid, so a retried job never books a document twice. Rate limits (429) wait the time QuickBooks asks for. A job queue with retries, a sync list with QuickBooks Ids, a Jobs page and a filtered log with CSV export. Secrets never reach the log.
• Events and cron only, no OCMOD, no core edits. OpenCart 4, tested on 4.1.0.4.

Limits to know

• You need your own QuickBooks Online company and an Intuit developer app (client ID and secret). Intuit decides which plans may use the API and its limits (500 requests a minute per company).
• One OpenCart store and one QuickBooks company. Orders are booked in the currency of the order; a currency other than the home currency needs multi-currency switched on in QuickBooks.
• Order level discounts (coupons, reward points) are booked as one discount line; the tax of the order comes from the order's tax totals. A product return is credited at the price the product was ordered at, without a share of an order level discount. Fees are booked without tax.
• Orders whose lines do not add up to the order total (a custom extension changed the total) are refused with the reason and not sent.
• Changes made in QuickBooks are not read back. A document that already has a payment, or is voided, is left alone by the shop.
• The extension was tested against a stand-in of the QuickBooks Online API built from Intuit's published documentation and SDK data classes, not against a live QuickBooks company. Not affiliated with Intuit.

QuickBooks is a trademark of Intuit Inc. This extension is not made, endorsed or certified by Intuit.

Installation

Requires OpenCart 4.1 (tested on 4.1.0.4), PHP 7.4 or newer with the cURL and OpenSSL extensions, and a store reachable over HTTPS (Intuit sends the browser back to your shop).

1. In the admin go to Extensions > Installer, upload kv_quickbooks.ocmod.zip and click Install.
2. Extensions > Extensions, choose "Modules", find "QuickBooks Online Sync" and click Install (the green button).
3. Click Edit. Switch the extension on and, if you have one, enter your Kavio Labs license key. Without a key the extension works for 14 days.
4. The pages are under Sales > QuickBooks: QuickBooks sync, Connection, Mapping, Log, Jobs.
5. Cron. The install registers an hourly entry in the OpenCart cron, which needs the standard OpenCart cron line on your server (shown on the settings page). For a faster sync call the secret web address from the settings page every few minutes with your host cron.

Uninstall removes the stored keys, the sync map, the job queue and the log. What was booked in QuickBooks stays in QuickBooks.

What you need from Intuit

1. Sign in to developer.intuit.com and create an app with the scope com.intuit.quickbooks.accounting.
2. Under Keys and credentials add the Redirect URI shown on the Connection page, exactly as written, for the development keys (sandbox) and for the production keys.
3. Copy the client ID and client secret. Enter them on the Connection page (sandbox or production), save, then press "Connect to QuickBooks" and pick the company. Start with a sandbox company in sandbox mode.
4. Production keys are issued by Intuit after the app questionnaire; the app stays private to your own company.

Configuration

Settings (Extensions > Modules > QuickBooks Online Sync > Edit)

Connection

Client ID and secret of your Intuit app for sandbox and for production; the mode switch picks one. After "Connect to QuickBooks" the page shows the scope that was asked for (com.intuit.quickbooks.accounting) and the company (realm id) the books are written to. To book to another company press "Connect again" and pick it.

Mapping

Press "Load items, accounts and tax codes from QuickBooks" and "Fill the tax codes suggested for my country", then check:

• The default item (required), a shipping item and a discount item. Ids of QuickBooks items; the lists give suggestions.
• An income account, only when items are created from SKUs.
• A deposit account for each payment method of your store, and a default for the others (a bank account or Undeposited Funds).
• The QuickBooks tax code for each OpenCart tax rate, a standard code, a code for lines without tax and one for shipping. US companies with automated sales tax use TAX and NON.

Usage

Daily work

Nothing to do. When an order reaches the chosen status the extension queues a job; the cron run books it. The QuickBooks sync page lists every customer, document, payment and refund with its number, currency, amount and QuickBooks Id, and links to the order.

• Sync order now. Type an order ID to queue it again (for example after fixing the mapping). Nothing is booked twice: an unchanged order is skipped, an unpaid invoice is updated, a document with a payment is left alone.
• Queue past orders. Queues the orders in the trigger statuses since the sync date that QuickBooks does not have yet.

Refunds and returns

Set an order to the refund status: a paid order gets a refund receipt, paid back from the mapped account; an unpaid order gets a credit memo applied to the invoice. For a product return give the return the chosen return status (Sales > Returns): the returned product and quantity are refunded the same way.

Jobs and log

The Jobs page shows the queue: queued, waiting to retry, done, gave up. A failed job is retried after 5 minutes, then 15 minutes, 1, 3 and 12 hours; a rate limit waits the time QuickBooks asks for; a lost authorization waits for you to connect again. "Retry" and "Remove" are on every row. The Log page has filters and a CSV export; secrets and tokens never appear in it.

QuickBooks is a trademark of Intuit Inc. This extension is not made, endorsed or certified by Intuit.

Developer notes

Identity

Events and cron

Cron: extension/kv_quickbooks/accounting/quickbooks.cron (OpenCart cron, or the secret web address). The Intuit redirect URI is the storefront route extension/kv_quickbooks/accounting/quickbooks.callback; it receives code, state and realmId. The state is kept in the database as a SHA-256 hash, single use, 15 minutes.

Structure

Client\Api is the OAuth and Accounting API client on Client\BaseClient (HTTP, Retry-After, error mapping); Sync (customer, item, invoice / sales receipt, payment, refund, return), Store (reads an OpenCart order), Accounts and Secret (keys sealed with AES-256-GCM, token refresh under a database lock), Queue, Jobs, Log, Connect (authorization flow).

Request ids (max 50 characters): kv-inv-<order>-<hash>, kv-sr-<order>-<hash>, kv-pay-<order>, kv-cm-<order>, kv-rr-<order>, kv-al-<order>, kv-cm-rt-<return>, kv-rr-rt-<return>, kv-al-rt-<return>, kv-cu-<hash>-<id>, kv-item-<hash>.

Map table entities: customer, invoice (the invoice or sales receipt), payment, credit (credit memo or refund receipt), refund (the application or the refund), item, rcredit and rrefund for returns.

Tests

php tests/unit.php (PHP 8.1 and 8.3), node tests/mock-server/server.js 11988 (stand-in of the Intuit OAuth service and Accounting API; the base URL is the setting module_kv_quickbooks_base_url, development only) and node tests/e2e.js (browser test on a dev store: OAuth with realmId, mapping, invoice + payment, retries, token refresh, refund receipt, return credit memo, sales receipt mode, non-US tax). The stand-in proves the extension against its own reading of the API, not against the real service.

API conformance (official Intuit documentation and SDKs)

Checked on 2026-11-06 against Intuit's published OAuth client (github.com/intuit/oauth-jsclient) and the data classes of the official QuickBooks V3 PHP SDK. developer.intuit.com renders only in a browser app, so limits and lifetimes come from the documentation as published at the time of writing: check them against developer.intuit.com before a release. Webhooks are not used; the extension syncs from the order events of the store.

Credit memos are applied with a zero-total Payment that links the invoice and the credit memo.

QuickBooks is a trademark of Intuit Inc. This extension is not made, endorsed or certified by Intuit.

FAQ

Does it use OCMOD?

No. Events and cron.

Does it work with OpenCart 3?

No, OpenCart 4 only.

Do I need an Intuit app?

Yes, your own. Your order data goes from your shop straight to your QuickBooks company.

Which QuickBooks plans work?

The ones that Intuit allows to use its API. Check the current rules and limits on developer.intuit.com.

Invoice or sales receipt?

Invoice mode books an invoice and then a payment against it. Sales receipt mode books one receipt when the order is paid, for shops that are paid at checkout and do not need an open invoice.

Is my company a "US company"?

The extension reads the country of the company. US companies use QuickBooks automated sales tax: the tax of the OpenCart order is sent as the total tax and the codes TAX and NON mark the lines. Other countries use tax codes; QuickBooks calculates the tax, so set the code of each rate on the Mapping page. A warning appears in the log when QuickBooks calculates a different total than the order.

Why is a payment not recorded?

Most often the invoice is missing or paid already. The Jobs page shows the message. Fix it and press Retry.

Why was an order refused ("lines add up to ... but the order total is ...")?

Something changed the order total without a matching line, for example a custom total extension. Nothing is sent so that QuickBooks never gets a wrong document; correct the order or book it by hand.

No item is mapped. Set the default item on the Mapping page (the id of a QuickBooks item) and press Retry.

The authorization is gone. QuickBooks refresh tokens expire after 100 days without use or when the user revokes the app. Press "Connect again" on the Connection page; jobs wait and run afterwards.

Multi-currency?

Documents are in the currency of the order; a currency other than the home currency of the company needs multi-currency switched on in QuickBooks.

Is it certified by Intuit?

No. QuickBooks is a trademark of Intuit Inc.; this extension is not made, endorsed or certified by Intuit.