Skill: armysarge/quickbooks-direct (version 1.0.1)

--- name: quickbooks-openclaw version: 1.0.1 description: Comprehensive QuickBooks Online API integration for accounting, invoicing, payments, and financial reporting author: Armysarge license: MIT tags: - accounting - quickbooks - invoicing - payments - financial - erp - bookkeeping category: Business & Finance --- # QuickBooks API Skill for OpenClaw A complete QuickBooks Online direct API integration skill for OpenClaw providing full access to accounting, invoicing, customer management, inventory, payments, and financial reporting through the Intuit QuickBooks API. ## Overview This skill enables OpenClaw to interact with QuickBooks Online for: - **Customer & Vendor Management**: Create and manage business relationships - **Invoicing**: Generate, send, and track invoices - **Payments**: Record and reconcile payments - **Inventory**: Manage products, services, and stock levels - **Financial Reports**: Generate P&L, Balance Sheets, Cash Flow, and aging reports - **Estimates**: Create quotes and proposals - **Bills**: Track accounts payable - **Purchase Orders**: Manage procurement ## Prerequisites 1. **QuickBooks Developer Account** - Sign up at [https://developer.intuit.com](https://developer.intuit.com) - Create a new app in the Developer Portal - Enable "QuickBooks Online API" scope 2. **App Credentials** - Client ID from your QuickBooks app - Client Secret from your QuickBooks app - Redirect URI: `http://localhost:3001/callback` 3. **Node.js** - Version 18.0.0 or higher - npm or yarn package manager ## Installation ### 1. Install Dependencies ```bash cd "c:\Users\Shaun\Desktop\Quickbooks skill" npm install ``` Required packages: - `axios` - HTTP client for API requests - `express` - OAuth callback server - `open` - Browser automation for OAuth ### 2. Configure Credentials Create `config.json` from template: ```bash cp config.json.template config.json ``` Edit `config.json` with your QuickBooks app credentials: ```json { "client_id": "YOUR_CLIENT_ID_HERE", "client_secret": "YOUR_CLIENT_SECRET_HERE", "redirect_uri": "http://localhost:3001/callback", "api_environment": "sandbox", "access_token": "", "refresh_token": "", "realm_id": "", "token_expiry": 0 } ``` ### 3. Add to Configuration **For OpenClaw:** Add to your OpenClaw configuration: ```json { "skills": { "quickbooks": { "path": "~/.openclaw/workspace/skills/Quickbooks-openclaw", "enabled": true, "autoStart": true } } } ``` ## Authentication ### First-Time Setup 1. Use the `qb_authenticate` tool with your credentials: ``` Use qb_authenticate with client_id and client_secret ``` 2. A browser window will open automatically 3. Log in to your QuickBooks account 4. Authorize the application 5. You'll be redirected to localhost (handled automatically) 6. Tokens are saved to `config.json` ### Token Management - **Access tokens** expire after 1 hour (refreshed automatically) - **Refresh tokens** last 100 days (renewed on refresh) - The skill automatically refreshes tokens before they expire - Re-authenticate if you see "Not authenticated" errors ## Available Tools ### 🔐 Authentication #### `qb_authenticate` Initiate OAuth2 authentication flow. **Parameters:** - `client_id` (required): Your QuickBooks app Client ID - `client_secret` (required): Your QuickBooks app Client Secret - `redirect_uri` (optional): OAuth redirect URI (default: http://localhost:3001/callback) **Example:** ```json { "client_id": "ABxxxxxxxxxxxxxxxxxxxx", "client_secret": "xxxxxxxxxxxxxxxxxx" } ``` --- ### 👥 Customer Management #### `qb_create_customer` Create a new customer. **Parameters:** - `DisplayName` (required): Customer display name - `CompanyName`: Company name - `GivenName`: First name - `FamilyName`: Last name - `PrimaryEmailAddr`: Email address object - `PrimaryPhone`: Phone number object - `BillAddr`: Billing address object - `ShipAddr`: Shipping address object **Example:** ```json { "DisplayName": "Acme Corporation", "PrimaryEmailAddr": { "Address": "[REDACTED_SECRET]" } } ``` #### `qb_get_customer` Get customer details by ID. **Parameters:** - `customer_id` (required): Customer ID #### `qb_query_customers` Query customers using SQL syntax. **Parameters:** - `query`: SQL query string (default: "SELECT * FROM Customer") **Example:** ```json { "query": "SELECT * FROM Customer WHERE Active = true" } ``` --- ### 🧾 Invoice Management #### `qb_create_invoice` Create a new invoice. **Parameters:** - `CustomerRef` (required): Customer reference object - `Line` (required): Array of line items - `TxnDate`: Transaction date (YYYY-MM-DD) - `DueDate`: Due date (YYYY-MM-DD) - `CustomerMemo`: Message to customer - `BillEmail`: Email address for invoice **Example:** ```json { "CustomerRef": { "value": "123" }, "Line": [{ "Amount": 500.00, "DetailType": "SalesItemLineDetail", "SalesItemLineDetail": { "ItemRef": { "value": "1" }, "Qty": 10, "UnitPrice": 50.00 } }], "DueDate": "2026-03-15" } ``` #### `qb_get_invoice` Get invoice by ID. **Parameters:** - `invoice_id` (required): Invoice ID #### `qb_send_invoice` Send invoice via email. **Parameters:** - `invoice_id` (required): Invoice ID - `email` (required): Recipient email address #### `qb_query_invoices` Query invoices using SQL syntax. **Parameters:** - `query`: SQL query string **Example:** ```json { "query": "SELECT * FROM Invoice WHERE Balance > 0" } ``` --- ### 📦 Item/Product Management #### `qb_create_item` Create a new product or service item. **Parameters:** - `Name` (required): Item name - `Type` (required): Item type (Service, Inventory, NonInventory) - `Description`: Item description - `UnitPrice`: Sales price - `IncomeAccountRef`: Income account reference - `ExpenseAccountRef`: Expense account reference (for inventory) - `QtyOnHand`: Quantity on hand (for inventory) **Example:** ```json { "Name": "Consulting Services", "Type": "Service", "UnitPrice": 150.00, "IncomeAccountRef": { "value": "79" } } ``` #### `qb_get_item` Get item by ID. **Parameters:** - `item_id` (required): Item ID #### `qb_query_items` Query items using SQL syntax. **Parameters:** - `query`: SQL query string --- ### 💰 Payment Processing #### `qb_create_payment` Record a payment received. **Parameters:** - `CustomerRef` (required): Customer reference - `TotalAmt` (required): Total payment amount - `TxnDate`: Transaction date - `Line`: Array of payment line items linking to invoices - `PaymentMethodRef`: Payment method reference **Example:** ```json { "CustomerRef": { "value": "123" }, "TotalAmt": 500.00, "Line": [{ "Amount": 500.00, "LinkedTxn": [{ "TxnId": "456", "TxnType": "Invoice" }] }] } ``` #### `qb_query_payments` Query payments using SQL syntax. --- ### 📊 Financial Reports #### `qb_get_profit_loss` Generate Profit & Loss report. **Parameters:** - `start_date` (required): Start date (YYYY-MM-DD) - `end_date` (required): End date (YYYY-MM-DD) **Example:** ```json { "start_date": "2026-01-01", "end_date": "2026-01-31" } ``` #### `qb_get_balance_sheet` Generate Balance Sheet report. **Parameters:** - `date` (required): Report date (YYYY-MM-DD) #### `qb_get_cash_flow` Generate Cash Flow report. **Parameters:** - `start_date` (required): Start date - `end_date` (required): End date #### `qb_get_aged_receivables` Generate Aged Receivables (A/R Aging) report. **Parameters:** None #### `qb_get_aged_payables` Generate Aged Payables (A/P Aging) report. **Parameters:** None --- ### 💼 Vendor & Bill Management #### `qb_create_vendor` Create a new vendor. **Parameters:** - `DisplayName` (required): Vendor display name - `CompanyName`: Company name - `PrimaryEmailAddr`: Email address object - `PrimaryPhone`: Phone number object #### `qb_create_bill` Create a bill for a vendor. **Parameters:** - `VendorRef` (required): Vendor reference - `Line` (required): Array of bill line items - `TxnDate`: Transaction date - `DueDate`: Due date #### `qb_query_vendors` Query vendors using SQL syntax. --- ### 📝 Estimates & Quotes #### `qb_create_estimate` Create a new estimate/quote. **Parameters:** - `CustomerRef` (required): Customer reference - `Line` (required): Array of line items - `TxnDate`: Transaction date - `ExpirationDate`: Expiration date #### `qb_query_estimates` Query estimates using SQL syntax. --- ### 🛒 Purchase Orders #### `qb_create_purchase_order` Create a purchase order. **Parameters:** - `VendorRef` (required): Vendor reference - `Line` (required): Array of PO line items --- ### 💵 Sales Receipts #### `qb_create_sales_receipt` Create a sales receipt (cash sale). **Parameters:** - `CustomerRef` (required): Customer reference - `Line` (required): Array of line items - `TxnDate`: Transaction date --- ### 🏦 Chart of Accounts #### `qb_query_accounts` Query chart of accounts. **Parameters:** - `query`: SQL query string **Example:** ```json { "query": "SELECT * FROM Account WHERE AccountType = 'Income'" } ``` --- ### 🏢 Company Information #### `qb_get_company_info` Get company information. **Parameters:** None --- ### 🔍 Generic Query #### `qb_query` Execute any SQL query against QuickBooks entities. **Parameters:** - `query` (required): SQL query string **Example:** ```json { "query": "SELECT * FROM Customer WHERE Balance > 100 ORDER BY DisplayName" } ``` **Supported Entities:** Account, Bill, BillPayment, Class, CreditMemo, Customer, Department, Deposit, Employee, Estimate, Invoice, Item, JournalEntry, Payment, PaymentMethod, Purchase, PurchaseOrder, RefundReceipt, SalesReceipt, TaxCode, TaxRate, Term, TimeActivity, Transfer, Vendor, VendorCredit --- ### ⚡ Batch Operations #### `qb_batch` Execute multiple operations in a single batch request. **Parameters:** - `operations` (required): Array of batch operations **Example:** ```json { "operations": [ { "bId": "bid1", "operation": "create", "entity": "Customer", "data": { "DisplayName": "Customer 1" } }, { "bId": "bid2", "operation": "query", "query": "SELECT * FROM Invoice WHERE Balance > 0" } ] } ``` ## Usage Examples ### Create and Send an Invoice Workflow ``` 1. First, create or find a customer: "Find customer with name 'Acme Corp' using qb_query_customers" 2. Create an invoice: "Create an invoice for customer ID 123 with consulting services for 10 hours at $150/hour, due in 30 days" 3. Send the invoice: "Send invoice 456 to [REDACTED_SECRET]" ``` ### Financial Reporting Workflow ``` 1. Get month-end reports: "Show me the profit and loss for January 2026" 2. Check cash flow: "What's the cash flow for last quarter?" 3. Review outstanding receivables: "Show me the aged receivables report" ``` ### Inventory Management Workflow ``` 1. Check low stock items: "Query items where quantity on hand is less than 10" 2. Create reorder purchase order: "Create a purchase order for vendor 789 to reorder low stock items" 3. Update item prices: "Update the price of item 'Widget Pro' to $299.99" ``` ## SQL Query Syntax QuickBooks uses a SQL-like query language: ### Basic Query ```sql SELECT * FROM Customer WHERE Active = true ``` ### With Conditions ```sql SELECT * FROM Invoice WHERE Balance > 0 AND DueDate < '2026-03-01' ``` ### Pattern Matching ```sql SELECT * FROM Customer WHERE DisplayName LIKE '%Corp%' ``` ### Ordering Results ```sql SELECT * FROM Invoice ORDER BY TxnDate DESC ``` ### Limiting Results ```sql SELECT *, MAXRESULTS 50 FROM Customer ``` ### Multiple Conditions ```sql SELECT * FROM Item WHERE Type = 'Inventory' AND QtyOnHand < 10 ``` ## Error Handling The skill provides detailed error messages: - **Authentication Errors**: "Not authenticated. Please run qb_authenticate first." - **API Errors**: Full QuickBooks error details with status codes - **Validation Errors**: Missing required fields or invalid data - **Rate Limit Errors**: "Too Many Requests - retry after delay" ## Configuration All configuration is stored in `config.json`. This file contains both your app credentials (Client ID and Secret) and the OAuth tokens that are saved after authentication. ### API Environment The skill supports both Sandbox and Production environments via the `api_environment` setting in `config.json`: - **sandbox** (default): QuickBooks Sandbox API for development and testing - **production**: QuickBooks Production API for live company data (requires app verification) To switch environments, update `config.json`: ```json { "api_environment": "sandbox" // or "production" } ``` **Important**: Production mode requires your app to be verified by Intuit. Start with sandbox for development. ### Security Considerations ⚠️ **Credential Storage**: This skill stores OAuth tokens and client secrets in plaintext in `config.json` on your local filesystem. To enhance security: - Set restrictive file permissions on `config.json` (read/write for owner only) - Never commit `config.json` to version control (included in `.gitignore`) - Store the skill directory in a secure location - Regularly rotate your client secrets in the QuickBooks Developer Portal - Consider encrypting your disk or using a secure secret management solution - Do not enable `autoStart` until you've verified the skill behaves as expected ## Rate Limits - **Sandbox**: 500 requests/minute per app - **Production**: Varies by subscription (500-1000/minute) The skill automatically handles rate limiting with proper error messages. ## Security - OAuth2 authentication (no password storage) - Tokens stored in `config.json` (excluded from git) - Automatic token refresh - Secure HTTPS API communication - No credentials in code ## Troubleshooting ### "Not authenticated" Error Run `qb_authenticate` with your credentials. ### "Token refresh failed" Delete `config.json` and re-authenticate. ### "Invalid redirect URI" Ensure redirect URI in config matches your QuickBooks app settings. ### Port 3000 Already in Use Change port in code or kill the process using port 3000. For more troubleshooting, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md). ## Documentation - [README.md](README.md) - Complete setup guide - [EXAMPLES.md](EXAMPLES.md) - 50+ practical examples - [API_REFERENCE.md](API_REFERENCE.md) - Full API documentation - [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues and solutions - [CHANGELOG.md](CHANGELOG.md) - Version history ## Support - [QuickBooks Developer Portal](https://developer.intuit.com) - [QuickBooks Developer Forum](https://help.developer.intuit.com/s/) - [API Documentation](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account) - [API Status](https://status.developer.intuit.com/) ## Contributing Contributions welcome! Please: 1. Fork the repository 2. Create a feature branch 3. Test thoroughly in sandbox 4. Submit a pull request ## License MIT License - See [LICENSE](LICENSE) file for details. ## Version **Current Version**: 1.0.1 **Last Updated**: February 21, 2026 **Node.js Required**: 18.0.0+ ## Tags `accounting` `quickbooks` `invoicing` `payments` `financial-reporting` `bookkeeping` `erp` `business` `intuit` `api-integration` `mcp-skill` `openclaw` --- **Ready to use!** Run `npm install` and authenticate to get started.


Security scan verdicts — ClawScan: suspicious | static analysis:  | VirusTotal: suspicious | SkillSpector: suspicious (CRITICAL)