Settings
Open Add-ons > Manage add-ons > QuickBooks Online Sync > Settings.
General
Section titled “General”| Setting | Default | Description |
|---|---|---|
| Enable | On | When off, no new work is started. Jobs already queued are still processed. |
| Marketplace owner mode | On | Multi-Vendor only. On: every order is booked in the marketplace owner’s company. Off: each vendor connects their own. |
| Debug log | Off | Also stores every HTTP call with masked request and response. Tokens and secrets are never stored. |
| Log retention (days) | 90 | Older log entries are removed by the cron run. |
| Book the invoice when the order status becomes | P (Processed) | The customer and the invoice are created in QuickBooks at this status. - books nothing automatically. In sales receipt mode the receipt is booked at the payment status instead. |
| Record the payment when the order status becomes | P | The payment is recorded against the invoice and deposited to the mapped account. In sales receipt mode this status books the sales receipt. - records no payments. |
| Book a refund when the order status becomes | I (Canceled) | Refund of the whole order, see Usage. - for none. |
| Document in QuickBooks | Invoice and payment | Or Sales receipt (paid orders): one sales receipt at the payment status instead of invoice plus payment. |
| Document number prefix | WEB- | The QuickBooks document number is the prefix plus the order number (WEB-1042), up to 21 characters. QuickBooks uses it only when Custom transaction numbers is on in the company settings; otherwise QuickBooks numbers the document itself. |
| Days until the invoice is due | 0 | Due date = order date plus this many days. Invoices only. |
| Sync orders from | empty | YYYY-MM-DD. Orders placed before are never sent. Use the first day of your financial year. |
| Create QuickBooks items from product codes | Off | Lines use an item named after the product code; missing items are created as service items with the income account of the Mapping page. Off: every product line uses the default item. |
Connection
Section titled “Connection”Credentials are not ordinary settings: they are entered on the Connection page and stored encrypted (AES-256-GCM, key derived from your store’s own secret). The client secret is never shown again; leave the field empty to keep the saved value. Access and refresh tokens are stored encrypted too.
| Field | Description |
|---|---|
| Mode | Test and Live each have their own Intuit app keys and their own connection. Test talks to sandbox-quickbooks.api.intuit.com (sandbox companies), Live to quickbooks.api.intuit.com. |
| Client ID / Client secret | From Keys and credentials of your app in the Intuit developer portal. |
| Redirect URI | Shown for you to register in the app; it must match exactly. |
| Connect to QuickBooks | Starts the authorization (scope com.intuit.quickbooks.accounting). |
| QuickBooks company | The company (realm id) orders are booked to: the one you chose on Intuit’s consent page. |
Mapping
Section titled “Mapping”Open Orders > QuickBooks sync > Mapping. Values are QuickBooks ids; the lists loaded from QuickBooks appear as suggestions while you type (the list shows the name, the field takes the id).
| Field | Description |
|---|---|
| Default item (product lines) | Required. The service or product item that product lines, rounding and surcharges are booked to: every QuickBooks sales line needs an item. |
| Shipping item, Order discount item | Items for the shipping line and for the order discount line (a negative line). Empty = the default item. |
| Income account for new items | Used when Create items creates an item. |
| Default deposit account | Account a payment is deposited to. Empty = QuickBooks Undeposited Funds. Refunds are paid back from this account, so a refund of a paid order needs one. |
| Deposit account per payment method | One id per active payment method of your store. |
| Tax code for taxed lines, for lines without tax, for shipping | QuickBooks tax code ids. United States companies with automated sales tax use TAX and NON. |
| Tax code per CS-Cart tax | One entry per tax of your store. |
How tax is handled depends on the company’s country (read when you test the connection):
- United States (automated sales tax): lines carry
TAXorNONand the tax amount of the CS-Cart order is sent as the total tax, so the QuickBooks total equals the order total; a difference of a few cents becomes a “Rounding” line. Prices that include tax are sent net of tax. - Other countries: lines carry the tax code id and the document is sent tax-inclusive or tax-exclusive like your store prices. QuickBooks calculates the tax from the code’s rate, so use codes whose rates match your store. If QuickBooks ends up with another total, a warning is written to the log.
The queue runs from cron. Use either the command line or the secret web address shown in the Cron section of the settings:
php /path/to/store/admin.php --dispatch=kv_quickbooks.cronhttps://your-store.example/index.php?dispatch=kv_quickbooks.cron&key=<secret>
Log and jobs
Section titled “Log and jobs”- Log lists every call, job and connection event with filters (level, action, text, dates) and a CSV export.
- Jobs lists the queue. A job that fails is retried after 5 minutes, 15 minutes, 1 hour, 3 hours and 12 hours, then marked “Gave up”; use Retry to queue it again. When QuickBooks answers “too many requests” (limit: 500 requests a minute per company) the job waits for the time QuickBooks names. While the connection needs you (expired or revoked), jobs wait six hours at a time so nothing is lost.
Multi-Vendor
Section titled “Multi-Vendor”In the vendor panel a vendor sees only their own records. With the marketplace owner mode off the vendor also gets the Connection and Mapping tabs for their own account.