quickbooks

name	quickbooks
version	1.0.0
description	QuickBooks API integration for managing customers, invoices, payments, bills, and financial reports via Maton gateway. Use this skill when the user needs to create invoices, track payments, manage vendors, run profit/loss reports, or says 'send an invoice', 'check outstanding payments', 'run a financial report.' Also trigger for 'quickbooks', 'accounting', 'invoicing', 'bookkeeping', or financial data management.
author	G-HunterAi
license	MIT
tags	["accounting","quickbooks","invoices","payments","finance"]
platforms	["all"]
category	integration
emoji	💰
metadata	{"author":"maton","compatibility":"Requires network access and valid Maton API key"}

QuickBooks Skill

Access the QuickBooks Online API with managed OAuth authentication. Manage customers, vendors, invoices, payments, and run financial reports.

When to Use

• Accounting and bookkeeping workflows
• Invoice creation and management
• Payment processing and tracking
• Financial reporting (P&L, balance sheets, cash flow)
• Customer and vendor management
• Multi-entity accounting

When NOT to Use

• CRM functions (use hubspot skill)
• Expense tracking only (simpler tools exist)
• Personal budgeting (use specialized finance apps)
• Tax preparation (use accounting software)

Prerequisites

1. Maton Gateway Account — Required for OAuth gateway

   • Sign up at maton.ai
   • Create API key at maton.ai/settings

2. QuickBooks Online Account — Company must be subscribed to QBO

3. Network Access — Connectivity to gateway.maton.ai and quickbooks.api.intuit.com

Important Note: This skill uses Maton as an OAuth gateway. Maton handles QuickBooks authentication and provides a unified API endpoint. All requests route through Maton's gateway.

Set environment variable:

export MATON_API_KEY="YOUR_API_KEY"

Quick Start

# Query customers
curl -s -X GET 'https://gateway.maton.ai/quickbooks/v3/company/:realmId/query?query=SELECT%20*%20FROM%20Customer%20MAXRESULTS%20100' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Base URL

https://gateway.maton.ai/quickbooks/v3/company/:realmId/{endpoint}

The gateway proxies requests to quickbooks.api.intuit.com. The :realmId placeholder is automatically replaced with your company's realm ID.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your QuickBooks OAuth connections at https://ctrl.maton.ai.

List Connections

curl -s -X GET 'https://ctrl.maton.ai/connections?app=quickbooks&status=ACTIVE' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Create Connection

curl -s -X POST 'https://ctrl.maton.ai/connections' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"app": "quickbooks"}'

Get Connection

curl -s -X GET 'https://ctrl.maton.ai/connections/{connection_id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response:

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "quickbooks"
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

curl -s -X DELETE 'https://ctrl.maton.ai/connections/{connection_id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

API Reference

Company Info

GET /quickbooks/v3/company/:realmId/companyinfo/:realmId

Customers

Query Customers

GET /quickbooks/v3/company/:realmId/query?query=SELECT%20*%20FROM%20Customer%20MAXRESULTS%20100

Get Customer

GET /quickbooks/v3/company/:realmId/customer/{customerId}

Create Customer

POST /quickbooks/v3/company/:realmId/customer
Content-Type: application/json

{
  "DisplayName": "John Doe",
  "PrimaryEmailAddr": {"Address": "[e-mail]"},
  "PrimaryPhone": {"FreeFormNumber": "555-1234"}
}

Update Customer

Requires Id and SyncToken from previous GET:

POST /quickbooks/v3/company/:realmId/customer
Content-Type: application/json

{
  "Id": "123",
  "SyncToken": "0",
  "DisplayName": "John Doe Updated"
}

Invoices

Query Invoices

GET /quickbooks/v3/company/:realmId/query?query=SELECT%20*%20FROM%20Invoice%20MAXRESULTS%20100

Create Invoice

POST /quickbooks/v3/company/:realmId/invoice
Content-Type: application/json

{
  "CustomerRef": {"value": "123"},
  "Line": [
    {
      "Amount": 100.00,
      "DetailType": "SalesItemLineDetail",
      "SalesItemLineDetail": {
        "ItemRef": {"value": "1"},
        "Qty": 1
      }
    }
  ]
}

Delete Invoice

POST /quickbooks/v3/company/:realmId/invoice?operation=delete
Content-Type: application/json

{
  "Id": "123",
  "SyncToken": "0"
}

Payments

Create Payment

POST /quickbooks/v3/company/:realmId/payment
Content-Type: application/json

{
  "CustomerRef": {"value": "123"},
  "TotalAmt": 100.00,
  "Line": [
    {
      "Amount": 100.00,
      "LinkedTxn": [{"TxnId": "456", "TxnType": "Invoice"}]
    }
  ]
}

Reports

Profit and Loss

GET /quickbooks/v3/company/:realmId/reports/ProfitAndLoss?start_date=2024-01-01&end_date=2024-12-31

Balance Sheet

GET /quickbooks/v3/company/:realmId/reports/BalanceSheet?date=2024-12-31

Batch Operations

POST /quickbooks/v3/company/:realmId/batch
Content-Type: application/json

{
  "BatchItemRequest": [
    {"bId": "1", "Query": "SELECT * FROM Customer MAXRESULTS 2"},
    {"bId": "2", "Query": "SELECT * FROM Vendor MAXRESULTS 2"}
  ]
}

Query Language

QuickBooks uses SQL-like queries:

SELECT * FROM Customer WHERE DisplayName LIKE 'John%' MAXRESULTS 100

Operators: =, LIKE, <, >, <=, >=, IN

SyncToken

All updates require the current SyncToken:

1. GET the entity to get current SyncToken
2. Include Id and SyncToken in POST body
3. If SyncToken doesn't match, update fails

Code Examples

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/quickbooks/v3/company/:realmId/query?query=SELECT%20*%20FROM%20Customer',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/quickbooks/v3/company/:realmId/query',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'query': 'SELECT * FROM Customer MAXRESULTS 10'}
)

Error Handling

Status	Meaning	Recovery
400	Missing QuickBooks connection	Create connection at https://ctrl.maton.ai
401	Invalid or missing Maton API key	Verify MATON_API_KEY is set correctly
403	Insufficient permissions	Check API key scopes and connection status
429	Rate limited	Wait 60 seconds; limits are 10 req/sec per account
4xx/5xx	Passthrough error from QuickBooks API	Check QuickBooks documentation

Works Well With

• hubspot — Sync customer data between HubSpot and QuickBooks
• email-automation — Invoice reminders and payment notifications
• workflow-orchestrator — Complex accounting workflows

---

Notes

• :realmId is automatically replaced by the router
• All queries must be URL-encoded
• Use MAXRESULTS to limit query results
• Dates are in YYYY-MM-DD format
• Soft delete entities by setting Active: false

Resources

• QuickBooks API Overview
• Customers
• Invoices
• Payments
• Reports