Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add caffeinelabs/skills --skill connector-quickbooks -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/connector-quickbooks/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/connector-quickbooks/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set33

The whole set →
connector-x connector-x — a skill for Claude Code, Codex, Cursor and other tools. Guides canister development for X API v2 integrations using the x-client package and user PKCE OAuth 2.0. CX Codex +1 11,600installs connector-weatherapi The connector-weatherapi skill pins down the supported way to read weather in Caffeine builds: the weatherapi-client mops package instead of hand-rolled ic.http_request calls. CX Codex +1 11,400installs connector-spotify connector-spotify — a skill for Caffeine builds on Motoko: routes Spotify Web API work through the spotify-client mops package and rules out hand-rolled HTTP calls. CX Codex +1 10,700installs connector-tmdb connector-tmdb — a skill for working with movie, TV show and cast data via The Movie Database API in Motoko projects on Internet Computer. CX Codex +1 10,300installs migrating-motoko-actors migrating-motoko-actors guides actor state migrations across canister upgrades and stable schema changes through the migration chain in migrations/. CX Codex +1 8,600installs troubleshooting-motoko-migrations troubleshooting-motoko-migrations is a Claude Code skill for Motoko migration-chain errors when diagnostics disagree with main.mo or migration-file edits have no effect. CX Codex +1 8,600installs writing-motoko writing-motoko is a Claude Code skill that provides Motoko, architecture, and mops guidance for building Internet Computer backends. CX Codex +1 8,600installs extension-http-endpoints extension-http-endpoints configures inbound HTTPS endpoints for Motoko canisters on the Internet Computer. Useful for Stripe webhooks, Telegram bot callbacks, and plain health checks. CX Codex +1 7,200installs

Project sponsors

Companies that keep this analytics open