# Quickbooks

> QuickBooks Online

- Skill: `mozilla-ai/quickbooks` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add mozilla-ai/quickbooks`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mozilla-ai/quickbooks/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mozilla-ai (https://skillmd.com/u/mozilla-ai)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/mozilla-ai/quickbooks

---

# QuickBooks Online

QuickBooks Online stores customers, items, estimates, invoices, bills, and payments. This integration queries those records and manages supported customers and sales transactions.

## Available Tools

| Tool | Purpose |
|------|---------|
| `qb_query` | Run read-only queries using QBO query language |
| `qb_create` | Create a Customer, Estimate, Invoice, or Item |
| `qb_update` | Update an existing Customer, Estimate, Invoice, or Item |
| `qb_send` | Email an invoice or estimate to a customer |

## Query Guide (qb_query)

### Queryable entities and useful fields
- Invoice: Id, SyncToken, DocNumber, CustomerRef, TotalAmt, Balance, DueDate, TxnDate, EmailStatus, BillEmail, BillEmailCc, BillEmailBcc, Line, CustomerMemo, PrivateNote, BillAddr, ShipAddr, LinkedTxn, PrintStatus, EInvoiceStatus
- Estimate: Id, SyncToken, DocNumber, CustomerRef, TotalAmt, TxnDate, ExpirationDate, TxnStatus, BillEmail, Line, CustomerMemo, PrivateNote, AcceptedDate, AcceptedBy, LinkedTxn
- Customer: Id, SyncToken, DisplayName, CompanyName, PrimaryEmailAddr, PrimaryPhone, BillAddr, Balance, BalanceWithJobs, Active, Notes, ParentRef, Job
- Item: Id, Name, FullyQualifiedName, Sku, Description, UnitPrice, Type, Active, IncomeAccountRef, ParentRef, QtyOnHand
- Payment: Id, CustomerRef, TotalAmt, TxnDate, PaymentMethodRef, PaymentRefNum, UnappliedAmt, Line
- Bill: Id, VendorRef, DocNumber, TotalAmt, Balance, DueDate, TxnDate, Line, PrivateNote

`BillEmail`, `BillEmailCc`, `BillEmailBcc` are shaped `{"Address": "..."}` (the recipient email recorded on the invoice or estimate). SyncToken is returned in query results; you need it when updating an entity with `qb_update`.

### Syntax
SELECT <fields> FROM <Entity> [WHERE <conditions>] [ORDERBY <field> DESC] [MAXRESULTS <n>]

### Operators
=, <, >, <=, >=, LIKE '%text%', IN ('a','b')

### Tips
- No subqueries. To filter by customer name, first query Customer to get the Id, then use CustomerRef = '<id>' in a second query.
- Always use MAXRESULTS to keep results manageable.
- Not all fields support all operators. For example, Estimate TxnStatus does not support IN or LIKE. If a query returns a 400 error, simplify the WHERE clause and filter results yourself.
- String comparisons are case-sensitive in QBO queries.

## Finding a customer, invoice, or estimate

An entity you have not queried this session is unknown, not absent. Never tell
the user a customer, invoice, or estimate does not exist, and never create a
new one, until `qb_query` has returned no match for the identifier they gave.
An ID you already resolved this session can be reused without re-querying.

Amounts, balances, and statuses are the opposite of IDs: they go stale
(payments land, invoices get edited). Quote them only from rows a query
returned this turn. If the entity the user asked about is not in those rows,
query for it directly; do not recite numbers remembered from an earlier turn.

## Creating Entities (qb_create)

Pass `entity_type` (Customer, Estimate, Invoice, or Item) and `data` (the QBO API payload).

### Customer payload

Required fields:
- `DisplayName` (string, must be unique in QB)

Optional fields:
- `PrimaryEmailAddr`: `{"Address": "email@example.com"}`
- `PrimaryPhone`: `{"FreeFormNumber": "555-1234"}`
- `CompanyName`: string
- `GivenName`, `FamilyName`: strings
- `BillAddr`: `{"Line1": "...", "City": "...", "CountrySubDivisionCode": "CA", "PostalCode": "90210"}`

Example:
```json
{
  "entity_type": "Customer",
  "data": {
    "DisplayName": "Test Customer",
    "PrimaryEmailAddr": {"Address": "test.customer@example.com"},
    "PrimaryPhone": {"FreeFormNumber": "555-0199"}
  }
}
```

### Estimate payload

Required fields:
- `CustomerRef`: `{"value": "<customer_id>"}` (look up the customer first with qb_query)
- `Line`: array of line items (see below)

Optional fields:
- `ExpirationDate`: "YYYY-MM-DD"
- `CustomerMemo`: `{"value": "notes text"}`
- `TxnDate`: "YYYY-MM-DD" (defaults to today)

### Invoice payload

Required fields:
- `CustomerRef`: `{"value": "<customer_id>"}`
- `Line`: array of line items (see below)

Optional fields:
- `DueDate`: "YYYY-MM-DD"
- `CustomerMemo`: `{"value": "notes text"}`
- `TxnDate`: "YYYY-MM-DD" (defaults to today)
- `LinkedTxn`: array of linked transactions (used when converting an estimate)

### Item payload

Required fields:
- `Name` (string, must be unique in QB)
- `Type` (string): "Inventory", "Service", or "OtherCharge"

Optional fields:
- `Description`: string
- `UnitPrice`: number
- `IncomeAccountRef`: `{"value": "<account_id>", "name": "<account_name>"}`
- `Active`: boolean (defaults to true)
- `Sku`: string (stock-keeping unit code)
- `ParentRef`: `{"value": "<parent_item_id>"}`
- `PurchaseDesc`: string
- `PurchaseCost`: number
- `QtyOnHand`: number (for Inventory items)

Example:
```json
{
  "entity_type": "Item",
  "data": {
    "Name": "Materials",
    "Type": "Service",
    "IncomeAccountRef": {
      "value": "1",
      "name": "Services"
    }
  }
}
```

### Line item format

Each line item in the `Line` array should look like:
```json
{
  "Amount": 400.00,
  "DetailType": "SalesItemLineDetail",
  "Description": "Labor - kitchen remodel",
  "SalesItemLineDetail": {
    "Qty": 8,
    "UnitPrice": 50.00
  }
}
```

`Amount` should equal `Qty * UnitPrice`.

## Updating Entities (qb_update)

Pass `entity_type` and `data` with the **full entity payload including Id and SyncToken** from a prior `qb_query`.

The SyncToken is required for optimistic concurrency. If the entity was modified since you last queried it, QuickBooks will reject the update with a conflict error. In that case, re-query the entity and try again with the new SyncToken.

### Update example
```json
{
  "entity_type": "Estimate",
  "data": {
    "Id": "2001",
    "SyncToken": "0",
    "CustomerRef": {"value": "100"},
    "Line": [
      {
        "Amount": 600.00,
        "DetailType": "SalesItemLineDetail",
        "Description": "Labor - kitchen remodel (revised)",
        "SalesItemLineDetail": {"Qty": 12, "UnitPrice": 50.00}
      },
      {
        "Amount": 350.00,
        "DetailType": "SalesItemLineDetail",
        "Description": "Materials",
        "SalesItemLineDetail": {"Qty": 1, "UnitPrice": 350.00}
      }
    ]
  }
}
```

## Sending Invoices and Estimates (qb_send)

- Pass `entity_type` (Invoice or Estimate), the entity ID (numeric), and the recipient email address.
- If you do not already have an email, follow "Recovering a customer email" below before asking the user.

## Common Workflows

### Voice-to-estimate (dictation workflow)
This is the primary workflow for users who dictate job details from the field:
1. User describes a job (client, scope, labor, materials) via chat
2. Extract structured data from the description, filling in defaults for anything the user did not specify (rate, quantity, expiration date, memo)
3. `qb_query` Customer to check if the client exists
4. If new client: `qb_create` Customer
5. `qb_create` Estimate with line items (typically labor + materials)
6. Summarize what you drafted and what you assumed in one line: "Drafted estimate for Test Customer: 8 hr labor at $50, materials $200, expires in 30 days. Change anything?"
7. User comes back later to refine: `qb_query` the estimate (note the SyncToken in the results)
8. `qb_update` Estimate with revised line items (include Id and SyncToken)
9. When user says it's ready: `qb_send` Estimate to the client's email

### New customer job
1. `qb_query` Customer to check if the client exists (see "Finding a customer, invoice, or estimate")
2. If new client: `qb_create` Customer
3. `qb_create` Estimate with the new customer's Id
4. User approves the estimate
5. Convert estimate to invoice (see below)
6. `qb_send` the invoice

### Recovering a customer email
1. `qb_query`: `SELECT * FROM Customer WHERE Id = '<customer_id>'` and check `PrimaryEmailAddr.Address`. If it's set, use it.
2. If empty, `qb_query`: `SELECT * FROM Invoice WHERE CustomerRef = '<customer_id>' ORDERBY TxnDate DESC MAXRESULTS 5` and check `BillEmail.Address` on the returned rows. Use the most recent non-empty value.
3. If still empty, repeat the same query against `Estimate`.
4. Only ask the user when none of the above produced an address.

### Quick invoice
1. `qb_query` Customer to get the customer Id
2. `qb_create` Invoice with CustomerRef and line items
3. `qb_send` the invoice

### Convert estimate to invoice
1. `qb_query`: `SELECT * FROM Estimate WHERE Id = '<estimate_id>'`
2. `qb_create` Invoice using the estimate's CustomerRef and Line items, plus a LinkedTxn:
```json
{
  "entity_type": "Invoice",
  "data": {
    "CustomerRef": {"value": "<customer_id from estimate>"},
    "Line": [... line items from estimate ...],
    "LinkedTxn": [{"TxnId": "<estimate_id>", "TxnType": "Estimate"}]
  }
}
```
QuickBooks automatically updates the estimate status when a linked invoice is created.

### Check outstanding balances
`qb_query`: `SELECT * FROM Invoice WHERE Balance > '0' MAXRESULTS 20`

