QuickBooks Online simulator

quickbooks-twin is a local, stateful simulator of the QuickBooks Online Accounting API for testing accounting code. Customers, the list entities, fourteen transactions and the company’s CompanyInfo keep QuickBooks’ envelopes, SyncToken checks and faults, in JSON at minorversion 75. Expect QuickBooks Online’s own field defaults, fault codes and update rules everywhere except where a Differs from QuickBooks line or Limitations names a gap. It never calls Intuit, moves no money and sends no email, so no test record lands in a real company file.

Quickstart

Install the CLI, sign in and boot the simulator with RYSTIC_URL pointing at it.

On Pro you sign in with an API key from your account .

curl -fsSL https://www.rystic.ai/install.sh | sh
rystic login rys_…   # your API key
export RYSTIC_URL=$(rystic run quickbooks-twin -d --port 0 --scenario quickbooks_customer_ledger --json | jq -r .data.url)
curl -s "$RYSTIC_URL/_rystic/version"
# -> {..."product":"quickbooks-twin"...}

On Enterprise, the licensed edition signs in with a license file in place of the key: rystic login ./rystic-license.json (licensing ).

First calls

Every path names the default scenario’s realm, 4620816365320737870. Read a customer, change one field with a sparse update that names its current SyncToken and read it back:

R=4620816365320737870
curl -s "$RYSTIC_URL/v3/company/$R/customer/1" -H 'Authorization: Bearer placeholder' | jq -c '.Customer | {Id, DisplayName, Balance, SyncToken}'
# -> {"Id":"1","DisplayName":"Amy's Bird Sanctuary","Balance":239,"SyncToken":"3"}
curl -s "$RYSTIC_URL/v3/company/$R/customer?minorversion=75" -H 'Authorization: Bearer placeholder' -H 'Content-Type: application/json' -d '{"Id":"1","SyncToken":"3","sparse":true,"Notes":"Prefers morning delivery"}' | jq -c '.Customer | {Id, Notes, SyncToken}'
# -> {"Id":"1","Notes":"Prefers morning delivery","SyncToken":"4"}
curl -s "$RYSTIC_URL/v3/company/$R/customer/1" -H 'Authorization: Bearer placeholder' | jq -c '.Customer | {Id, Notes, SyncToken}'
# -> {"Id":"1","Notes":"Prefers morning delivery","SyncToken":"4"}

Connect your client

Point your client at $RYSTIC_URL in place of https://sandbox-quickbooks.api.intuit.com or https://quickbooks.api.intuit.com; the /v3/company/{realmId}/… paths stay as they are, and any non-empty access token works. Node, with node-quickbooks:

const QuickBooks = require("node-quickbooks");

QuickBooks.V3_ENDPOINT_BASE_URL = `${process.env.RYSTIC_URL}/v3/company/`;
const qbo = new QuickBooks(
  "placeholder", "placeholder", "placeholder", false,
  "4620816365320737870", true, false, 75, "2.0", "placeholder",
);
qbo.getCustomer("1", (err, customer) => {
  if (err) throw new Error(JSON.stringify(err));
  console.log(customer.DisplayName);
});

Python, with python-quickbooks:

import os

from intuitlib.client import AuthClient
from quickbooks import QuickBooks
from quickbooks.objects.customer import Customer

os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"
QuickBooks.sandbox_api_url_v3 = os.environ["RYSTIC_URL"] + "/v3"
auth = AuthClient("placeholder", "placeholder", "http://localhost/callback", "sandbox")
auth.access_token = "placeholder"
auth.refresh_token = "placeholder"
client = QuickBooks(auth_client=auth, company_id="4620816365320737870", minorversion=75)
print(Customer.get(1, qb=client).DisplayName)

The simulator serves plain HTTP, which python-quickbooks refuses without OAUTHLIB_INSECURE_TRANSPORT. For another library, set its base URL as Point your client at it describes. Without the intercept gateway, a library that keeps Intuit’s host talks to Intuit.

No client has been checked against this simulator yet.

Auth

Send Authorization: Bearer <token> with any non-empty OAuth 2.0 token.

A request with no bearer token returns 401 with code 3200 and type AuthenticationFault. That covers no Authorization header, an empty token or another scheme such as Basic. The envelope depends on the route, so assert on the status and the code only:

