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