Skip to main content

QuickBooks Online

QuickBooks Online is a cloud-based accounting software designed for small to medium-sized businesses. It provides comprehensive tools for managing finances including invoicing, bill payment, expense tracking, financial reporting, inventory management, and payment processing. QuickBooks helps businesses track income and expenses, manage cash flow, and maintain accurate financial records for tax and compliance purposes.

Authentication Types​

QuickBooks Online supports 1 authentication method:

  • OAuth 2.0 - Create your own Intuit app and connect each user with their QuickBooks company.
    • Pros: Secure, per-user access, supports all QuickBooks features, production-ready, automatic token refresh
    • Cons: Requires Intuit Developer account and app creation
    • Best for: Organizations needing secure access to QuickBooks data with proper user authentication

Understanding Realm ID​

QuickBooks uses a Realm ID (also called Company ID) to identify which QuickBooks company a user is accessing. This ID is automatically captured during the OAuth authorization flow when a user connects their QuickBooks account. The Realm ID is stored with the user's credentials and used in all API requests to ensure operations are performed on the correct company.

Each QuickBooks company has a unique Realm ID, so users working with multiple companies will need to create separate connections for each company.

Setting up OAuth​

To use QuickBooks Online with Webrix, you need to create an app in the Intuit Developer Portal and configure OAuth 2.0 authentication.

1. Create an Intuit Developer Account​

  1. Go to developer.intuit.com

  2. Click Sign up (or Sign in if you already have an account)

  3. Complete the registration process with your email and password

  4. Verify your email address

2. Create a QuickBooks Online App​

  1. Log in to the Intuit Developer Portal

  2. Click the Dashboard tab in the top navigation

  3. Click Create an app (or + Create an app button)

  4. Select QuickBooks Online and Payments as the platform

  5. Enter an App name (e.g., "Webrix Integration")

  6. Select the appropriate scopes for your app:

    • Accounting: Select this for access to QuickBooks accounting data (required)
    • Payments: Select this if you need payment processing capabilities

  7. Click Create app

3. Configure OAuth Settings​

  1. In your app dashboard, go to the Development section (or Keys & OAuth tab)

  2. Under Redirect URIs, click Add URI

  3. Copy the Redirect URI from Webrix and paste it here

    tip

    You can find the Redirect URI in Webrix when configuring the QuickBooks connector under the OAuth settings. It will look like: https://your-domain.com/oauth/callback

  4. Click Save

  5. Copy your Client ID and Client Secret from the Keys section

    warning

    Keep your Client Secret secure and never share it publicly. Treat it like a password.

For testing purposes, it's recommended to create a sandbox QuickBooks company:

  1. In the Intuit Developer Portal, go to Sandbox

  2. Click Create a sandbox company

  3. Choose a company type (e.g., "Wholesale", "Retail", "Services")

  4. Wait for the sandbox company to be created (this may take a few minutes)

  5. You can use this sandbox company for testing without affecting real data

5. Configure in Webrix​

  1. In Webrix, go to Integrations → New → Built-in

  2. Select QuickBooks Online and click Use

  3. Under Authentication Type, select OAuth

  4. Paste your Client ID in the Client ID field

  5. Paste your Client Secret in the Client Secret field

  6. Click Save Changes

6. Test the Connection​

  1. After saving, click Connect to test the OAuth flow

  2. You'll be redirected to Intuit's authorization page

  3. Sign in to your QuickBooks account (or use sandbox credentials for testing)

  4. Select the company you want to connect (if you have multiple companies)

  5. Review the permissions and click Connect or Authorize

  6. You'll be redirected back to Webrix with a successful connection

The connection is now established and the Realm ID for the selected company has been stored automatically.

Production Deployment​

When you're ready to move from sandbox to production:

  1. In the Intuit Developer Portal, go to your app's Production section

  2. Complete the App Assessment questionnaire

  3. Submit your app for review (Intuit reviews apps before production access)

  4. Once approved, copy the Production Client ID and Client Secret

  5. Update your Webrix configuration with the production credentials

  6. Users will now connect to their real QuickBooks companies instead of sandbox

tip

Keep your development (sandbox) and production (live) configurations separate. Test thoroughly in sandbox before deploying to production.

Rate Limits​

QuickBooks Online API enforces rate limits to ensure platform stability:

  • 500 requests per minute per Realm ID (company)
  • 10 concurrent requests maximum per company per app
  • 40 batch requests per minute for batch operations

Best Practices:

  • Implement exponential backoff for 429 (rate limit) errors
  • Use batch operations when processing multiple records
  • Use Change Data Capture (CDC) queries instead of polling for updates
  • Cache frequently accessed data like accounts and items

Common Use Cases​

Customer Invoicing Workflow​

  1. Use List Customers to find or verify the customer exists
  2. If needed, use Create Customer to add a new customer
  3. Use List Items to get product/service IDs for invoice line items
  4. Use Create Invoice with customer ID and line items
  5. Optionally use Get Invoice PDF to download and email the invoice

Bill Payment Workflow​

  1. Use List Bills to find unpaid bills (e.g., WHERE Balance > '0')
  2. Use Get Bill to review bill details
  3. Use List Accounts to find the bank account for payment
  4. Use Create Bill Payment to record the payment

Financial Reporting​

  1. Use Get Profit and Loss Report to analyze revenue and expenses
  2. Use Get Balance Sheet Report to review assets, liabilities, and equity
  3. Use Get Cash Flow Report to understand cash movements
  4. Use Get General Ledger Report for detailed transaction audit