{"attachableResponse":[],"batchItemResponse":[],"cdcresponse":[],"fault":{"error":[{"code":"3200","detail":"Token expired or invalid","element":null,"message":"AuthenticationFailed"}],"type":"AuthenticationFault"},"intuitObject":null,"queryResponse":null,"report":null,"requestId":null,"status":null,"syncErrorResponse":null,"time":1768780800001,"warnings":null}

No OAuth route is served: send a placeholder in place of minting a token. Because the simulator checks no token, it cannot exercise your token-refresh path.

Differs from QuickBooks: the simulator never refuses a token as expired, revoked or short of a scope. Its only 403 is a CompanyInfo read of a realm with no seeded company.

API version

The simulator serves every request as minorversion 75, reads no minorversion parameter and sends no version header. A request that names another value, or none, gets the same shapes. Pass minorversion=75 in your client anyway, as both libraries above do, so your code asks for what the simulator serves.

Errors and limits

Error format

Most refusals return a 400 whose body is a Fault holding type and an Error array, beside a time. Each error has code, Message, Detail and element, the field it names or empty. Assert on the status, type and code rather than the Detail text. A behavior marked (unconfirmed) has not been checked against QuickBooks. How a read refuses an Id:

A write body that does not parse as JSON returns 400 ValidationFault code 6240, before the token is checked. Its body is the duplicate-name fault, Message Duplicate Name Exists Error, with a fixed time; whether QuickBooks returns the same fault is unconfirmed.

An unserved route returns the simulator’s own 404, and a 401 has its own envelope (Auth).

Rate limits

Network profiles send a 429 you shape, with the body and headers you choose; the simulator counts no requests and never returns 429 on its own (Limitations).

Pagination

Not applicable: listing and search go through QuickBooks’ query endpoint, which Limitations lists as not served, so read each record by its Id.

Idempotency

A ?requestid=<id> replays a write only on the entities in the table’s first row. On every other entity a retry writes again (Limitations):

On the first row’s entities, a requestid another entity stored replays that entity’s response (Limitations). A requestid longer than 50 characters returns 400 ValidationFault code 6000 on Customer, Vendor, Item, Class and Term writes.

A stale SyncToken on an update or an invoice void returns 400 ValidationFault code 5010, so sending one update twice fails the second time unless an entity in the table’s first row replays it.

A delete (?operation=delete) of a Bill, BillPayment, CreditMemo, Deposit, Invoice, JournalEntry, Payment, Purchase, PurchaseOrder, RefundReceipt or Transfer succeeds with a stale SyncToken, as QuickBooks does. An Estimate, SalesReceipt or VendorCredit delete with a stale SyncToken returns 400 ValidationFault code 5010 (unconfirmed).

Coverage

The simulator serves customers, the list entities, the TaxCode and TaxRate reads, fourteen transactions, CompanyInfo and the report reads under /v3/company/{realmId}/, in JSON. The query endpoint, batch, change data capture, webhooks, XML and the transactions’ PDF reads and email sends are out of scope.

On 2026-11-07, the simulator matched QuickBooks Online on 491 of the 538 tests that compare the two (91.3%), and 2 of them gave no verdict.

96 routes, counted from the simulator’s route table.

Feed effects. No write emits a feed effect; watch requests instead. Each call appears on the event feed (/_rystic/events) as a request event, and reading the record back shows what it changed.

Scenarios

The simulator ships 5 scenarios; the quickstart boots quickbooks_customer_ledger.

What each scenario holds:

• quickbooks_customer_ledger: Two paid up, five with open balances and one whose BalanceWithJobs is above its own Balance, so customer and CompanyInfo reads return records before any write.
• quickbooks_fresh_books: Settings configured, one customer with a zero balance and one stored requestid.
• quickbooks_inactive_archive: Four of five deactivated, one of them with an open balance.
• quickbooks_job_hierarchy: A parent with two jobs, one a Project and one with a job of its own two levels deep, plus a flat customer, so ParentRef, Level and BillWithParent reads have targets.
• quickbooks_replay_desk: A create, an update, a deactivation and a validation fault, against three customers. A customer write stores its requestid but never replays it.

Boot one by name, or load one into a running simulator:

rystic run quickbooks-twin -d --port 0 --scenario quickbooks_customer_ledger
curl -s -X POST "$RYSTIC_URL/_rystic/scenario" -d '{"name":"quickbooks_customer_ledger"}'

What the scenarios do not hold

