QuickBooks Batch API

openapi: 3.2.0
info:
  title: QuickBooks Online Accounting Batch API
  version: '2026-11-05'
  description: QuickBooks Online Accounting API (v3). Entities, reports, query, batch and change-data-capture operations for a QuickBooks Online company (realmId). Generated from the JSON Intuit's API Explorer renders; Intuit publishes no OpenAPI document.
  termsOfService: https://developer.intuit.com/app/developer/qbo/docs/legal-agreements/intuit-terms-of-service-for-intuit-developer-services
  contact:
    name: Intuit Developer Support
    url: https://help.developer.intuit.com/s/
  x-generated-from: documentation
  x-generator: convert-intuit-api-explorer.py (deterministic conversion of the provider's API Explorer JSON; no model)
  x-source:
  - https://static.developer.intuit.com/JSONObjects/EntityJsonObject_v1.json
  - https://static.developer.intuit.com/JSONObjects/CodesModelsJsonObjects_v2.json
  - https://static.developer.intuit.com/JSONObjects/TocJsonObject_v1.json
  x-generated: '2026-11-05'
servers:
- url: https://quickbooks.api.intuit.com
  description: Production
- url: https://sandbox-quickbooks.api.intuit.com
  description: Sandbox
security:
- oauth2:
  - com.intuit.quickbooks.accounting
tags:
- name: Batch
  description: The batch operation enables an application to perform multiple operations in a single request. For example, in a single batch request an application can create a customer, update an invoice, and read an account. Compared to multiple requests, a single batch request can improve an application's performance by decreasing network roundtrips and increasing throughput. The individual operations within a batch request are called BatchItemRequest objects.
paths:
  /v3/company/{realmID}/batch:
    post:
      operationId: defaultBatch
      summary: Sample batch request
      tags:
      - Batch
      x-source: https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/batch
      x-intuit-operation: POST /v3/company/<realmID>/batch
      parameters:
      - name: realmID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/batchrequest'
            example:
              BatchItemRequest:
              - bId: bid1
                Vendor:
                  DisplayName: Smith Family Store
                operation: create
              - bId: bid2
                operation: delete
                Invoice:
                  SyncToken: '0'
                  Id: '129'
              - SalesReceipt:
                  PrivateNote: A private note.
                  SyncToken: '0'
                  domain: QBO
                  Id: '11'
                  sparse: true
                bId: bid3
                operation: update
              - Query: select * from SalesReceipt where TotalAmt > '300.00'
                bId: bid4
        required: true
        description: The request on the right includes four BatchItemRequest objects.
      responses:
        '200':
          description: Some content has been omitted in order to showcase the overall BatchItemRequest object structure.
          content:
            application/json:
              schema: {}
              example:
                BatchItemResponse:
                - Fault:
                    type: ValidationFault
                    Error:
                    - Message: Duplicate Name Exists Error
                      code: '6240'
                      Detail: "The name supplied already exists. : Another customer, vendor or employee is already using this \nname. Please use a different name."
                      element: ''
                  bId: bid1
                - Fault:
                    type: ValidationFault
                    Error:
                    - Message: Object Not Found
                      code: '610'
                      Detail: 'Object Not Found : Something you''re trying to use has been made inactive. Check the fields with accounts, customers, items, vendors or employees.'
                      element: ''
                  bId: bid2
                - Fault:
                    type: ValidationFault
                    Error:
                    - Message: Stale Object Error
                      code: '5010'
                      Detail: 'Stale Object Error : You and root were working on this at the same time. root finished before you did, so your work was not saved.'
                      element: ''
                  bId: bid3
                - bId: bid4
                  QueryResponse:
                    SalesReceipt:
                    - TxnDate: '2015-08-25'
                      domain: QBO
                      CurrencyRef:
                        name: United States Dollar
                        value: USD
                      PrintStatus: NotSet
                      PaymentRefNum: '10264'
                      TotalAmt: 337.5
                      Line:
                      - Description: Custom Design
                        DetailType: SalesItemLineDetail
                        SalesItemLineDetail:
                          TaxCodeRef:
                            value: NON
                          Qty: 4.5
                          UnitPrice: 75
                          ItemRef:
                            name: Design
                            value: '4'
                        LineNum: 1
                        Amount: 337.5
                        Id: '1'
                      - DetailType: SubTotalLineDetail
                        Amount: 337.5
                        SubTotalLineDetail: {}
                      ApplyTaxAfterDiscount: false
                      DocNumber: '1003'
                      PrivateNote: A private note.
                      sparse: false
                      DepositToAccountRef:
                        name: Checking
                        value: '35'
                      CustomerMemo:
                        value: Thank you for your business and have a great day!
                      Balance: 0
                      CustomerRef:
                        name: Dylan Sollfrank
                        value: '6'
                      TxnTaxDetail:
                        TotalTax: 0
                      SyncToken: '1'
                      PaymentMethodRef:
                        name: Check
                        value: '2'
                      EmailStatus: NotSet
                      BillAddr:
                        Lat: INVALID
                        Long: INVALID
                        Id: '49'
                        Line1: Dylan Sollfrank
                      MetaData:
                        CreateTime: '2015-08-27T14:59:48-07:00'
                        LastUpdatedTime: '2016-04-15T09:01:10-07:00'
                      CustomField:
                      - DefinitionId: '1'
                        Type: StringType
                        Name: 'Crew #'
                      Id: '11'
                    startPosition: 1
                    maxResults: 1
                time: '2016-04-15T09:01:18.141-07:00'
        '400':
          $ref: '#/components/responses/Fault'
        '401':
          $ref: '#/components/responses/Fault'
        '429':
          $ref: '#/components/responses/Throttled'
      security:
      - oauth2:
        - com.intuit.quickbooks.accounting
components:
  schemas:
    IntuitFault:
      type: object
      properties:
        Fault:
          type: object
          properties:
            type:
              type: string
              enum:
              - ValidationFault
              - SystemFault
              - AuthenticationFault
              - AuthorizationFault
            Error:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  element:
                    type: string
                  Message:
                    type: string
                  Detail:
                    type: string
        time:
          type: string
          format: date-time
    batchrequest:
      type: object
      title: batchrequest
      properties:
        BatchItemRequest:
          allOf:
          - $ref: '#/components/schemas/batchitemrequest'
          description: A wrapper around all request objects for this batch operation.
          x-intuit-required: Required
      required:
      - BatchItemRequest
    batchitemrequest:
      type: object
      title: batchitemrequest
      properties:
        optionsData:
          type: string
          description: 'Use for the void operation for those resources that support it. Must be supplied with operation set to update.

            Valid value: void. Required for void operations.'
          x-intuit-required: Conditionally required
        bId:
          type: string
          description: Unique identifier for the batch item.
          x-intuit-required: Required
        Query:
          type: string
          description: The SELECT statement for the query. When Query is defined, do not define the operation attribute.
          x-intuit-required: Optional
        operation:
          type: string
          description: 'The operation to perform with the supplied request object payload. Do not use if this  batchitemrequest object is for a query operation.

            Valid values include: create, update, delete Required for create, update, and delete.'
          x-intuit-required: Conditionally required
        resourceName:
          type: object
          x-intuit-type: Request object
          description: The payload for the request for create, update, and delete operations.
          x-intuit-required: Optional
      required:
      - bId
  responses:
    Fault:
      description: Error. The body carries a Fault element (type ValidationFault, SystemFault, AuthenticationFault or AuthorizationFault) with one or more Error entries (code, element, Message, Detail).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IntuitFault'
    Throttled:
      description: 'HTTP 429: the request was throttled. Wait 60 seconds before retrying.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IntuitFault'
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'Intuit OAuth 2.0 (authorization code). Discovery: https://developer.api.intuit.com/.well-known/openid_configuration'
      flows:
        authorizationCode:
          authorizationUrl: https://appcenter.intuit.com/connect/oauth2
          tokenUrl: https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer
          refreshUrl: https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer
          scopes:
            com.intuit.quickbooks.accounting: Grants access to the QuickBooks Online Accounting API, which focuses on accounting data.
            com.intuit.quickbooks.payment: Grants access to the QuickBooks Payments API, which focuses on payments processing.
            openid: Grants access to OpenID Connect features.
            profile: User's given and family names info
            email: User's email address
            phone: User's phone number
            address: User's physical address
x-generated-from: documentation
x-provenance:
  method: generated
  generated: '2026-11-05'
  source: https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account
  note: Converted from the JSON the developer.intuit.com API Explorer loads (static.developer.intuit.com/JSONObjects). Intuit publishes no OpenAPI document; this is a faithful machine transformation of its own reference data, graded as generated.