connector-quickbooks — QuickBooks Online skill for Claude Code
connector-quickbooks is a Claude Code skill for managing QuickBooks Online invoices, customers, payments and items via quickbooks-client. It can bill customers or retrieve QBO data from a project.
Apache-2.0 10,200 installs ★ 2 updated 2026-11-02
npx skills add caffeinelabs/skills --skill connector-quickbooks -a claude-codeWhat connector-quickbooks does
The skill wires the quickbooks-client package into agent requests. It covers creating, reading and updating invoices, customers, payments, items and chart-of-account entries in QuickBooks Online, emailing invoices, and running query_ calls against QBO data.
Inside are Motoko bindings for five entities: Customer, Invoice, Payment, Item and Account. All 12 operations live in Apis/DefaultApi.mo, as save*/get* pairs plus sendInvoice and query_. Schemas were transcribed from Intuit's official XSD.
Auth is OAuth 2.0 Authorization Code, so there is no static API key. Each user connects their own QuickBooks company, and the app gets a short-lived Bearer token, roughly an hour. HTTP 401 means re-authenticate. Outbound calls need is_replicated = ?false: QBO responses are non-deterministic, and a replicated call would fan out across ~13 replicas and fail consensus. Create and update share one save<Entity> operation: without Id and SyncToken it creates, with both it updates. Transactions like Invoice and Payment are deleted via operation = ?#delete; customers, items and accounts cannot be deleted, only deactivated with Active = ?false. Estimates, bills, vendors and the rest of the QBO entity set are not part of this slice.
What it helps with
- create an invoice with line items and email it to a customer
- fetch a customer or item by Id
- run a partial invoice update with the sparse flag
- query QBO for records matching custom filters
- delete a payment using the correct SyncToken
Example prompts for the agent
- Create a $100 consulting invoice for customer 58, item 1, then email it
- Look up customer 58 and show me their current details
- Delete invoice 12345 after fetching its SyncToken with getInvoice
How to install connector-quickbooks
1Skills CLI (Vercel)
npx skills add caffeinelabs/skills --skill connector-quickbooks -a claude-code2Manually: put the files in place
~/.claude/skills/connector-quickbooks/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/connector-quickbooks/
1Skills CLI (Vercel)
npx skills add caffeinelabs/skills --skill connector-quickbooks -a codex2Manually: put the files in place
.agents/skills/connector-quickbooks/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add caffeinelabs/skills --skill connector-quickbooks -a cursor2Manually: put the files in place
.cursor/skills/connector-quickbooks/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install caffeinelabs/skills skills/connector-quickbooks2Manually: put the files in place
.github/skills/connector-quickbooks/SKILL.md1Skills CLI (Vercel)
npx skills add caffeinelabs/skills --skill connector-quickbooks -a gemini-cli2Platform CLI
gemini skills install https://github.com/caffeinelabs/skills --path skills/connector-quickbooksManually: put the files in place
.devin/skills/connector-quickbooks/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add caffeinelabs/skills --skill connector-quickbooks -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about connector-quickbooks
How do I install connector-quickbooks in Claude Code?
Run npx skills add caffeinelabs/skills --skill connector-quickbooks -a claude-code. The skill lands in ~/.claude/skills/connector-quickbooks/SKILL.md.
What does connector-quickbooks do?
It gives an agent QuickBooks Online access through quickbooks-client: invoices, customers, payments, items and accounts. You can create, read, update, delete transactions and email invoices.
What is the difference between create and update here?
Both go through save<Entity>. A body with Id and the current SyncToken updates; without them it creates. For partial updates set sparse = ?true.
Source text
SKILL.md · Apache-2.0
---
name: connector-quickbooks
description: >-
Use the `quickbooks-client` mops package whenever the user asks the canister
to create/read/update invoices, customers, payments, items, or chart-of-account
entries in QuickBooks Online (QBO), email an invoice, or run a QuickBooks query.
The package wraps the QuickBooks Online Accounting API v3 at
`https://quickbooks.api.intuit.com` via outbound HTTPS calls.
version: 0.3.0
caffeineai-subscription: [none]
compatibility:
mops:
quickbooks-client: "~0.4.0"
---
# quickbooks-client
Motoko bindings for a curated slice of the [QuickBooks Online Accounting API
v3](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account):
**Customer, Invoice, Payment, Item, Account**. Schemas were transcribed from
Intuit's official XSD. All 12 operations live in `Apis/DefaultApi.mo`:
`saveCustomer`/`getCustomer`, `saveItem`/`getItem`, `saveAccount`/`getAccount`,
`saveInvoice`/`getInvoice`/`sendInvoice`, `savePayment`/`getPayment`, and `query_`
(trailing underscore — `query` is a reserved word in Motoko).
## Trigger phrases
Reach for this skill on any request mentioning: QuickBooks, QBO, invoice,
"bill a customer", "send an invoice", record/receive a payment, customer,
accounting, bookkeeping, chart of accounts, item/product/service,
"sync to QuickBooks".
**Not in this slice:** Estimate, Bill, Vendor, PurchaseOrder, CreditMemo and the
rest of the QBO entity set — the spec is hand-curated to Customer, Invoice,
Payment, Item and Account. If a request needs one of the others, say so rather
than mapping it onto Invoice; the spec has to be re-spun from Intuit's XSD
first.
## How QuickBooks authentication works (read before wiring)
QBO uses **OAuth 2.0 Authorization Code** — there is no static API key. Each
end-user authorises their QuickBooks company; the app exchanges the authorization
code for a short-lived **Bearer access token** (~1 hour) and passes it to the
client at call time. On expiry the API returns HTTP 401 — surface a
`#Err("auth_expired")` result and re-authenticate off-chain.
Two identifiers travel with every call:
- **`realmId`** — the QuickBooks *company id*, obtained during the OAuth handshake.
It is the first argument to every operation.
- **`minorversion`** — the API minor version (default `"75"`); pass `""` to omit
and use the account default.
**The token exchange is itself an on-chain outcall** to Intuit's token endpoint
and needs the app's **Client Secret**. Two hazards (identical to the googlemail
connector):
- **`is_replicated = ?false` on the exchange too** — the token response is
non-deterministic, so a replicated exchange duplicates across ~13 replicas and
fails IC consensus.
- **The Client Secret leaks with exported source** — Caffeine can export the app
to a `.zip` or public GitHub repo, carrying the secret along. Scope it minimally
and rotate if the source is shared.
Persist the per-user refresh/session token across upgrades (stable memory) so a
redeploy doesn't force re-authentication. OAuth scope: `com.intuit.quickbooks.accounting`.
## Create vs. update vs. delete (important QBO semantics)
- **Create and update BOTH use the `save<Entity>` (POST) operation.** It's an
*update* when the body carries the entity's `Id` **and** current `SyncToken`
(fetch them first via `get<Entity>`); set `sparse = ?true` for a partial update.
Without `Id`/`SyncToken` it's a create.
- **Delete** (transactions only — `Invoice`, `Payment`): call `saveInvoice` /
`savePayment` with `operation = ?#delete` and a body carrying `Id` + `SyncToken`.
The `operation` argument is **optional** (`?SaveInvoiceOperationParameter`),
not a bare variant. Pass **`null` for a normal create or update** — the client
then omits the query parameter entirely, which is what QBO wants; the spec
says "Omit for create/update; 'delete' removes the invoice". Only `?#delete`
is routinely needed. Name-list entities
(`Customer`, `Item`, `Account`) are **not deletable** — set `Active = ?false`
to deactivate instead (their `save*` ops take no `operation` argument).
- **Responses are wrapped**: `getCustomer` returns `CustomerResponse` with a
`Customer` field (and a `time`); same shape per entity. `query_` returns a
`QueryResponse` whose `QueryResponse` field holds arrays per entity type.
The operation is `query_`, not `query`.
- **Invoice lines and Payment lines are different types.** `Invoice.Line` is
`[Line]`, where `DetailType` is **required**. `Payment.Line` is
`[PaymentLine]` — `{Amount, LinkedTxn, …}` with **no** `DetailType`, which is
what Intuit actually sends when a payment is applied to invoices. They were
one shared type until 0.2.0, and that made every payment response fail to
decode.
## Frontend surfaces (two pages)
Like any per-user OAuth connector, an app needs **two** surfaces:
- An **admin-gated Intuit app configuration page** — the **Client ID** and
**Client Secret** are canister-wide, set once by an admin; never expose the
Client Secret to ordinary users.
- A **per-user OAuth 2.0 handshake page** — each user connects their own
QuickBooks company (yielding their `realmId` + token); re-prompt on HTTP 401.
## Usage
```mo:quickbooks-client
import { saveInvoice; getInvoice; sendInvoice; saveCustomer }
"mo:quickbooks-client/Apis/DefaultApi";
import Invoice "mo:quickbooks-client/Models/Invoice";
import { defaultConfig } "mo:quickbooks-client/Config";
let cfg = {
defaultConfig with
auth = ?#bearer "<off-chain OAuth2 access token>";
is_replicated = ?false; // non-replicated: required for writes; reads too
};
let realmId = "<company id from OAuth handshake>";
// Build an invoice: one sales line, $100, item "1", billed to customer "58".
// Invoice has no required fields → init {} then record-update the optionals.
// NOTE: DetailType is REQUIRED on a Line, and its variants are lowercase.
let inv = {
Invoice.init {} with
CustomerRef = ?{ value = "58"; name = null };
Line = ?[ {
DetailType = #salesitemlinedetail; // required; lowercase variant
Amount = ?100.0;
Description = ?"Consulting";
SalesItemLineDetail = ?{ ItemRef = ?{ value = "1"; name = null };
Qty = ?1.0; UnitPrice = ?100.0; TaxCodeRef = null; ServiceDate = null };
Id = null; LineNum = null; LinkedTxn = null;
} ];
};
// saveInvoice(config, realmId, invoice, minorversion, operation)
// `operation` is optional: null omits it — the create/update path.
let created = await* saveInvoice(cfg, realmId, inv, "75", null);
// Email it to the customer (config, realmId, invoiceId, sendTo, minorversion):
// ignore await* sendInvoice(cfg, realmId, "<invoiceId>", "[email protected]", "75");
```
## Notes
- **Use `is_replicated = ?false` for writes** (`save*`, `sendInvoice`, delete via
`operation = ?#delete`). These outcalls are non-idempotent and QBO's response is
non-deterministic; in replicated mode every replica issues the request — creating
duplicate invoices/payments and failing IC consensus. Reads (`get*`, `query_`)
also use `?false` (one node, ~13× cheaper).
- **Update needs a fresh `SyncToken`** — always `get<Entity>` first, copy its
`SyncToken` into the body, then `save<Entity>`. A stale token → HTTP 400
("stale object").
- `minorversion` defaults to `"75"`; pass `""` to omit.
- QBO returns errors as an `ErrorResponse` whose list field is `Fault.Error_` —
note the trailing underscore, `Error` being reserved — so surface
`Fault.Error_[0].Message` to the caller; never blind-retry a write.
- Sandbox vs production: point the client host at
`sandbox-quickbooks.api.intuit.com` for the Intuit sandbox company during
development (edit the server in `Config`), and `quickbooks.api.intuit.com` for
production.
© caffeinelabs · Apache-2.0 · caffeinelabs/skills