• No list entity or transaction: each scenario seeds one company and its customers, so create an account, an item or a vendor with the API before a transaction references it (Transactions and list entities).
• One tax code, one tax rate and one tax agency only. Every scenario’s customers name tax code 2 in DefaultTaxCodeRef, that code lists rate 1, and the rate names agency 1, the only agency_id TaxSummary accepts. Seed more in state_taxcode, state_taxrate and state_taxagency (Seeding state).
• Without --scenario, the simulator boots with no records, and the CompanyInfo read returns 403 AuthorizationFault.

Seeding state

Each entity is one register named state_<entity>, such as state_customer, state_vendor or state_invoice. A register keys its records by Id, except state_company_info, which is keyed by realm id. state_request_dedup keys each stored response by its requestid, as {"requestid": "…", "response": {…}}, and a replay returns response as its body. Seed a company under its realm id, with realmId in the record too, and a customer, then read them back:

curl -s -X POST "$RYSTIC_URL/_rystic/seed" -d '{"state_company_info":{"9341452000000001":{"realmId":"9341452000000001","Id":"1","CompanyName":"Example Co"}},"state_customer":{"100":{"Id":"100","DisplayName":"Seeded Customer","SyncToken":"0","Active":true}}}'
curl -s "$RYSTIC_URL/v3/company/9341452000000001/companyinfo/9341452000000001" -H 'Authorization: Bearer placeholder' | jq -c '.CompanyInfo | {Id, CompanyName, LegalName, NameValue}'
# -> {"Id":"1","CompanyName":"Example Co","LegalName":"Company 9341452000000001","NameValue":[]}
curl -s "$RYSTIC_URL/v3/company/9341452000000002/companyinfo/9341452000000002" -H 'Authorization: Bearer placeholder' | jq -c '.Fault | {type, code: .Error[0].code}'
# -> {"type":"AuthorizationFault","code":"3100"}
curl -s "$RYSTIC_URL/v3/company/9341452000000001/customer/100" -H 'Authorization: Bearer placeholder' | jq -c '.Customer | {Id, DisplayName, SyncToken}'
# -> {"Id":"100","DisplayName":"Seeded Customer","SyncToken":"0"}

{companyId} selects nothing. A field the seeded company leaves out is filled in: CompanyName and LegalName become Company <realmId>, and NameValue is empty. Registers lists each register’s fields, and Scenarios and seeding covers the seed response, refusals, boot files and the seed gate.

Features

Each feature has its own page:

• Customers: The customer lifecycle QuickBooks applies: create, read, sparse and full update, deactivate and reactivate, with SyncToken checks, name rules and stored sub-customers.
• Transactions and list entities: Vendors, items, accounts and the other list entities, and fourteen transactions from Invoice to Transfer, with delete, void and the amounts each keeps.

Determinism and reset

Each entity numbers its records from 1, except Class, which starts at 5000000000000007280. The V4IDPseudonym sequence starts at 000000000000000000000001. The clock moves one millisecond for each request that renders a time, reads included.

The simulator renders the times it writes at a fixed offset:

It writes MetaData.CreateTime and MetaData.LastUpdatedTime to the second. A customer response’s time is to the second too, and a CompanyInfo response’s time to the millisecond. A 401’s time format depends on the route; see Auth.

Reset and determinism covers reset, the clock and the RNG.

Limitations

Known issues.

• A requestid is shared across entities: a write replays whatever another entity stored under the same id, where QuickBooks scopes it to the request.
• No request rate is enforced, where QuickBooks throttles each realm’s requests with 429.
• A retried requestid writes again on every entity but Item, Invoice, Estimate, CreditMemo, Deposit, VendorCredit and Term, where QuickBooks returns the stored response.

Beyond the known issues, 57 of the 153 operations in the published spec are not served, 3 success responses may leave out fields the spec requires, 470 documented responses have no test yet and 325 behaviors are not modeled. The details follow.

By design.

• No realm isolation. A read selects by Id without checking the realm in its path. Creating a record under a realm id that is not all digits returns 404 with an empty body, and so do the customer, CompanyInfo, Bill, PaymentMethod, PurchaseOrder and SalesReceipt reads. Every other read serves any realm id. Voiding a BillPayment returns that 404 under a realm id of fewer than 10 digits or of one repeated digit.

  Differs from QuickBooks: QuickBooks scopes every record to its realm.

• Bodies are read as JSON whatever their Content-Type. An XML body returns the unparsable-body refusal (Error format).

Release notes: Changelog