openapi: 3.1.0
info:
  title: QuickBooks Online Accounting Customers Invoices API
  description: The QuickBooks Online Accounting API is a RESTful API that provides programmatic access to QuickBooks Online company data. This specification covers core entities including invoices, customers, items, and payments, enabling developers to automate accounting workflows, synchronize financial data, and extend QuickBooks Online functionality for small and mid-sized businesses. All API calls require OAuth 2.0 authorization and a valid company ID (realmId). Responses follow the Intuit entity response envelope pattern, and the API supports minor version parameters to access newer fields and behaviors without breaking existing integrations.
  version: '75'
  termsOfService: https://developer.intuit.com/app/developer/qbo/docs/learn/terms-of-service
  contact:
    name: Intuit Developer Support
    url: https://help.developer.intuit.com
    email: developer-support@intuit.com
  license:
    name: Intuit Developer Terms of Service
    url: https://developer.intuit.com/app/developer/qbo/docs/learn/terms-of-service
  x-logo:
    url: https://developer.intuit.com/app/developer/common/imgs/IntuitDev_Logo.svg
servers:
- url: https://quickbooks.api.intuit.com/v3/company/{realmId}
  description: Production
  variables:
    realmId:
      description: The QuickBooks Online company ID (realm ID) that uniquely identifies the company dataset to operate on.
      default: '1234567890'
- url: https://sandbox-quickbooks.api.intuit.com/v3/company/{realmId}
  description: Sandbox
  variables:
    realmId:
      description: The sandbox company ID for testing and development purposes.
      default: '1234567890'
security:
- oauth2: []
tags:
- name: Invoices
  description: An Invoice represents a sales form where the customer pays for a product or service later. QuickBooks records an accounts receivable transaction for each invoice.
  externalDocs:
    url: https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/invoice
