connector-quickbooks

quickbooks-client

Motoko bindings for a curated slice of the QuickBooks Online Accounting API v3: 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

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>", "cust@example.com", "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.*