QuickBooks Setup

Create a QuickBooks app in the Intuit Developer Portal for accounting integration.

Setup Steps

1. Create an Intuit Developer Account

   Sign up at the Intuit Developer Portal if you don’t have one.

2. Create a New App

   Click “Create an app” and select the QuickBooks Online and Payments platform. Choose your app type.

3. Configure App Settings

   In your app’s Keys & OAuth section, enable the Accounting scope for full functionality.

4. Add Redirect URI

   Add the redirect URI in both Sandbox and Production environments:

   https://api.switchboard.fpdigital.ai/oauth/quickbooks/callback

5. Get Sandbox Credentials

   Copy the Client ID and Client Secret from the “Keys & credentials” tab. Start with Sandbox credentials for testing.

   Caution

   Use Sandbox credentials during development. Production credentials require app review by Intuit.

6. Create Sandbox Company

   In the Sandbox section, create a test company with sample data for development and testing.

7. Switch to Production (When Ready)

   After testing, submit your app for review to get Production credentials. Update your environment variables accordingly.

Environment Variables

npx wrangler secret put QUICKBOOKS_CLIENT_ID
npx wrangler secret put QUICKBOOKS_CLIENT_SECRET
npx wrangler secret put QUICKBOOKS_SANDBOX  # Set to "true" for sandbox

Variable	Description
QUICKBOOKS_CLIENT_ID	Client ID from Intuit Developer Portal
QUICKBOOKS_CLIENT_SECRET	Client Secret from Intuit Developer Portal
QUICKBOOKS_SANDBOX	Set to “true” for sandbox environment, omit for production

Redirect URI

https://api.switchboard.fpdigital.ai/oauth/quickbooks/callback

Organization Token Sharing

Note

Important: QuickBooks enforces one token per app per company. When one team member connects, the connection is automatically shared with all organization members. The dashboard shows a “Shared” badge with who connected it.

Organization members cannot disconnect the shared connection - only the person who connected or an admin can manage it.

Important Notes

• Sandbox and Production use different credentials and companies
• Access tokens expire after 1 hour
• Refresh tokens expire after 100 days
• Production apps require Intuit review for public distribution

Common Issues

One Token Per Company

QuickBooks enforces one OAuth token per app per company. If another user in your org connects, the previous connection is replaced. Use the org-level shared connection feature.

• Sandbox vs Production confusion: Make sure QUICKBOOKS_SANDBOX is set correctly. Sandbox uses different API endpoints and data.
• Refresh token expired: QuickBooks refresh tokens expire after 100 days. If expired, the user must re-authorize from the dashboard.
• Currency formatting: QuickBooks returns amounts as strings (e.g., “1234.56”), not numbers. The AI handles conversion automatically.
• Realm ID: The QuickBooks Company ID (Realm ID) is captured during OAuth and stored automatically.

Testing

1. Create a Sandbox company in the Intuit Developer Portal (comes with sample data)
2. Connect using Sandbox credentials
3. Click Test Connection to verify
4. Try: “Show my QuickBooks profit and loss report”