paths:
  /invoice:
    post:
      operationId: createInvoice
      summary: Create an Invoice
      description: Creates a new invoice. At minimum, the request must include a CustomerRef and at least one Line item. The TxnDate defaults to the current date if not specified. QuickBooks automatically calculates totals, tax, and balance fields.
      tags:
      - Invoices
      parameters:
      - $ref: '#/components/parameters/minorVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Invoice'
            examples:
              CreateinvoiceRequestExample:
                summary: Default createInvoice request
                x-microcks-default: true
                value:
                  Id: abc123
                  SyncToken: example_value
                  MetaData:
                    CreateTime: '2026-01-15T10:30:00Z'
                    LastUpdatedTime: '2026-01-15T10:30:00Z'
                  DocNumber: example_value
                  TxnDate: '2026-01-15'
                  DueDate: '2026-01-15'
                  PrivateNote: example_value
                  CustomerMemo:
                    value: example_value
                  CustomerRef:
                    value: example_value
                    name: Example Title
                  BillAddr:
                    Id: abc123
                    Line1: example_value
                    Line2: example_value
                    Line3: example_value
                    Line4: example_value
                    Line5: example_value
                    City: example_value
                    CountrySubDivisionCode: example_value
                    PostalCode: example_value
                    Country: example_value
                    Lat: example_value
                    Long: example_value
                  ShipAddr:
                    Id: abc123
                    Line1: example_value
                    Line2: example_value
                    Line3: example_value
                    Line4: example_value
                    Line5: example_value
                    City: example_value
                    CountrySubDivisionCode: example_value
                    PostalCode: example_value
                    Country: example_value
                    Lat: example_value
                    Long: example_value
                  BillEmail:
                    Address: example_value
                  Line:
                  - Id: abc123
                    LineNum: 10
                    Description: A sample description.
                    Amount: 42.5
                    DetailType: SalesItemLineDetail
                    LinkedTxn: {}
                  TxnTaxDetail:
                    TotalTax: 42.5
                    TaxLine:
                    - {}
                  TotalAmt: 42.5
                  Balance: 42.5
                  Deposit: 42.5
                  DepositToAccountRef:
                    value: example_value
                    name: Example Title
                  SalesTermRef:
                    value: example_value
                    name: Example Title
                  PaymentMethodRef:
                    value: example_value
                    name: Example Title
                  CurrencyRef:
                    value: example_value
                    name: Example Title
                  ExchangeRate: 42.5
                  ShipDate: '2026-01-15'
                  ShipMethodRef:
                    value: example_value
                    name: Example Title
                  TrackingNum: example_value
                  ApplyTaxAfterDiscount: true
                  PrintStatus: NotSet
                  EmailStatus: NotSet
                  GlobalTaxCalculation: TaxExcluded
                  AllowOnlinePayment: true
                  AllowOnlineCreditCardPayment: true
                  AllowOnlineACHPayment: true
                  CustomField:
                  - DefinitionId: '500123'
                    Name: Example Title
                    Type: StringType
                    StringValue: example_value
                  LinkedTxn:
                  - TxnId: '500123'
                    TxnType: Invoice
                  domain: example_value
                  sparse: true
      responses:
        '200':
          description: Invoice created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceResponse'
              examples:
                Createinvoice200Example:
                  summary: Default createInvoice 200 response
                  x-microcks-default: true
                  value:
                    Invoice:
                      Id: abc123
                      SyncToken: example_value
                      DocNumber: example_value
                      TxnDate: '2026-01-15'
                      DueDate: '2026-01-15'
                      PrivateNote: example_value
                      CustomerMemo:
                        value: example_value
                      Line:
                      - {}
                      TotalAmt: 42.5
                      Balance: 42.5
                      Deposit: 42.5
                      ExchangeRate: 42.5
                      ShipDate: '2026-01-15'
                      TrackingNum: example_value
                      ApplyTaxAfterDiscount: true
                      PrintStatus: NotSet
                      EmailStatus: NotSet
                      GlobalTaxCalculation: TaxExcluded
                      AllowOnlinePayment: true
                      AllowOnlineCreditCardPayment: true
                      AllowOnlineACHPayment: true
                      CustomField:
                      - {}
                      LinkedTxn:
                      - {}
                      domain: example_value
                      sparse: true
                    time: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /invoice/{invoiceId}:
    get:
      operationId: readInvoice
      summary: Read an Invoice
      description: Retrieves the details of an invoice that has been previously created. Supply the unique invoice ID returned from a previous create or query request.
      tags:
      - Invoices
      parameters:
      - $ref: '#/components/parameters/invoiceId'
      - $ref: '#/components/parameters/minorVersion'
      responses:
        '200':
          description: Invoice retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceResponse'
              examples:
                Readinvoice200Example:
                  summary: Default readInvoice 200 response
                  x-microcks-default: true
                  value:
                    Invoice:
                      Id: abc123
                      SyncToken: example_value
                      DocNumber: example_value
                      TxnDate: '2026-01-15'
                      DueDate: '2026-01-15'
                      PrivateNote: example_value
                      CustomerMemo:
                        value: example_value
                      Line:
                      - {}
                      TotalAmt: 42.5
                      Balance: 42.5
                      Deposit: 42.5
                      ExchangeRate: 42.5
                      ShipDate: '2026-01-15'
                      TrackingNum: example_value
                      ApplyTaxAfterDiscount: true
                      PrintStatus: NotSet
                      EmailStatus: NotSet
                      GlobalTaxCalculation: TaxExcluded
                      AllowOnlinePayment: true
                      AllowOnlineCreditCardPayment: true
                      AllowOnlineACHPayment: true
                      CustomField:
                      - {}
                      LinkedTxn:
                      - {}
                      domain: example_value
                      sparse: true
                    time: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: updateInvoice
      summary: Update an Invoice
      description: Updates an existing invoice. A full update replaces the entire entity with the data provided. The request must include the Id and SyncToken fields from the latest read of the entity. Writable fields omitted from the request body are set to NULL.
      tags:
      - Invoices
      parameters:
      - $ref: '#/components/parameters/invoiceId'
      - $ref: '#/components/parameters/minorVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Invoice'
            examples:
              UpdateinvoiceRequestExample:
                summary: Default updateInvoice request
                x-microcks-default: true
                value:
                  Id: abc123
                  SyncToken: example_value
                  MetaData:
                    CreateTime: '2026-01-15T10:30:00Z'
                    LastUpdatedTime: '2026-01-15T10:30:00Z'
                  DocNumber: example_value
                  TxnDate: '2026-01-15'
                  DueDate: '2026-01-15'
                  PrivateNote: example_value
                  CustomerMemo:
                    value: example_value
                  CustomerRef:
                    value: example_value
                    name: Example Title
                  BillAddr:
                    Id: abc123
                    Line1: example_value
                    Line2: example_value
                    Line3: example_value
                    Line4: example_value
                    Line5: example_value
                    City: example_value
                    CountrySubDivisionCode: example_value
                    PostalCode: example_value
                    Country: example_value
                    Lat: example_value
                    Long: example_value
                  ShipAddr:
                    Id: abc123
                    Line1: example_value
                    Line2: example_value
                    Line3: example_value
                    Line4: example_value
                    Line5: example_value
                    City: example_value
                    CountrySubDivisionCode: example_value
                    PostalCode: example_value
                    Country: example_value
                    Lat: example_value
                    Long: example_value
                  BillEmail:
                    Address: example_value
                  Line:
                  - Id: abc123
                    LineNum: 10
                    Description: A sample description.
                    Amount: 42.5
                    DetailType: SalesItemLineDetail
                    LinkedTxn: {}
                  TxnTaxDetail:
                    TotalTax: 42.5
                    TaxLine:
                    - {}
                  TotalAmt: 42.5
                  Balance: 42.5
                  Deposit: 42.5
                  DepositToAccountRef:
                    value: example_value
                    name: Example Title
                  SalesTermRef:
                    value: example_value
                    name: Example Title
                  PaymentMethodRef:
                    value: example_value
                    name: Example Title
                  CurrencyRef:
                    value: example_value
                    name: Example Title
                  ExchangeRate: 42.5
                  ShipDate: '2026-01-15'
                  ShipMethodRef:
                    value: example_value
                    name: Example Title
                  TrackingNum: example_value
                  ApplyTaxAfterDiscount: true
                  PrintStatus: NotSet
                  EmailStatus: NotSet
                  GlobalTaxCalculation: TaxExcluded
                  AllowOnlinePayment: true
                  AllowOnlineCreditCardPayment: true
                  AllowOnlineACHPayment: true
                  CustomField:
                  - DefinitionId: '500123'
                    Name: Example Title
                    Type: StringType
                    StringValue: example_value
                  LinkedTxn:
                  - TxnId: '500123'
                    TxnType: Invoice
                  domain: example_value
                  sparse: true
      responses:
        '200':
          description: Invoice updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceResponse'
              examples:
                Updateinvoice200Example:
                  summary: Default updateInvoice 200 response
                  x-microcks-default: true
                  value:
                    Invoice:
                      Id: abc123
                      SyncToken: example_value
                      DocNumber: example_value
                      TxnDate: '2026-01-15'
                      DueDate: '2026-01-15'
                      PrivateNote: example_value
                      CustomerMemo:
                        value: example_value
                      Line:
                      - {}
                      TotalAmt: 42.5
                      Balance: 42.5
                      Deposit: 42.5
                      ExchangeRate: 42.5
                      ShipDate: '2026-01-15'
                      TrackingNum: example_value
                      ApplyTaxAfterDiscount: true
                      PrintStatus: NotSet
                      EmailStatus: NotSet
                      GlobalTaxCalculation: TaxExcluded
                      AllowOnlinePayment: true
                      AllowOnlineCreditCardPayment: true
                      AllowOnlineACHPayment: true
                      CustomField:
                      - {}
                      LinkedTxn:
                      - {}
                      domain: example_value
                      sparse: true
                    time: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /invoice/{invoiceId}/send:
    post:
      operationId: sendInvoice
      summary: Send an Invoice via Email
      description: Sends the specified invoice via email to the address associated with the customer's BillEmail. You can override the destination email by providing a sendTo query parameter.
      tags:
      - Invoices
      parameters:
      - $ref: '#/components/parameters/invoiceId'
      - name: sendTo
        in: query
        description: Override destination email address
        schema:
          type: string
          format: email
        example: example_value
      - $ref: '#/components/parameters/minorVersion'
      responses:
        '200':
          description: Invoice sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceResponse'
              examples:
                Sendinvoice200Example:
                  summary: Default sendInvoice 200 response
                  x-microcks-default: true
                  value:
                    Invoice:
                      Id: abc123
                      SyncToken: example_value
                      DocNumber: example_value
                      TxnDate: '2026-01-15'
                      DueDate: '2026-01-15'
                      PrivateNote: example_value
                      CustomerMemo:
                        value: example_value
                      Line:
                      - {}
                      TotalAmt: 42.5
                      Balance: 42.5
                      Deposit: 42.5
                      ExchangeRate: 42.5
                      ShipDate: '2026-01-15'
                      TrackingNum: example_value
                      ApplyTaxAfterDiscount: true
                      PrintStatus: NotSet
                      EmailStatus: NotSet
                      GlobalTaxCalculation: TaxExcluded
                      AllowOnlinePayment: true
                      AllowOnlineCreditCardPayment: true
                      AllowOnlineACHPayment: true
                      CustomField:
                      - {}
                      LinkedTxn:
                      - {}
                      domain: example_value
                      sparse: true
                    time: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /invoice/{invoiceId}/void:
    post:
      operationId: voidInvoice
      summary: Void an Invoice
      description: Voids the specified invoice. The invoice remains in the system with a voided status. The request body must include the Id and SyncToken of the invoice. The operation=void parameter must also be included.
      tags:
      - Invoices
      parameters:
      - $ref: '#/components/parameters/invoiceId'
      - name: operation
        in: query
        required: true
        schema:
          type: string
          enum:
          - void
        example: void
      - $ref: '#/components/parameters/minorVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - Id
              - SyncToken
              properties:
                Id:
                  type: string
                SyncToken:
                  type: string
            examples:
              VoidinvoiceRequestExample:
                summary: Default voidInvoice request
                x-microcks-default: true
                value:
                  Id: abc123
                  SyncToken: example_value
      responses:
        '200':
          description: Invoice voided successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceResponse'
              examples:
                Voidinvoice200Example:
                  summary: Default voidInvoice 200 response
                  x-microcks-default: true
                  value:
                    Invoice:
                      Id: abc123
                      SyncToken: example_value
                      DocNumber: example_value
                      TxnDate: '2026-01-15'
                      DueDate: '2026-01-15'
                      PrivateNote: example_value
                      CustomerMemo:
                        value: example_value
                      Line:
                      - {}
                      TotalAmt: 42.5
                      Balance: 42.5
                      Deposit: 42.5
                      ExchangeRate: 42.5
                      ShipDate: '2026-01-15'
                      TrackingNum: example_value
                      ApplyTaxAfterDiscount: true
                      PrintStatus: NotSet
                      EmailStatus: NotSet
                      GlobalTaxCalculation: TaxExcluded
                      AllowOnlinePayment: true
                      AllowOnlineCreditCardPayment: true
                      AllowOnlineACHPayment: true
                      CustomField:
                      - {}
                      LinkedTxn:
                      - {}
                      domain: example_value
                      sparse: true
                    time: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /invoice/{invoiceId}/pdf:
    get:
      operationId: getInvoicePdf
      summary: Get Invoice as Pdf
      description: Returns the specified invoice as a PDF document. The response content type is application/pdf.
      tags:
      - Invoices
      parameters:
      - $ref: '#/components/parameters/invoiceId'
      - $ref: '#/components/parameters/minorVersion'
      responses:
        '200':
          description: PDF retrieved successfully
          content:
            application/pdf:
              schema:
                type: string
                format: binary
              examples:
                Getinvoicepdf200Example:
                  summary: Default getInvoicePdf 200 response
                  x-microcks-default: true
                  value: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /query:
    get:
      operationId: queryEntities
      summary: Query Entities
      description: Executes a SQL-like query against QuickBooks Online entities. The query language supports SELECT, WHERE, ORDER BY, COUNT, STARTPOSITION, and MAXRESULTS clauses. This endpoint is used to query invoices, customers, items, payments, and other entity types.
      tags:
      - Invoices
      parameters:
      - name: query
        in: query
        required: true
        description: 'A SQL-like query string. For example: SELECT * FROM Invoice WHERE TotalAmt > ''100.00'' ORDERBY TxnDate'
        schema:
          type: string
        example: SELECT * FROM Invoice WHERE TotalAmt > '100.00' MAXRESULTS 10
      - $ref: '#/components/parameters/minorVersion'
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
              examples:
                Queryentities200Example:
                  summary: Default queryEntities 200 response
                  x-microcks-default: true
                  value:
                    QueryResponse:
                      startPosition: 10
                      maxResults: 10
                      totalCount: 10
                      Invoice:
                      - {}
                      Customer:
                      - {}
                      Item:
                      - {}
                      Payment:
                      - {}
                    time: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    Forbidden:
      description: The authenticated user does not have permission to perform this operation on the specified resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: An internal error occurred on the server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication failed. The OAuth 2.0 access token is missing, expired, or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was invalid. This can occur due to missing required fields, validation errors, or malformed request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    QueryResponse:
      type: object
      description: Response wrapper for query operations. Contains the array of matching entities along with pagination metadata.
      properties:
        QueryResponse:
          type: object
          properties:
            startPosition:
              type: integer
              description: Starting position of the results
            maxResults:
              type: integer
              description: Maximum number of results returned
            totalCount:
              type: integer
              description: Total count of matching entities
            Invoice:
              type: array
              items:
                $ref: '#/components/schemas/Invoice'
            Customer:
              type: array
              items:
                $ref: '#/components/schemas/Customer'
            Item:
              type: array
              items:
                $ref: '#/components/schemas/Item'
            Payment:
              type: array
              items:
                $ref: '#/components/schemas/Payment'
          example: example_value
        time:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
    Customer:
      type: object
      description: A Customer represents a consumer of the service or product that the business offers. Customers can be organized as sub-customers (jobs) within a parent customer hierarchy.
      properties:
        Id:
          type: string
          description: Unique identifier for the customer
          readOnly: true
          example: abc123
        SyncToken:
          type: string
          description: Version number for optimistic locking
          example: example_value
        MetaData:
          $ref: '#/components/schemas/MetaData'
          readOnly: true
        Title:
          type: string
          description: Title of the person (e.g., Mr., Mrs., Ms.)
          maxLength: 16
          example: Example Title
        GivenName:
          type: string
          description: Given (first) name of the customer
          maxLength: 100
          example: example_value
        MiddleName:
          type: string
          description: Middle name of the customer
          maxLength: 100
          example: example_value
        FamilyName:
          type: string
          description: Family (last) name of the customer
          maxLength: 100
          example: example_value
        Suffix:
          type: string
          description: Suffix of the person (e.g., Jr., Sr., III)
          maxLength: 16
          example: example_value
        DisplayName:
          type: string
          description: The name displayed to identify the customer. Must be unique across Customer, Employee, and Vendor objects.
          maxLength: 500
          example: example_value
        CompanyName:
          type: string
          description: The name of the company associated with the customer
          maxLength: 500
          example: example_value
        PrintOnCheckName:
          type: string
          description: Name of the customer as printed on a check
          maxLength: 110
          example: example_value
        Active:
          type: boolean
          description: Whether the customer is currently active
          default: true
          example: true
        Taxable:
          type: boolean
          description: Whether the customer is taxable
          example: true
        PrimaryEmailAddr:
          $ref: '#/components/schemas/EmailAddress'
        PrimaryPhone:
          $ref: '#/components/schemas/TelephoneNumber'
        Mobile:
          $ref: '#/components/schemas/TelephoneNumber'
        Fax:
          $ref: '#/components/schemas/TelephoneNumber'
        AlternatePhone:
          $ref: '#/components/schemas/TelephoneNumber'
        BillAddr:
          $ref: '#/components/schemas/PhysicalAddress'
        ShipAddr:
          $ref: '#/components/schemas/PhysicalAddress'
        Notes:
          type: string
          description: Free-form text about the customer
          maxLength: 2000
          example: example_value
        Job:
          type: boolean
          description: Whether this customer is a sub-customer (job)
          example: true
        ParentRef:
          $ref: '#/components/schemas/ReferenceType'
        Level:
          type: integer
          description: Depth level in the customer hierarchy (0 = top)
          readOnly: true
          example: 10
        FullyQualifiedName:
          type: string
          description: Fully qualified name of the entity, including parent names separated by colons
          readOnly: true
          example: example_value
        CurrencyRef:
          $ref: '#/components/schemas/ReferenceType'
        PreferredDeliveryMethod:
          type: string
          description: Preferred delivery method for communications
          enum:
          - Print
          - Email
          - None
          example: Print
        Balance:
          type: number
          description: Open balance amount for the customer
          readOnly: true
          example: 42.5
        BalanceWithJobs:
          type: number
          description: Open balance amount including balances of sub-customers (jobs)
          readOnly: true
          example: 42.5
        SalesTermRef:
          $ref: '#/components/schemas/ReferenceType'
        PaymentMethodRef:
          $ref: '#/components/schemas/ReferenceType'
        TaxExemptionReasonId:
          type: string
          description: Tax exemption reason ID
          example: '500123'
        WebAddr:
          type: object
          properties:
            URI:
              type: string
              format: uri
              description: Website address
          example: example_value
        domain:
          type: string
          readOnly: true
          example: example_value
        sparse:
          type: boolean
          example: true
      required:
      - DisplayName
    Payment:
      type: object
      description: A Payment records a payment received from a customer. Payments can be applied to one or more outstanding invoices, or left as unapplied credit.
      properties:
        Id:
          type: string
          description: Unique identifier for the payment
          readOnly: true
          example: abc123
        SyncToken:
          type: string
          description: Version number for optimistic locking
          example: example_value
        MetaData:
          $ref: '#/components/schemas/MetaData'
          readOnly: true
        TxnDate:
          type: string
          format: date
          description: The date of the payment transaction
          example: '2026-01-15'
        TotalAmt:
          type: number
          description: Total amount of the payment
          example: 42.5
        CustomerRef:
          $ref: '#/components/schemas/ReferenceType'
        DepositToAccountRef:
          $ref: '#/components/schemas/ReferenceType'
        PaymentMethodRef:
          $ref: '#/components/schemas/ReferenceType'
        PaymentRefNum:
          type: string
          description: Reference number for the payment (e.g., check number)
          maxLength: 21
          example: example_value
        CurrencyRef:
          $ref: '#/components/schemas/ReferenceType'
        ExchangeRate:
          type: number
          description: Currency exchange rate
          example: 42.5
        Line:
          type: array
          description: Lines indicating which invoices or credit memos this payment is applied against
          items:
            $ref: '#/components/schemas/PaymentLine'
          example: []
        PrivateNote:
          type: string
          description: Private note for internal use
          maxLength: 4000
          example: example_value
        UnappliedAmt:
          type: number
          description: Amount not yet applied to invoices
          readOnly: true
          example: 42.5
        ProcessPayment:
          type: boolean
          description: Whether to process the payment through the Intuit payment gateway
          example: true
        TxnSource:
          type: string
          description: Source of the transaction
          readOnly: true
          example: example_value
        domain:
          type: string
          readOnly: true
          example: example_value
        sparse:
          type: boolean
          example: true
      required:
      - CustomerRef
      - TotalAmt
    CustomField:
      type: object
      description: Custom field defined for the entity
      properties:
        DefinitionId:
          type: string
          description: Unique identifier of the custom field definition
          example: '500123'
        Name:
          type: string
          description: Name of the custom field
          example: Example Title
        Type:
          type: string
          description: Data type of the custom field
          enum:
          - StringType
          - BooleanType
          - NumberType
          - DateType
          example: StringType
        StringValue:
          type: string
          description: Value when Type is StringType
          example: example_value
    ReferenceType:
      type: object
      description: A reference type used throughout the API to link entities. Contains the ID value and optionally the display name of the referenced entity.
      properties:
        value:
          type: string
          description: The ID of the referenced entity
          example: example_value
        name:
          type: string
          description: An identifying name for the referenced entity
          example: Example Title
      required:
      - value
    Invoice:
      type: object
      description: An Invoice represents a sales form where the customer pays for a product or service later. It creates an accounts receivable transaction.
      properties:
        Id:
          type: string
          description: Unique identifier for the invoice (assigned by QuickBooks)
          readOnly: true
          example: abc123
        SyncToken:
          type: string
          description: Version number of the entity, used for optimistic locking. Required for updates.
          example: example_value
        MetaData:
          $ref: '#/components/schemas/MetaData'
          readOnly: true
        DocNumber:
          type: string
          description: Reference number for the transaction. If not provided, QuickBooks auto-generates one.
          maxLength: 21
          example: example_value
        TxnDate:
          type: string
          format: date
          description: The date of the transaction. Defaults to the current date.
          example: '2026-01-15'
        DueDate:
          type: string
          format: date
          description: Date when the payment of the transaction is due
          example: '2026-01-15'
        PrivateNote:
          type: string
          description: A private note that is not displayed to the customer
          maxLength: 4000
          example: example_value
        CustomerMemo:
          type: object
          description: A note to the customer displayed on the invoice
          properties:
            value:
              type: string
              maxLength: 1000
          example: example_value
        CustomerRef:
          $ref: '#/components/schemas/ReferenceType'
        BillAddr:
          $ref: '#/components/schemas/PhysicalAddress'
        ShipAddr:
          $ref: '#/components/schemas/PhysicalAddress'
        BillEmail:
          $ref: '#/components/schemas/EmailAddress'
        Line:
          type: array
          description: Individual line items of the transaction. At least one line is required.
          items:
            $ref: '#/components/schemas/InvoiceLine'
          minItems: 1
          example: []
        TxnTaxDetail:
          $ref: '#/components/schemas/TxnTaxDetail'
        TotalAmt:
          type: number
          description: Total amount of the transaction including tax
          readOnly: true
          example: 42.5
        Balance:
          type: number
          description: The balance remaining on the invoice. A value of 0 indicates the invoice is fully paid.
          readOnly: true
          example: 42.5
        Deposit:
          type: number
          description: Deposit amount applied to the invoice
          example: 42.5
        DepositToAccountRef:
          $ref: '#/components/schemas/ReferenceType'
        SalesTermRef:
          $ref: '#/components/schemas/ReferenceType'
        PaymentMethodRef:
          $ref: '#/components/schemas/ReferenceType'
        CurrencyRef:
          $ref: '#/components/schemas/ReferenceType'
        ExchangeRate:
          type: number
          description: Currency exchange rate (multicurrency enabled companies)
          example: 42.5
        ShipDate:
          type: string
          format: date
          description: Date for delivery of goods or services
          example: '2026-01-15'
        ShipMethodRef:
          $ref: '#/components/schemas/ReferenceType'
        TrackingNum:
          type: string
          description: Shipping tracking number
          example: example_value
        ApplyTaxAfterDiscount:
          type: boolean
          description: Whether to apply tax after discount
          example: true
        PrintStatus:
          type: string
          description: Printing status of the invoice
          enum:
          - NotSet
          - NeedToPrint
          - PrintComplete
          example: NotSet
        EmailStatus:
          type: string
          description: Email delivery status of the invoice
          enum:
          - NotSet
          - NeedToSend
          - EmailSent
          example: NotSet
        GlobalTaxCalculation:
          type: string
          description: Method in which tax is applied
          enum:
          - TaxExcluded
          - TaxInclusive
          - NotApplicable
          example: TaxExcluded
        AllowOnlinePayment:
          type: boolean
          description: Whether online payment is allowed
          example: true
        AllowOnlineCreditCardPayment:
          type: boolean
          description: Whether online credit card payment is allowed
          example: true
        AllowOnlineACHPayment:
          type: boolean
          description: Whether online ACH (bank) payment is allowed
          example: true
        CustomField:
          type: array
          items:
            $ref: '#/components/schemas/CustomField'
          maxItems: 3
          example: []
        LinkedTxn:
          type: array
          items:
            $ref: '#/components/schemas/LinkedTxn'
          example: []
        domain:
          type: string
          description: Domain (e.g., QBO)
          readOnly: true
          example: example_value
        sparse:
          type: boolean
          description: Whether this is a sparse (partial) representation
          example: true
      required:
      - CustomerRef
      - Line
    EmailAddress:
      type: object
      description: Email address
      properties:
        Address:
          type: string
          format: email
          description: Email address string
          maxLength: 100
          example: example_value
    Item:
      type: object
      description: An Item represents a product or service that a company buys, sells, or re-sells. Items are used in line items on invoices, sales receipts, bills, and other transactions.
      properties:
        Id:
          type: string
          description: Unique identifier for the item
          readOnly: true
          example: abc123
        SyncToken:
          type: string
          description: Version number for optimistic locking
          example: example_value
        MetaData:
          $ref: '#/components/schemas/MetaData'
          readOnly: true
        Name:
          type: string
          description: Name of the item. Must be unique within the same type.
          maxLength: 100
          example: Example Title
        Description:
          type: string
          description: Description of the item used in sales transactions
          maxLength: 4000
          example: A sample description.
        PurchaseDesc:
          type: string
          description: Description of the item used in purchase transactions
          maxLength: 4000
          example: example_value
        Active:
          type: boolean
          description: Whether the item is currently active
          default: true
          example: true
        FullyQualifiedName:
          type: string
          description: Fully qualified name of the item
          readOnly: true
          example: example_value
        Taxable:
          type: boolean
          description: Whether sales of this item are taxable
          example: true
        SalesTaxIncluded:
          type: boolean
          description: Whether the sales tax is included in the item amount
          example: true
        UnitPrice:
          type: number
          description: Sales price for this item
          example: 42.5
        Type:
          type: string
          description: Classification of the item
          enum:
          - Inventory
          - NonInventory
          - Service
          - Group
          - Category
          - Bundle
          example: Inventory
        PurchaseCost:
          type: number
          description: Purchase cost of the item
          example: 42.5
        QtyOnHand:
          type: number
          description: Current quantity on hand (inventory items only)
          example: 42.5
        InvStartDate:
          type: string
          format: date
          description: Date of opening balance for inventory items
          example: '2026-01-15'
        TrackQtyOnHand:
          type: boolean
          description: Whether quantity on hand is tracked
          example: true
        Sku:
          type: string
          description: Stock keeping unit identifier
          maxLength: 100
          example: example_value
        IncomeAccountRef:
          $ref: '#/components/schemas/ReferenceType'
        ExpenseAccountRef:
          $ref: '#/components/schemas/ReferenceType'
        AssetAccountRef:
          $ref: '#/components/schemas/ReferenceType'
        ParentRef:
          $ref: '#/components/schemas/ReferenceType'
        SubItem:
          type: boolean
          description: Whether this is a sub-item
          example: true
        Level:
          type: integer
          description: Depth level in the item hierarchy
          readOnly: true
          example: 10
        SalesTaxCodeRef:
          $ref: '#/components/schemas/ReferenceType'
        PurchaseTaxCodeRef:
          $ref: '#/components/schemas/ReferenceType'
        ClassRef:
          $ref: '#/components/schemas/ReferenceType'
        AbatementRate:
          type: number
          readOnly: true
          example: 42.5
        ReverseChargeRate:
          type: number
          readOnly: true
          example: 42.5
        domain:
          type: string
          readOnly: true
          example: example_value
        sparse:
          type: boolean
          example: true
      required:
      - Name
      - Type
    InvoiceLine:
      type: object
      description: A line item on an invoice
      properties:
        Id:
          type: string
          description: The unique identifier for the line item
          example: abc123
        LineNum:
          type: integer
          description: Line number within the transaction
          example: 10
        Description:
          type: string
          description: Free-form text description of the line item
          maxLength: 4000
          example: A sample description.
        Amount:
          type: number
          description: The total amount for the line item
          example: 42.5
        DetailType:
          type: string
          description: Specifies the type of line detail
          enum:
          - SalesItemLineDetail
          - GroupLineDetail
          - DescriptionOnly
          - DiscountLineDetail
          - SubTotalLineDetail
          example: SalesItemLineDetail
        SalesItemLineDetail:
          $ref: '#/components/schemas/SalesItemLineDetail'
        LinkedTxn:
          type: array
          items:
            $ref: '#/components/schemas/LinkedTxn'
          example: []
      required:
      - Amount
      - DetailType
    TelephoneNumber:
      type: object
      description: Telephone number
      properties:
        FreeFormNumber:
          type: string
          description: Telephone number in free-form format
          maxLength: 30
          example: example_value
    Error:
      type: object
      description: Error response from the API
      properties:
        Fault:
          type: object
          properties:
            Error:
              type: array
              items:
                type: object
                properties:
                  Message:
                    type: string
                    description: A short human-readable summary of the error
                  Detail:
                    type: string
                    description: Detailed description of the error
                  code:
                    type: string
                    description: Intuit-specific error code
                  element:
                    type: string
                    description: The element that caused the error
            type:
              type: string
              description: The type of fault
              enum:
              - ValidationFault
              - SystemFault
              - AuthenticationFault
              - AuthorizationFault
          example: example_value
        time:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
    PhysicalAddress:
      type: object
      description: Physical (mailing) address
      properties:
        Id:
          type: string
          description: Unique identifier for the address
          example: abc123
        Line1:
          type: string
          description: First line of the street address
          maxLength: 500
          example: example_value
        Line2:
          type: string
          description: Second line of the street address
          maxLength: 500
          example: example_value
        Line3:
          type: string
          description: Third line of the street address
          maxLength: 500
          example: example_value
        Line4:
          type: string
          description: Fourth line of the street address
          maxLength: 500
          example: example_value
        Line5:
          type: string
          description: Fifth line of the street address
          maxLength: 500
          example: example_value
        City:
          type: string
          description: City name
          maxLength: 255
          example: example_value
        CountrySubDivisionCode:
          type: string
          description: Region or state within a country (e.g., state, province)
          maxLength: 255
          example: example_value
        PostalCode:
          type: string
          description: Postal code
          maxLength: 30
          example: example_value
        Country:
          type: string
          description: Country name or code
          maxLength: 255
          example: example_value
        Lat:
          type: string
          description: Latitude coordinate
          example: example_value
        Long:
          type: string
          description: Longitude coordinate
          example: example_value
    PaymentLine:
      type: object
      description: A line item on a payment showing how it is applied
      properties:
        Amount:
          type: number
          description: Amount to apply from this payment
          example: 42.5
        LinkedTxn:
          type: array
          items:
            $ref: '#/components/schemas/LinkedTxn'
          example: []
      required:
      - Amount
      - LinkedTxn
    LinkedTxn:
      type: object
      description: A reference to a linked transaction such as an invoice, payment, or credit memo
      properties:
        TxnId:
          type: string
          description: Transaction ID of the related transaction
          example: '500123'
        TxnType:
          type: string
          description: The type of the linked transaction
          enum:
          - Invoice
          - Payment
          - CreditMemo
          - Estimate
          - SalesReceipt
          - JournalEntry
          - Expense
          - StatementCharge
          - ReimburseCharge
          example: Invoice
      required:
      - TxnId
      - TxnType
    TxnTaxDetail:
      type: object
      description: Tax details for a transaction
      properties:
        TxnTaxCodeRef:
          $ref: '#/components/schemas/ReferenceType'
        TotalTax:
          type: number
          description: Total tax calculated for the transaction
          example: 42.5
        TaxLine:
          type: array
          items:
            type: object
            properties:
              Amount:
                type: number
                description: Tax amount for this tax line
              DetailType:
                type: string
                enum:
                - TaxLineDetail
              TaxLineDetail:
                type: object
                properties:
                  TaxRateRef:
                    $ref: '#/components/schemas/ReferenceType'
                  PercentBased:
                    type: boolean
                  TaxPercent:
                    type: number
                  NetAmountTaxable:
                    type: number
          example: []
    InvoiceResponse:
      type: object
      properties:
        Invoice:
          $ref: '#/components/schemas/Invoice'
        time:
          type: string
          format: date-time
          description: Timestamp of the response
          example: '2026-01-15T10:30:00Z'
    SalesItemLineDetail:
      type: object
      description: Detail for a sales item line
      properties:
        ItemRef:
          $ref: '#/components/schemas/ReferenceType'
        ClassRef:
          $ref: '#/components/schemas/ReferenceType'
        UnitPrice:
          type: number
          description: Unit price of the item
          example: 42.5
        RatePercent:
          type: number
          description: The discount rate as a percentage (for discount lines)
          example: 42.5
        Qty:
          type: number
          description: Number of items for the line
          example: 42.5
        ItemAccountRef:
          $ref: '#/components/schemas/ReferenceType'
        TaxCodeRef:
          $ref: '#/components/schemas/ReferenceType'
        ServiceDate:
          type: string
          format: date
          description: Date the service was performed
          example: '2026-01-15'
        DiscountAmt:
          type: number
          description: Discount amount applied to the line
          example: 42.5
        DiscountRate:
          type: number
          description: Discount rate as a percentage
          example: 42.5
    MetaData:
      type: object
      description: Metadata about when the entity was created and last updated
      properties:
        CreateTime:
          type: string
          format: date-time
          description: Time the entity was created
          example: '2026-01-15T10:30:00Z'
        LastUpdatedTime:
          type: string
          format: date-time
          description: Time the entity was last updated
          example: '2026-01-15T10:30:00Z'
  parameters:
    invoiceId:
      name: invoiceId
      in: path
      required: true
      description: The unique identifier for the invoice
      schema:
        type: string
    minorVersion:
      name: minorversion
      in: query
      description: The minor version of the API to use. Minor versions introduce new fields and behaviors without breaking existing integrations. If omitted, the base version behavior is used.
      schema:
        type: integer
        minimum: 1
        maximum: 75
      example: 75
  securitySchemes:
    oauth2:
      type: oauth2
      description: Intuit uses OAuth 2.0 for authorization. Apps must be registered on the Intuit Developer portal to obtain client credentials. Access tokens have a 60-minute lifetime and can be refreshed using refresh tokens (100-day lifetime).
      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: Access to QuickBooks Online Accounting API
externalDocs:
  description: QuickBooks Online API Documentation
  url: https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account