The batch endpoint: up to 30 creates, updates, deletes and queries in one request. Items run in order and each succeeds or fails on its own; a failed item does not roll the others back.
::b ::quickbooks::batch
results ::b/batch([
::b/create-item("Customer", {DisplayName: "Acme Corp"}),
::b/update-item("Invoice", {Id: "130", SyncToken: "2", sparse: true, DueDate: "2026-12-31"}),
::b/delete-item("Bill", "88", "0"),
::b/query-item("select * from Vendor where Active = true")
])
failed filter(results, (r) { not(r.ok) })
Intuit allows about 40 batch requests a minute per company. A batch is not idempotent: retrying a partly applied batch can repeat its creates, so check each result before resubmitting.
Values
OPERATIONS
OPERATIONS: Vec [
"create",
"update",
"delete"
]
Functions
batch
fn (items: Vec): Vec
fn (items: Vec, opts: Map): Vec
POST /batch: run up to 30 items and return their item-results. The
call itself Errs only for request-level failures (auth, throttling, a
malformed batch).
Example
results ::quickbooks::batch/batch([
::quickbooks::batch/create-item("Customer", {DisplayName: "Acme Corp"}),
::quickbooks::batch/query-item("select * from Vendor where Active = true")
], {realm-id: "9341453"})
// A failed item does not fail the call
failed filter(results, (r) { not(r.ok) })
map(failed, %.message)
build-batch
fn (items: Vec): Map
The batch request body {BatchItemRequest: [...]} (pure). Items
without a bId get their 1-based position. Errs when there are no
items, more than 30, a repeated bId, or an item whose entity does
not support its operation.
Example
::quickbooks::batch/build-batch([::quickbooks::batch/query-item("select * from Vendor")])
// {BatchItemRequest: [{Query: "select * from Vendor", bId: "1"}]}
is-err(::quickbooks::batch/build-batch([])) // true
create-item
fn (entity: Str, body: Map): Map
fn (entity: Str, body: Map, bid: Str?): Map
A batch create for entity with body. bid (optional) names the item
in the results; items without one are numbered in order.
Example
::quickbooks::batch/create-item("Customer", {DisplayName: "Acme Corp"})
// {operation: "create", entity: "Customer", body: {DisplayName: "Acme Corp"}}
::quickbooks::batch/create-item("Customer", {DisplayName: "Acme Corp"}, "acme").bId // "acme"
delete-item
fn (entity: Str, id: Str | Int, sync-token: Str | Int): Map
fn (entity: Str, id: Str | Int, sync-token: Str | Int, bid: Str?): Map
A batch delete of a transaction by Id and current SyncToken.
Example
::quickbooks::batch/delete-item("Bill", "88", "0")
// {operation: "delete", entity: "Bill", body: {Id: "88", SyncToken: "0"}}
item-result
fn (item: Map): Map
One BatchItemResponse as {bid, ok, entity, value, message, errors}:
entity is the entity name (or "QueryResponse"), value the entity
or query response, and for a failed item message is readable and
errors lists each {message, detail, code, element}.
Example
::quickbooks::batch/item-result({bId: "1", Invoice: {Id: "130"}})
// {bid: "1", ok: true, entity: "Invoice", value: {Id: "130"}}
failed ::quickbooks::batch/item-result({bId: "2", Fault: {type: "ValidationFault", Error: [{Message: "Stale Object Error", code: "5010"}]}})
failed.ok // false
failed.message // "quickbooks: batch item 2 failed: ValidationFault: Stale Object Error"
parse-results
fn (body: Map): Vec
Every item of a batch response body as an item-result, in response
order.
Example
body {BatchItemResponse: [
{bId: "1", Customer: {Id: "58"}},
{bId: "2", Fault: {type: "ValidationFault", Error: [{Message: "Stale Object Error"}]}}
]}
map(::quickbooks::batch/parse-results(body), %.ok) // [true, false]
query-item
fn (q: Str): Map
fn (q: Str, bid: Str?): Map
A batch query (select ...; STARTPOSITION/MAXRESULTS allowed).
Example
::quickbooks::batch/query-item("select * from Vendor") // {Query: "select * from Vendor"}
::quickbooks::batch/query-item("select * from Vendor", "vendors").bId // "vendors"
update-item
fn (entity: Str, body: Map): Map
fn (entity: Str, body: Map, bid: Str?): Map
A batch update. body carries Id and SyncToken; add sparse: true
to change only the fields given.
Example
item ::quickbooks::batch/update-item("Invoice", {Id: "130", SyncToken: "2", sparse: true, DueDate: "2026-12-31"})
item.operation // "update"
item.body.DueDate // "2026-12-31"
wire-item
fn (item: Map): Map
Check one item and turn it into its wire form ({bId, operation, Invoice: {...}} or {bId, Query}), or an Err.
Example
::quickbooks::batch/wire-item(::quickbooks::batch/delete-item("Bill", "88", "0"))
// {operation: "delete", Bill: {Id: "88", SyncToken: "0"}}
is-err(::quickbooks::batch/wire-item(::quickbooks::batch/delete-item("Customer", "58", "1"))) // true