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