Overview of Sync Issues
When data fails to sync between Zuper and QuickBooks Online, the issue can stem from various sources, including configuration errors, data validation issues, or QuickBooks Online API limitations. The absence of an error in sync history often indicates that the record was created or updated by the same user whose API key was used for the integration. Other scenarios include incorrect installation (e.g., incomplete OAuth) or specific errors logged in the sync history, which can be either Zuper-validated or QuickBooks Online API errors.Sources of Errors
- Zuper Entities:
- Primary Zuper Record: Missing line items or invoices not in a sync-ready status.
- Associated Zuper Object: Incorrect customer details for QuickBooks Online creation.
- Zuper App Configuration: Misconfigured settings.
- Zuper Settings: Duplicate object errors due to mismatched unique fields.
- QuickBooks Online Entities :
- Primary QuickBooks Online Record: Manual modifications in QuickBooks Online conflict with sync updates.
- Associated QuickBooks Online Record: Issues fetching tax or other linked data.
- QuickBooks Online Settings: Custom transaction numbers, class tracking, or multicurrency settings.
- QuickBooks Online Plan: Limitations, such as a lack of class tracking support.
- Combined Issues: Errors may arise from a combination of configuration and missing data, or unsupported QuickBooks Online settings.
Diagnostic Tools
- Sync Activity: Review to identify created or associated records during sync.
- QuickBooks Online Transaction Audit History: Compare with Zuper’s invoice activity to distinguish user-initiated changes from integration-driven changes.
Error Categories and Solutions
Below is a consolidated breakdown of errors, their causes, and actionable solutions, organized by category.1. Zuper-Side Errors
These errors originate from Zuper’s validation or backend processes, often related to data issues or configuration.| Error | Error Code | Cause | Solution |
|---|---|---|---|
| Customer not found or could not be created in QuickBooks Online | N/A | Invalid customer information (e.g., incorrect email format, invalid phone number). | Verify and correct the customer’s email address (e.g., user@domain.com) and phone number format in Zuper to meet QuickBooks Online’s requirements. After updating, retry the sync. |
| Unable to upload attachment - $ in QuickBooks Online | N/A | Attachment exceeds QuickBooks Online’s 20MB size limit or is in an unsupported format (e.g., PDF). | Ensure the attachment is under 20MB and in a supported format (e.g., JPEG, PNG). Compress or convert the file if needed, then retry the sync. |
| Unable to fetch tax from QuickBooks Online | N/A | There is a tax sync issue, often when QuickBooks Online is the tax master, and the relevant tax is not created in Zuper. | Verify that Zuper’s tax configuration matches QuickBooks Online’s tax settings. If QuickBooks Online is the tax master, create the corresponding tax in Zuper or update the tax mapping in the integration settings, then retry. |
| Line item not present | N/A | The invoice or quote lacks at least one line item required for syncing. There are no line items present in the Invoice. QuickBooks Online requires at least 1 line item to be part of the Invoices that are created. | Add at least one valid line item to the invoice or quote in Zuper, ensuring all required fields (e.g., description and amount) are populated. Then, retry the sync. |
| Could not create or update product | N/A | This error occurs due to a few reasons. Some of these include: 1. Failed to get Zuper product details. 2. QBO doesn’t support negative price for Inventory Item. 3. Bundle Level Pricing is not supported in QBO. Bundle is not available in QBO. 4. QBO doesn’t allow the creation of bundles via API. | 1. Please retry sync after some time. 2. Please modify the selling price for the Inventory item and retry sync. 3. Please use a roll-up Bundle in the Invoice or Estimate and retry sync. 4. Please create the Bundle in QBO so that it may be identified and used while syncing the invoice/estimate. |
| Excess Payment Detected | N/A | This usually occurs when a payment collected in a Zuper Invoice fails to sync to QuickBooks Online. It is then collected in QBO and when the reverse sync is attempted this error is thrown by Zuper as the payments exceed the invoice total. | We can ignore this error in most cases as payments will match between Zuper and QuickBooks Online. |
| Payment method not found in Zuper/QuickBooks. Add a fallback method using the default UID in Application Config. | N/A | This occurs because for payments collected in QuickBooks Online they don’t have a payment method selected or have a payment method that doesn’t exist in Zuper. | For payments being synced back from QuickBooks Online to Zuper, please add a fallback method for payments. |
2. QuickBooks Online API Errors
These errors are returned by the QuickBooks Online API, often due to validation failures or configuration mismatches.| Error | Error Code | Cause | Solution |
|---|---|---|---|
| Unsupported Operation | 500 | The QuickBooks Online plan selected in Zuper’s configuration does not match the user’s subscribed QuickBooks Online plan, or technical issues (e.g., encoding problems). | Contact Zuper support at support@zuper.co to verify and update the QuickBooks Online plan in the integration settings. Ensure the selected plan aligns with the user’s QuickBooks Online subscription. Check for encoding issues (e.g., special characters) in the data, correct them, and retry the sync. |
| Business Validation Error | 6000 | A business validation rule fails in QuickBooks Online, such as missing GST/HST rates (e.g., in Canada), agency issues, currency mismatches, or missing required fields. | Review the error message to identify the cause (e.g., missing tax rate, incorrect currency). Update the relevant field in Zuper (e.g., add a valid GST/HST rate or correct the currency) and retry the sync. |
| Invalid Email Address Format Error | 2210 | The customer email specified in Zuper is in an incorrect format (e.g., missing @ or invalid domain). | Modify the email address in Zuper to a valid format (e.g., user@domain.com). Verify other customer details, then retry the sync. |
| Invalid Reference ID Error | 2500 | A line item in a transaction has the same name as a master record (e.g., a product category) in QuickBooks Online. | Modify the line item name in Zuper to be unique and distinct from any master record names in QuickBooks Online retry the sync. |
| Stale Object Error | 5010 | The object being updated is not the latest version, often due to simultaneous edits in QuickBooks Online by the OAuth user. | Contact Zuper support at support@zuper.co to refresh the integration connection and ensure the latest object version is synced. Coordinate with the QuickBooks Online user to avoid concurrent edits, then retry. |
| Object not found | N/A | The referenced record (e.g., customer or product) in QuickBooks Online is deleted or inactive. | Check QuickBooks Online to ensure the referenced customer or product is active. Reactivate or recreate the record if necessary, then retry the sync. |
| Incorrect account type or missing account reference | N/A | The account referenced in the transaction is invalid or missing in QuickBooks Online. | Verify that the account referenced in the transaction exists in QuickBooks Online and is of the correct type (e.g., income, expense). Update the account mapping in Zuper’s integration settings and retry the sync. |
3. Duplicate Errors
These errors occur when unique constraints in QuickBooks Online are violated due to duplicate data.| Error | Error Code | Cause | Solution |
|---|---|---|---|
| Duplicate Object Error | 630 | An object in Zuper (e.g., customer, product) has properties (e.g., reference IDs) that violate QuickBooks Online’s unique constraint. | Modify the object’s properties in Zuper to ensure uniqueness (e.g., update the reference ID or name). Verify no conflicting records exist in QuickBooks Online, then retry the sync. |
| Duplicate Document Error / Duplicate Document Number Error | 6140 | The invoice number specified in Zuper is already being used in QuickBooks Online. This error occurs when the Document number (invoice or estimate no.) in the Zuper record is already present in QuickBooks Online. This may occur if the user has existing records in QuickBooks Online that were created before installing the integration and they’re using a similar series in Zuper with ID preference set to Zuper. | To avoid conflicts, specify a unique invoice number in Zuper or enable automatic numbering in QuickBooks Online settings. Please set ID preference to ‘QuickBooks’ in such cases and retry sync. Note - If this is done, the document numbers will not match between Zuper and QuickBooks Online. Then, retry the sync. |
| Duplicate Name Exists Error | 6240 | A customer’s name in Zuper already exists in QuickBooks Online with a different QuickBooks Online ID, often due to manual deletion and recreation in QuickBooks Online. | Modify the customer’s display name in Zuper to be unique or merge/rename the duplicate customer in QuickBooks Online to align with the Zuper record. Retry the sync. |
4. Other Errors
These are fallback or unlisted errors not covered by the above categories.| Error | Error Code | Cause | Solution |
|---|---|---|---|
| Unable to Fetch Customer from QuickBooks Online | N/A | Unknown issues are preventing customer data retrieval, possibly due to connectivity or permissions. | Verify the OAuth connection and API key permissions. Ensure the customer exists and is active in QuickBooks Online. If necessary, re-authenticate the integration and retry. |
| Unable to Fetch the Estimate from QuickBooks Online | N/A | Unknown issues with estimate retrieval, often due to data mismatches or QuickBooks Online access issues. | Check the estimate status in QuickBooks Online and ensure it matches Zuper’s sync requirements. Re-authenticate the integration, confirm connectivity, and retry the sync. |
| All Other Error Codes | N/A | Unknown or unlisted issues not covered by the above error codes, potentially related to connectivity, permissions, or data issues. | Contact Zuper support at support@zuper.co with the specific error code and details from the sync history. Provide relevant logs or screenshots to assist in troubleshooting. |
| Customer not present in QBO for the given id: XXXX | N/A | This error usually occurs when the customer record has synced from Zuper to QuickBooks Online but has been made inactive. Sometimes this error occurs due to connection issues when the customer record can’t be retrieved. | Please re-activate the customer in QuickBooks Online and retry sync. In case of connection issues, Please retry sync after some time. |
Best Practices to Prevent Sync Errors
- Verify Integration Setup:
- Ensure OAuth is completed correctly and the API key is valid.
- Confirm that the QuickBooks Online plan selected in the app configuration matches the user’s subscription.
- Data Validation:
- Regularly check customer details, tax settings, and line items in Zuper for accuracy.
- Avoid manual changes in QuickBooks Online that could conflict with sync updates.
- QuickBooks Online Configuration:
- Enable or disable features like custom transaction numbers, class tracking, or multicurrency as needed.
- Ensure tax settings in QuickBooks Online align with Zuper’s configuration.
- Monitor Sync Activity:
- Regularly review sync history and activity logs to identify and address issues early.
- Compare QuickBooks Online’s transaction audit history with Zuper’s invoice activity for discrepancies.
- User Coordination:
- Prevent the OAuth user from editing QuickBooks Online records during sync to avoid stale object errors.
- Unique Identifiers:
- Ensure customer names, invoice numbers, and reference IDs are unique to avoid Duplicate Object (630), Duplicate Document (6140), and Duplicate Name Exists (6240) errors.
- Use distinct names for line items to prevent Invalid Reference ID Errors (Error Code: 2500).
Additional Notes
- Multiple Causes: Sync failures may result from combined issues (e.g., missing data and incorrect settings). Address each potential cause systematically.
- Documentation: Refer to the QuickBooks Online API error codes and Zuper’s error documentation for detailed troubleshooting.
- Support: If issues persist, contact Zuper or QuickBooks Online support with specific error details from the sync history.
Diagnostic Tools
- Sync Activity: Review to identify created or associated records during sync.
- QuickBooks Online Transaction Audit History: Compare with Zuper’s invoice activity to distinguish user-initiated changes from integration-driven changes.
- Error Codes: Use the provided error codes to pinpoint the issue and apply the corresponding solution.
- Combined Issues: Some errors may result from multiple causes (e.g., incorrect plan selection and missing data). Address each issue systematically using the provided solutions.
- Escalation: For errors requiring Zuper support (e.g., Unsupported Operation, Stale Object, or unlisted error codes), provide detailed information, including the error code, sync history logs, and affected records.
- Documentation: For further details on specific error messages, refer to QuickBooks Online’s API documentation and Zuper’s error code reference.