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

{
  "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

{
  "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 — or let ?requestid= do it for you: each write item is remembered as requestid:bId, so resending the same envelope replays settled items and runs only the rest. See Safe retries (requestid max 36 characters, bId max 10 when it is used).

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.
• Void: send operation: "update" with optionsData: "void" and the record's Id + SyncToken (QBO's spelling; operation: "void" also works). It runs the same pipeline as ?operation=void.
• Any other optionsData 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 item that was in flight gets its own fault — AGENT_OFFLINE if it was never sent, AGENT_TIMEOUT if it was sent and the answer never came back (it may have applied; re-query before retrying it, or resend with a requestid — see Safe retries). Every item after it gets AGENT_OFFLINE: it was never sent, so it is safe to resend. If the agent was offline from the start, the whole request is a 503.

See also

• Error codes — BATCH_INVALID_REQUEST, BATCH_TOO_MANY_ITEMS, BATCH_UNSUPPORTED_OPTION in full, with causes and fixes.
• Change Data Capture — the other multi-item platform endpoint, with the same per-item fault-isolation model.