Troubleshooting
“Connect to QuickBooks” fails
Section titled ““Connect to QuickBooks” fails”- Check the mode: Development keys only work in test mode (sandbox companies) and Production keys only in live mode.
invalid_client: wrong client ID or secret, or a space around them. Copy them again from Keys and credentials in the Intuit developer portal.invalid_grantright after sign-in: the code was used twice or the redirect URI sent differs from the registered one. Start again.- Redirect URI errors on Intuit’s page: the address shown on the Connection page is not listed under Redirect URIs for the key set you use, or differs by a character (http versus https, a trailing slash).
- “The QuickBooks sign-in could not be verified”: the page was open too long or opened in another browser; start again.
- “QuickBooks did not send the company ID”: start again and choose a company on Intuit’s page.
- The Log tab shows Intuit’s answer (masked). Your server must reach
appcenter.intuit.com,oauth.platform.intuit.comandquickbooks.api.intuit.com(orsandbox-quickbooks.api.intuit.com) over HTTPS (outgoing port 443) and have a current CA bundle.
“Connect again” appears
Section titled ““Connect again” appears”The refresh token expires 100 days after its last use, or when someone disconnects the app in QuickBooks, or after a client secret change. Press Connect to QuickBooks; jobs that waited meanwhile continue by themselves.
Nothing happens after an order changes status
Section titled “Nothing happens after an order changes status”- Check Settings > General > Enable, the order status settings and the Sync orders from date.
- Check the license status bar on the add-on pages.
- Open Jobs: queued jobs wait for cron. If the counts never change, the cron job is not running; run the command from the settings page by hand once.
A job is “Waiting to retry” or “Gave up”
Section titled “A job is “Waiting to retry” or “Gave up””The last error is shown in the list. Fix the cause and press Retry. Common QuickBooks messages:
| Message | Meaning |
|---|---|
| Invalid Reference Id: ItemRef / TaxCodeRef / DepositToAccountRef | The id on the Mapping page does not exist (or is inactive) in this company. Load the lists and pick from them. |
| No QuickBooks item is mapped … | Set the default item on the Mapping page. QuickBooks needs an item on every sales line. |
| “Create items” needs an income account | Set the income account for new items on the Mapping page. |
| Duplicate Name Exists Error | A customer, vendor or employee with this name exists. The add-on retries once with the e-mail address added to the name. |
| Duplicate Document Number Error | A document with this number exists (another system, or an earlier attempt). The add-on adopts an earlier attempt of its own; otherwise change the prefix. |
| Stale Object Error | Someone changed the record in QuickBooks at the same moment; Retry. |
| No QuickBooks account is mapped for the payment method …: the refund cannot be paid out | A refund of a paid order is paid from a deposit account. Map one on the Mapping page, then Retry. |
| Business Validation Error about a period or date | QuickBooks’s closing date prevents posting; move the Sync orders from date or ask the accountant to change the closing date. |
| ThrottleExceeded / 429 | QuickBooks limits requests (500 a minute per company); the job waits as long as QuickBooks asks. |
| The lines … add up to … but the order total is … | The order contains something this version cannot book (the lines differ from the total by more than a rounding amount). Nothing was sent; contact us with the order. |
The QuickBooks total differs from the order total
Section titled “The QuickBooks total differs from the order total”Outside the United States QuickBooks calculates the tax from the tax code, so the total can differ from the order by a few cents or more when the code’s rate is not your store’s rate. The Log shows a warning with both totals. Map a tax code with the right rate, or use the United States mode only for companies with automated sales tax.
The document number is not WEB-…
Section titled “The document number is not WEB-…”QuickBooks uses the number only when Custom transaction numbers is switched on in the company’s sales settings; otherwise it numbers the document itself (the PrivateNote of the document carries the order number).
The cron address answers “Forbidden”
Section titled “The cron address answers “Forbidden””The key in the address is wrong. Copy the address again from the settings page.
Still stuck
Section titled “Still stuck”Contact us through https://cs-cart.kaviolabs.com with the add-on version, the CS-Cart version and the relevant log lines (tokens and secrets are masked automatically).