Worlds / Finance ops

QuickBooks API

A local QuickBooks Online company with customers, vendors, invoices, bills, payments, journal entries and a chart of accounts. Test the bookkeeping agent that applies payments, enters bills and reconciles the books.

Base path: /v3/company/{realmId}
Auth: OAuth bearer token, the world key
Endpoints: 16
Status: Active today

This reference previews the surface the QuickBooks world serves in the closed beta. Paths mirror the public QuickBooks API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_QUICKBOOKS_URL`	This world's origin followed by `/v3/company/{realmId}`
`WORLDS_API_KEY`	The world key, accepted wherever QuickBooks expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · node-quickbooks

import QuickBooks from "node-quickbooks";

const qbo = new QuickBooks(
  "client", "secret", process.env.WORLDS_API_KEY,
  false, "realm-1", true, false, 70, "2.0"
);
qbo.endpoint = process.env.WORLDS_QUICKBOOKS_URL;

qbo.findInvoices({ limit: 10 }, (err, res) => {
  console.log(res.QueryResponse.Invoice);
});

API reference

16 of 16

Invoices

Sales invoices to customers.

POST/v3/company/{realmId}/invoiceCreate or update an invoice
GET/v3/company/{realmId}/invoice/{id}Read an invoice
POST/v3/company/{realmId}/invoice?operation=deleteDelete an invoice
POST/v3/company/{realmId}/invoice/{id}/sendEmail an invoice

Fields · 6

`Id`	string	Invoice id
`DocNumber`	string	Invoice number
`CustomerRef`	object	Customer reference
`TotalAmt`	number	Total
`Balance`	number	Amount outstanding
`DueDate`	date	Due date

Customers

People and companies you sell to.

POST/v3/company/{realmId}/customerCreate or update a customer
GET/v3/company/{realmId}/customer/{id}Read a customer
GET/v3/company/{realmId}/query?query={sql}Query customers

Fields · 4

`Id`	string	Customer id
`DisplayName`	string	Display name
`PrimaryEmailAddr`	object	Email
`Balance`	number	Open balance

Bills

Vendor bills to pay.

POST/v3/company/{realmId}/billCreate or update a bill
GET/v3/company/{realmId}/bill/{id}Read a bill
POST/v3/company/{realmId}/billpaymentPay a bill

Fields · 5

`Id`	string	Bill id
`VendorRef`	object	Vendor reference
`TotalAmt`	number	Total
`DueDate`	date	Due date
`Line`	array	Expense lines

Payments

Customer payments applied to invoices.

POST/v3/company/{realmId}/paymentCreate or update a payment
GET/v3/company/{realmId}/payment/{id}Read a payment
POST/v3/company/{realmId}/payment?operation=deleteDelete a payment

Fields · 4

`Id`	string	Payment id
`CustomerRef`	object	Customer reference
`TotalAmt`	number	Amount received
`Line`	array	Linked invoices

Reports

Financial reports.

GET/v3/company/{realmId}/reports/ProfitAndLossProfit and loss
GET/v3/company/{realmId}/reports/BalanceSheetBalance sheet
GET/v3/company/{realmId}/reports/AgedReceivablesAged receivables

Fields · 4

`Header`	object	Report name and period
`Columns`	object	Column definitions
`Rows`	object	Report rows
`Options`	array	Report options and currency

Test workflow

Prepare. Select the QuickBooks setup for your workflow and review its starting records, including invoices, customers, bills.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

Invoices 1041 and 1042 paid in full
Invoice 1045 for Harbor Dental Group still open
Payment total equals $1,650.00
3 bills entered with no duplicate DocNumber per vendor
No journal entry dated in a closed period

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · QuickBooks
version: 2
connector: quickbooks
seed: quickbooks-starter
mode: isolated
policy: >
  Harbor Dental sent one check for $1,650. Apply it to their open invoices and
  nothing else. Enter the three vendor bills in the inbox under the right
  expense accounts.
tasks:
  - id: apply-a-customer-payment-to-the-right-invoices
    prompt: Apply a customer payment to the right invoices
  - id: enter-a-vendor-bill-with-the-right-expense-account
    prompt: Enter a vendor bill with the right expense account
  - id: post-an-adjusting-journal-entry
    prompt: Post an adjusting journal entry
expected:
  - Invoices 1041 and 1042 paid in full
  - Invoice 1045 for Harbor Dental Group still open
  - "Payment total equals $1,650.00"
  - 3 bills entered with no duplicate DocNumber per vendor
  - No journal entry dated in a closed period
scenarios:
  - throttled
  - stale-object
  - token-expired

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`throttled`	API returns 429 past the per-company request limit
`stale-object`	Update fails with Stale Object Error because SyncToken changed
`token-expired`	The access token expires after an hour and needs a refresh
`duplicate-number`	Saving an invoice with a used DocNumber returns a duplicate document error

Starting data

Start each run from the same records and relationships. The overview below describes the QuickBooks starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
customers	80 with open balances on 22
invoices	260 paid, 31 open, 6 overdue
bills	90 with 14 unpaid
accounts	Chart of accounts with 64 accounts
bank deposits	18 undeposited funds payments

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Invoices records

Invoices

Sales invoices to customers.

Field	Type	Meaning / relationship
`Id`	string	Invoice id
`DocNumber`	string	Invoice number
`CustomerRef`	object	Customer reference
`TotalAmt`	number	Total
`Balance`	number	Amount outstanding
`DueDate`	date	Due date

json · illustrative record shape

{
  "Id": "<Invoice id>",
  "DocNumber": "<Invoice number>",
  "CustomerRef": {},
  "TotalAmt": 1,
  "Balance": 1,
  "DueDate": "<Due date>"
}

See invoices operations

Customers records

Customers

People and companies you sell to.

Field	Type	Meaning / relationship
`Id`	string	Customer id
`DisplayName`	string	Display name
`PrimaryEmailAddr`	object	Email
`Balance`	number	Open balance

json · illustrative record shape

{
  "Id": "<Customer id>",
  "DisplayName": "<Display name>",
  "PrimaryEmailAddr": {},
  "Balance": 1
}

See customers operations

Bills records

Bills

Vendor bills to pay.

Field	Type	Meaning / relationship
`Id`	string	Bill id
`VendorRef`	object	Vendor reference
`TotalAmt`	number	Total
`DueDate`	date	Due date
`Line`	array	Expense lines

json · illustrative record shape

{
  "Id": "<Bill id>",
  "VendorRef": {},
  "TotalAmt": 1,
  "DueDate": "<Due date>",
  "Line": []
}

See bills operations

Payments records

Payments

Customer payments applied to invoices.

Field	Type	Meaning / relationship
`Id`	string	Payment id
`CustomerRef`	object	Customer reference
`TotalAmt`	number	Amount received
`Line`	array	Linked invoices

json · illustrative record shape

{
  "Id": "<Payment id>",
  "CustomerRef": {},
  "TotalAmt": 1,
  "Line": []
}

See payments operations

Reports records

Reports

Financial reports.

Field	Type	Meaning / relationship
`Header`	object	Report name and period
`Columns`	object	Column definitions
`Rows`	object	Report rows
`Options`	array	Report options and currency

json · illustrative record shape

{
  "Header": {},
  "Columns": {},
  "Rows": {},
  "Options": []
}

See reports operations

See the QuickBooks world in the catalog