Batch operations

One POST /v3/company/{realmId}/batch call runs up to 30 operations — creates, updates, deletes, and queries — and returns one response slot per item, keyed by your bId.

POST /v3/company/:realmId/batch

Same Bearer auth as every other endpoint.

Request

json

{
  "BatchItemRequest": [
    { "bId": "bid1", "operation": "create", "Customer": { "DisplayName": "Acme Corp" } },
    {
      "bId": "bid2",
      "operation": "update",
      "Invoice": {
        "Id": "1F00-1",
        "SyncToken": "0",
        "CustomerMemo": { "value": "Thanks for your business!" }
      }
    },
    { "bId": "bid3", "operation": "delete", "Invoice": { "Id": "1F00-2", "SyncToken": "0" } },
    { "bId": "bid4", "Query": "SELECT * FROM SalesReceipt WHERE TotalAmt > '300.00'" }
  ]
}

Every item needs a unique bId — an opaque string echoed back on its slot.
An entity item is exactly one entity payload key plus operation: create | update | delete.
A query item is a Query string — the same QBO-SQL /query accepts, including STARTPOSITION/MAXRESULTS pagination.

Response

json

{
  "BatchItemResponse": [
    {
      "bId": "bid1",
      "Customer": {
        "Id": "80000001-1736100000",
        "SyncToken": "0",
        "DisplayName": "Acme Corp",
        "domain": "QBO",
        "sparse": false
      }
    },
    {
      "bId": "bid2",
      "Fault": {
        "Error": [
          {
            "Message": "Stale Object Error",
            "Detail": "QuickBooks Desktop: The provided edit sequence is out-of-date. See https://docs.tenkeybridge.com/reference/error-codes.html#5010",
            "code": "5010"
          }
        ],
        "type": "ValidationFault"
      },
      "tkb": {
        "code": "5010",
        "causes": ["A user or another integration modified the record in QuickBooks after you read it."],
        "fixes": ["GET the record again, take the fresh SyncToken, and re-apply your change."],
        "docsUrl": "https://docs.tenkeybridge.com/reference/error-codes.html#5010"
      }
    },
    {
      "bId": "bid3",
      "Invoice": { "Id": "1F00-2", "status": "Deleted", "domain": "QBO" }
    },
    {
      "bId": "bid4",
      "QueryResponse": {
        "SalesReceipt": [
          { "Id": "1F00-3", "SyncToken": "0", "TotalAmt": 425.0, "...": "full SalesReceipt payload" }
        ],
        "startPosition": 1,
        "maxResults": 1
      }
    }
  ],
  "time": "2026-07-30T18:04:11.203Z"
}

Slots come back in request order. A success slot carries exactly what the single-shot endpoint would have returned; a fault slot carries the same fault anatomy as everywhere else, tkb help block included.

Batch is not a transaction

Items execute sequentially, independently. If item 3 faults, items 1–2 have already happened and stay happened; items 4+ still run. QuickBooks Online's batch behaves the same way. Design idempotent retries per item, not per envelope.

Structural errors fail the whole request

If the envelope itself can't be understood — missing/duplicate bId, an item that isn't exactly one payload, an unknown operation, a create carrying an Id — the whole request returns 400 BATCH_INVALID_REQUEST and nothing executes. Semantic problems (unsupported entity, Desktop validation errors) fault only their own item.

Limits and honesty

30 items max (BATCH_TOO_MANY_ITEMS) — QBO's own cap, cloned.
optionsData (e.g. void) is not supported (BATCH_UNSUPPORTED_OPTION) — that item faults; the rest run.
Latency: items run one at a time through your QuickBooks Desktop machine; a 30-item batch of updates is up to 60 Desktop round trips. There is no per-request deadline — budget client timeouts accordingly.
Agent offline mid-batch: completed items keep their results; the remaining items return AGENT_OFFLINE/AGENT_TIMEOUT fault slots. If the agent was offline from the start, the whole request is a 503.

Batch operations ​

Request ​

Response ​

Batch is not a transaction ​

Structural errors fail the whole request ​

Limits and honesty ​