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. It must be set in General Settings before connecting. The Realm ID is included in every API request URL 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 integrations for each company.

Where to find your Realm ID​

Sandbox (Development):

  1. Log in to the Intuit Developer Portal
  2. Click My Hub → Sandboxes
  3. The Realm ID is shown in the Company ID column next to your sandbox company

Production: The Realm ID (Company ID) is visible in the URL when you are logged in to QuickBooks Online — it appears as a numeric value in the URL path, for example: https://app.qbo.intuit.com/app/homepage — the Realm ID can also be found via Settings → Account and Settings → Billing & Subscription or by inspecting the URL of any QuickBooks page (look for /company/REALM_ID/).

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 My Hub menu in the top right

  3. Click App dashboard

  4. On the App tab, click the + button

  5. Enter the App name (e.g., "Webrix MCP 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 Done (bottom right)

  8. On the pop-up shown, review the details and click Confirm

  9. Enable the Show credentials toggle

  10. 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.

  1. Click on Open app

3. Configure OAuth Settings​

  1. In your app dashboard, go to the Settings section

  2. Under Redirect URIs tab, 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 Auth settings. It will look like: https://your-domain.com/oauth/callback

  4. Click Save

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

  1. In the Intuit Developer Portal, Click the My Hub menu in the top right

  2. Click Sandboxes

  3. Click Add

  4. Select the QuickBooks Online SKU

  5. Click Create

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

  7. 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. Under Scopes, click Add and select the permissions your integration needs:

    • com.intuit.quickbooks.accounting — required for all accounting data access
    • com.intuit.quickbooks.payment — required for payment processing
    • openid, profile, email — recommended for user identity

    Minimum required: com.intuit.quickbooks.accounting

  7. Under General Settings, set the API Base URL based on the credentials you copied from the Intuit Developer Portal:

    • If your Client ID/Secret came from the Development tab → https://sandbox-quickbooks.api.intuit.com
    • If your Client ID/Secret came from the Production tab → https://quickbooks.api.intuit.com
    How to tell which environment you're using

    In the Intuit Developer Portal, open your app (My hub → App dashboard → click the app's tile) and go to Keys and credentials. You'll see two tabs: Development and Production. Use the URL that matches the tab you copied your credentials from.

  8. Under General Settings, set the Realm ID (Company ID):

    • For sandbox: find it in the Intuit Developer Portal under My Hub → Sandboxes (the value in the Company ID column)
    • For production: find it in the QuickBooks URL when logged in (the numeric value in the URL path)

    See the Understanding Realm ID section above for detailed instructions.

  9. 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

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 — requires pay_type ("Check" or "CreditCard"), the bank account ID, and line_items linking the bill IDs (each line item needs Amount and a LinkedTxn array with TxnId and TxnType: "Bill")

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

Purchase Order Workflow​

  1. Use List Vendors to find the vendor ID
  2. Use List Accounts to find an Accounts Payable account ID (AccountType = 'Accounts Payable')
  3. Use List Items to find inventory or non-inventory items — they must have an ExpenseAccountRef configured (service items without an expense account cannot be used on POs)
  4. Use Create Purchase Order with the vendor ID, AP account ID, and line items

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 configured in General Settings is incorrect or does not match the company the OAuth token was granted for.

Solution:

  1. In Webrix, go to the QuickBooks integration → General Settings and verify the Realm ID (Company ID) value
  2. Find your correct Realm ID following the Understanding Realm ID instructions above
  3. Update the Realm ID in General Settings and click Save Changes
  4. Verify that the user still has access to the QuickBooks company
  5. 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. Purchase Orders: Require ap_account_id (an Accounts Payable account — use List Accounts filtered by AccountType = 'Accounts Payable'). Line items must reference items that have an ExpenseAccountRef configured; inventory and non-inventory items typically qualify, but pure service items (with no expense account) will cause a "Select an account for this transaction" validation error.
  6. Use List/Get tools to find valid IDs for referenced entities (customers, accounts, items, etc.)
  7. 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)