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 FROM [WHERE ] [ORDERBY DESC] [MAXRESULTS ]
Operators
=, <, >, <=, >=, LIKE '%text%', IN ('a','b')
Tips
- No subqueries. To filter by customer name, first query Customer to get the Id, then use CustomerRef = '' 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:
{
"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:
{
"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:
{
"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
{
"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:
- User describes a job (client, scope, labor, materials) via chat
- Extract structured data from the description, filling in defaults for anything the user did not specify (rate, quantity, expiration date, memo)
qb_query Customer to check if the client exists
- If new client:
qb_create Customer
qb_create Estimate with line items (typically labor + materials)
- 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?"
- User comes back later to refine:
qb_query the estimate (note the SyncToken in the results)
qb_update Estimate with revised line items (include Id and SyncToken)
- When user says it's ready:
qb_send Estimate to the client's email
New customer job
qb_query Customer to check if the client exists (see "Finding a customer, invoice, or estimate")
- If new client:
qb_create Customer
qb_create Estimate with the new customer's Id
- User approves the estimate
- Convert estimate to invoice (see below)
qb_send the invoice
Recovering a customer email
qb_query: SELECT * FROM Customer WHERE Id = '<customer_id>' and check PrimaryEmailAddr.Address. If it's set, use it.
- 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.
- If still empty, repeat the same query against
Estimate.
- Only ask the user when none of the above produced an address.
Quick invoice
qb_query Customer to get the customer Id
qb_create Invoice with CustomerRef and line items
qb_send the invoice
Convert estimate to invoice
qb_query: SELECT * FROM Estimate WHERE Id = '<estimate_id>'
qb_create Invoice using the estimate's CustomerRef and Line items, plus a LinkedTxn:
{
"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
1---2name: quickbooks3description: QuickBooks Online4---5# QuickBooks Online67QuickBooks Online stores customers, items, estimates, invoices, bills, and payments. This integration queries those records and manages supported customers and sales transactions.89## Available Tools1011| Tool | Purpose |12|------|---------|13| `qb_query` | Run read-only queries using QBO query language |14| `qb_create` | Create a Customer, Estimate, Invoice, or Item |15| `qb_update` | Update an existing Customer, Estimate, Invoice, or Item |16| `qb_send` | Email an invoice or estimate to a customer |1718## Query Guide (qb_query)1920### Queryable entities and useful fields21- Invoice: Id, SyncToken, DocNumber, CustomerRef, TotalAmt, Balance, DueDate, TxnDate, EmailStatus, BillEmail, BillEmailCc, BillEmailBcc, Line, CustomerMemo, PrivateNote, BillAddr, ShipAddr, LinkedTxn, PrintStatus, EInvoiceStatus22- Estimate: Id, SyncToken, DocNumber, CustomerRef, TotalAmt, TxnDate, ExpirationDate, TxnStatus, BillEmail, Line, CustomerMemo, PrivateNote, AcceptedDate, AcceptedBy, LinkedTxn23- Customer: Id, SyncToken, DisplayName, CompanyName, PrimaryEmailAddr, PrimaryPhone, BillAddr, Balance, BalanceWithJobs, Active, Notes, ParentRef, Job24- Item: Id, Name, FullyQualifiedName, Sku, Description, UnitPrice, Type, Active, IncomeAccountRef, ParentRef, QtyOnHand25- Payment: Id, CustomerRef, TotalAmt, TxnDate, PaymentMethodRef, PaymentRefNum, UnappliedAmt, Line26- Bill: Id, VendorRef, DocNumber, TotalAmt, Balance, DueDate, TxnDate, Line, PrivateNote2728`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`.2930### Syntax31SELECT <fields> FROM <Entity> [WHERE <conditions>] [ORDERBY <field> DESC] [MAXRESULTS <n>]3233### Operators34=, <, >, <=, >=, LIKE '%text%', IN ('a','b')3536### Tips37- No subqueries. To filter by customer name, first query Customer to get the Id, then use CustomerRef = '<id>' in a second query.38- Always use MAXRESULTS to keep results manageable.39- 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.40- String comparisons are case-sensitive in QBO queries.4142## Finding a customer, invoice, or estimate4344An entity you have not queried this session is unknown, not absent. Never tell45the user a customer, invoice, or estimate does not exist, and never create a46new one, until `qb_query` has returned no match for the identifier they gave.47An ID you already resolved this session can be reused without re-querying.4849Amounts, balances, and statuses are the opposite of IDs: they go stale50(payments land, invoices get edited). Quote them only from rows a query51returned this turn. If the entity the user asked about is not in those rows,52query for it directly; do not recite numbers remembered from an earlier turn.5354## Creating Entities (qb_create)5556Pass `entity_type` (Customer, Estimate, Invoice, or Item) and `data` (the QBO API payload).5758### Customer payload5960Required fields:61- `DisplayName` (string, must be unique in QB)6263Optional fields:64- `PrimaryEmailAddr`: `{"Address": "email@example.com"}`65- `PrimaryPhone`: `{"FreeFormNumber": "555-1234"}`66- `CompanyName`: string67- `GivenName`, `FamilyName`: strings68- `BillAddr`: `{"Line1": "...", "City": "...", "CountrySubDivisionCode": "CA", "PostalCode": "90210"}`6970Example:71```json72{73 "entity_type": "Customer",74 "data": {75 "DisplayName": "Test Customer",76 "PrimaryEmailAddr": {"Address": "test.customer@example.com"},77 "PrimaryPhone": {"FreeFormNumber": "555-0199"}78 }79}80```8182### Estimate payload8384Required fields:85- `CustomerRef`: `{"value": "<customer_id>"}` (look up the customer first with qb_query)86- `Line`: array of line items (see below)8788Optional fields:89- `ExpirationDate`: "YYYY-MM-DD"90- `CustomerMemo`: `{"value": "notes text"}`91- `TxnDate`: "YYYY-MM-DD" (defaults to today)9293### Invoice payload9495Required fields:96- `CustomerRef`: `{"value": "<customer_id>"}`97- `Line`: array of line items (see below)9899Optional fields:100- `DueDate`: "YYYY-MM-DD"101- `CustomerMemo`: `{"value": "notes text"}`102- `TxnDate`: "YYYY-MM-DD" (defaults to today)103- `LinkedTxn`: array of linked transactions (used when converting an estimate)104105### Item payload106107Required fields:108- `Name` (string, must be unique in QB)109- `Type` (string): "Inventory", "Service", or "OtherCharge"110111Optional fields:112- `Description`: string113- `UnitPrice`: number114- `IncomeAccountRef`: `{"value": "<account_id>", "name": "<account_name>"}`115- `Active`: boolean (defaults to true)116- `Sku`: string (stock-keeping unit code)117- `ParentRef`: `{"value": "<parent_item_id>"}`118- `PurchaseDesc`: string119- `PurchaseCost`: number120- `QtyOnHand`: number (for Inventory items)121122Example:123```json124{125 "entity_type": "Item",126 "data": {127 "Name": "Materials",128 "Type": "Service",129 "IncomeAccountRef": {130 "value": "1",131 "name": "Services"132 }133 }134}135```136137### Line item format138139Each line item in the `Line` array should look like:140```json141{142 "Amount": 400.00,143 "DetailType": "SalesItemLineDetail",144 "Description": "Labor - kitchen remodel",145 "SalesItemLineDetail": {146 "Qty": 8,147 "UnitPrice": 50.00148 }149}150```151152`Amount` should equal `Qty * UnitPrice`.153154## Updating Entities (qb_update)155156Pass `entity_type` and `data` with the **full entity payload including Id and SyncToken** from a prior `qb_query`.157158The 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.159160### Update example161```json162{163 "entity_type": "Estimate",164 "data": {165 "Id": "2001",166 "SyncToken": "0",167 "CustomerRef": {"value": "100"},168 "Line": [169 {170 "Amount": 600.00,171 "DetailType": "SalesItemLineDetail",172 "Description": "Labor - kitchen remodel (revised)",173 "SalesItemLineDetail": {"Qty": 12, "UnitPrice": 50.00}174 },175 {176 "Amount": 350.00,177 "DetailType": "SalesItemLineDetail",178 "Description": "Materials",179 "SalesItemLineDetail": {"Qty": 1, "UnitPrice": 350.00}180 }181 ]182 }183}184```185186## Sending Invoices and Estimates (qb_send)187188- Pass `entity_type` (Invoice or Estimate), the entity ID (numeric), and the recipient email address.189- If you do not already have an email, follow "Recovering a customer email" below before asking the user.190191## Common Workflows192193### Voice-to-estimate (dictation workflow)194This is the primary workflow for users who dictate job details from the field:1951. User describes a job (client, scope, labor, materials) via chat1962. Extract structured data from the description, filling in defaults for anything the user did not specify (rate, quantity, expiration date, memo)1973. `qb_query` Customer to check if the client exists1984. If new client: `qb_create` Customer1995. `qb_create` Estimate with line items (typically labor + materials)2006. 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?"2017. User comes back later to refine: `qb_query` the estimate (note the SyncToken in the results)2028. `qb_update` Estimate with revised line items (include Id and SyncToken)2039. When user says it's ready: `qb_send` Estimate to the client's email204205### New customer job2061. `qb_query` Customer to check if the client exists (see "Finding a customer, invoice, or estimate")2072. If new client: `qb_create` Customer2083. `qb_create` Estimate with the new customer's Id2094. User approves the estimate2105. Convert estimate to invoice (see below)2116. `qb_send` the invoice212213### Recovering a customer email2141. `qb_query`: `SELECT * FROM Customer WHERE Id = '<customer_id>'` and check `PrimaryEmailAddr.Address`. If it's set, use it.2152. 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.2163. If still empty, repeat the same query against `Estimate`.2174. Only ask the user when none of the above produced an address.218219### Quick invoice2201. `qb_query` Customer to get the customer Id2212. `qb_create` Invoice with CustomerRef and line items2223. `qb_send` the invoice223224### Convert estimate to invoice2251. `qb_query`: `SELECT * FROM Estimate WHERE Id = '<estimate_id>'`2262. `qb_create` Invoice using the estimate's CustomerRef and Line items, plus a LinkedTxn:227```json228{229 "entity_type": "Invoice",230 "data": {231 "CustomerRef": {"value": "<customer_id from estimate>"},232 "Line": [... line items from estimate ...],233 "LinkedTxn": [{"TxnId": "<estimate_id>", "TxnType": "Estimate"}]234 }235}236```237QuickBooks automatically updates the estimate status when a linked invoice is created.238239### Check outstanding balances240`qb_query`: `SELECT * FROM Invoice WHERE Balance > '0' MAXRESULTS 20`