Expense Tracking​

  1. Use List Accounts to find expense accounts
  2. Use List Vendors to find or verify vendors
  3. Use Create Bill to record vendor expenses
  4. Use List Expenses to query and analyze spending patterns

Troubleshooting​

Redirect URI Mismatch Error​

If you see "redirect_uri_mismatch" during OAuth authorization.

Cause: The redirect URI configured in your Intuit app doesn't match the one being used in the OAuth flow.

Solution:

  1. Copy the exact Redirect URI from Webrix (including https:// and any path)
  2. Go to your Intuit app → Keys & OAuth → Redirect URIs
  3. Ensure the URI is added exactly as provided (trailing slashes matter!)
  4. Save changes and wait a few minutes for the changes to propagate
  5. Try connecting again

Invalid Realm ID Error​

API requests fail with "Invalid Realm ID" or "Unauthorized" errors.

Cause: The Realm ID stored with the credentials is incorrect or the user's access to that company has been revoked.

Solution:

  1. Disconnect and reconnect the QuickBooks integration in Webrix
  2. During reconnection, carefully select the correct company when prompted
  3. Verify that the user still has access to the QuickBooks company
  4. Check that the company subscription is active

Token Refresh Failures​

Users are repeatedly asked to reconnect or see "invalid_grant" errors.

Cause: Refresh tokens expire after 100 days of inactivity, or the app's credentials have changed.

Solution:

  1. If 100 days have passed, users must reconnect (this is a QuickBooks security requirement)
  2. Verify that the Client ID and Client Secret haven't been rotated in the Intuit Developer Portal
  3. Disconnect and reconnect the integration to obtain new tokens
  4. Ensure your app has not been deleted or disabled in the Intuit Developer Portal

Rate Limit Errors (429)​

API requests fail with HTTP 429 "Too Many Requests" errors.

Cause: Exceeded the 500 requests per minute limit or 10 concurrent requests limit.

Solution:

  1. Implement exponential backoff retry logic (wait 1s, 2s, 4s, 8s between retries)
  2. Reduce the frequency of API calls
  3. Use batch operations when creating/updating multiple records
  4. Avoid polling; use webhooks or CDC queries for detecting changes
  5. Cache data that doesn't change frequently (accounts, items, company info)

"Stale Object" Error​

Update or delete operations fail with "Stale object" error.

Cause: The SyncToken in your update request doesn't match the current version in QuickBooks. This happens when the record was modified by another process after you retrieved it.

Solution:

  1. Use Get [Entity] (e.g., Get Customer, Get Invoice) to fetch the latest SyncToken
  2. Include the current SyncToken in your update request
  3. If the error persists, the record was modified again - fetch the latest version
  4. QuickBooks uses optimistic locking to prevent concurrent update conflicts

Query Syntax Errors​

Query operations fail with "Invalid query" errors.

Cause: Using unsupported SQL syntax or filtering on non-filterable fields.

Solution:

  1. QuickBooks query syntax is limited - no OR, JOIN, or GROUP BY operations
  2. Only filterable properties can be used in WHERE clauses (check API docs for each entity)
  3. Use single quotes around string values: WHERE DisplayName = 'Acme Corp'
  4. Escape special characters with backslash: WHERE CompanyName LIKE 'O\\'Reilly'
  5. URL-encode your query string before sending
  6. Maximum 1000 results per query (use pagination for more)

Permission Denied Errors​

API calls fail with "403 Forbidden" or "Insufficient permissions" errors.

Cause: The access token doesn't have the required scope, or the user lacks permissions in QuickBooks.

Solution:

  1. Verify that you requested the correct OAuth scopes during app creation
  2. For accounting operations, ensure com.intuit.quickbooks.accounting scope is included
  3. For payment operations, ensure com.intuit.quickbooks.payment scope is included
  4. Disconnect and reconnect to request the proper scopes
  5. Verify the user has appropriate permissions in their QuickBooks company (not all users can create/modify all records)

Validation Errors When Creating Records​

Create operations fail with validation errors like "Required field missing" or "Invalid reference".

Cause: Missing required fields or referencing entities that don't exist.

Solution:

  1. Invoices: Must have CustomerRef and at least one Line item
  2. Bills: Must have VendorRef and at least one Line item with AccountRef
  3. Journal Entries: Must have at least 2 lines and debits must equal credits
  4. Items: Must have valid IncomeAccountRef for Service/NonInventory items
  5. Use List/Get tools to find valid IDs for referenced entities (customers, accounts, items, etc.)
  6. Check field requirements in API documentation for each entity type

Sandbox vs Production Data Mismatch​

Testing works in sandbox but fails in production, or vice versa.

Cause: Different data exists in sandbox vs production environments, or different API behaviors.

Solution:

  1. Sandbox companies have sample data; production companies have real data
  2. Entity IDs (customers, accounts, items) are different between sandbox and production
  3. Don't hardcode IDs - always query to find the correct entities
  4. Test thoroughly in sandbox before deploying to production
  5. Be aware that some sandbox companies have limited features compared to production

Additional Resources​

Need Help?​

If you encounter issues not covered in this guide, please contact Webrix support with:

  • The specific error message you're receiving
  • The API operation you were attempting (e.g., Create Invoice, List Customers)
  • Whether you're using sandbox or production environment
  • Your QuickBooks subscription level (if relevant)