Intuit Items API

openapi: 3.2.0
info:
  title: QuickBooks Online Accounting Customers Items 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: Items
  description: An Item represents a product or service that a company buys, sells, or re-sells, such as products, shipping charges, discount, and sales tax (if applicable). Items are used in line items on invoices and other transaction entities.
  externalDocs:
    url: https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/item
paths:
  /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:
      - Items
      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
  /item:
    post:
      operationId: createItem
      summary: Create an Item
      description: Creates a new item (product or service). At minimum, the request must include a Name, Type (Inventory, NonInventory, or Service), and appropriate account references (IncomeAccountRef, ExpenseAccountRef, and AssetAccountRef for inventory items).
      tags:
      - Items
      parameters:
      - $ref: '#/components/parameters/minorVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Item'
            examples:
              CreateitemRequestExample:
                summary: Default createItem request
                x-microcks-default: true
                value:
                  Id: abc123
                  SyncToken: example_value
                  MetaData:
                    CreateTime: '2026-01-15T10:30:00Z'
                    LastUpdatedTime: '2026-01-15T10:30:00Z'
                  Name: Example Title
                  Description: A sample description.
                  PurchaseDesc: example_value
                  Active: true
                  FullyQualifiedName: example_value
                  Taxable: true
                  SalesTaxIncluded: true
                  UnitPrice: 42.5
                  Type: Inventory
                  PurchaseCost: 42.5
                  QtyOnHand: 42.5
                  InvStartDate: '2026-01-15'
                  TrackQtyOnHand: true
                  Sku: example_value
                  IncomeAccountRef:
                    value: example_value
                    name: Example Title
                  ExpenseAccountRef:
                    value: example_value
                    name: Example Title
                  AssetAccountRef:
                    value: example_value
                    name: Example Title
                  ParentRef:
                    value: example_value
                    name: Example Title
                  SubItem: true
                  Level: 10
                  SalesTaxCodeRef:
                    value: example_value
                    name: Example Title
                  PurchaseTaxCodeRef:
                    value: example_value
                    name: Example Title
                  ClassRef:
                    value: example_value
                    name: Example Title
                  AbatementRate: 42.5
                  ReverseChargeRate: 42.5
                  domain: example_value
                  sparse: true
      responses:
        '200':
          description: Item created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemResponse'
              examples:
                Createitem200Example:
                  summary: Default createItem 200 response
                  x-microcks-default: true
                  value:
                    Item:
                      Id: abc123
                      SyncToken: example_value
                      Name: Example Title
                      Description: A sample description.
                      PurchaseDesc: example_value
                      Active: true
                      FullyQualifiedName: example_value
                      Taxable: true
                      SalesTaxIncluded: true
                      UnitPrice: 42.5
                      Type: Inventory
                      PurchaseCost: 42.5
                      QtyOnHand: 42.5
                      InvStartDate: '2026-01-15'
                      TrackQtyOnHand: true
                      Sku: example_value
                      SubItem: true
                      Level: 10
                      AbatementRate: 42.5
                      ReverseChargeRate: 42.5
                      domain: example_value
                      sparse: true
                    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
  /item/{itemId}:
    get:
      operationId: readItem
      summary: Read an Item
      description: Retrieves the details of an item that has been previously created. Supply the unique item ID.
      tags:
      - Items
      parameters:
      - $ref: '#/components/parameters/itemId'
      - $ref: '#/components/parameters/minorVersion'
      responses:
        '200':
          description: Item retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemResponse'
              examples:
                Readitem200Example:
                  summary: Default readItem 200 response
                  x-microcks-default: true
                  value:
                    Item:
                      Id: abc123
                      SyncToken: example_value
                      Name: Example Title
                      Description: A sample description.
                      PurchaseDesc: example_value
                      Active: true
                      FullyQualifiedName: example_value
                      Taxable: true
                      SalesTaxIncluded: true
                      UnitPrice: 42.5
                      Type: Inventory
                      PurchaseCost: 42.5
                      QtyOnHand: 42.5
                      InvStartDate: '2026-01-15'
                      TrackQtyOnHand: true
                      Sku: example_value
                      SubItem: true
                      Level: 10
                      AbatementRate: 42.5
                      ReverseChargeRate: 42.5
                      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: updateItem
      summary: Update an Item
      description: Updates an existing item. The request must include the Id and SyncToken. Sparse updates are supported.
      tags:
      - Items
      parameters:
      - $ref: '#/components/parameters/itemId'
      - name: sparse
        in: query
        description: Set to true for a sparse (partial) update
        schema:
          type: boolean
        example: true
      - $ref: '#/components/parameters/minorVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Item'
            examples:
              UpdateitemRequestExample:
                summary: Default updateItem request
                x-microcks-default: true
                value:
                  Id: abc123
                  SyncToken: example_value
                  MetaData:
                    CreateTime: '2026-01-15T10:30:00Z'
                    LastUpdatedTime: '2026-01-15T10:30:00Z'
                  Name: Example Title
                  Description: A sample description.
                  PurchaseDesc: example_value
                  Active: true
                  FullyQualifiedName: example_value
                  Taxable: true
                  SalesTaxIncluded: true
                  UnitPrice: 42.5
                  Type: Inventory
                  PurchaseCost: 42.5
                  QtyOnHand: 42.5
                  InvStartDate: '2026-01-15'
                  TrackQtyOnHand: true
                  Sku: example_value
                  IncomeAccountRef:
                    value: example_value
                    name: Example Title
                  ExpenseAccountRef:
                    value: example_value
                    name: Example Title
                  AssetAccountRef:
                    value: example_value
                    name: Example Title
                  ParentRef:
                    value: example_value
                    name: Example Title
                  SubItem: true
                  Level: 10
                  SalesTaxCodeRef:
                    value: example_value
                    name: Example Title
                  PurchaseTaxCodeRef:
                    value: example_value
                    name: Example Title
                  ClassRef:
                    value: example_value
                    name: Example Title
                  AbatementRate: 42.5
                  ReverseChargeRate: 42.5
                  domain: example_value
                  sparse: true
      responses:
        '200':
          description: Item updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemResponse'
              examples:
                Updateitem200Example:
                  summary: Default updateItem 200 response
                  x-microcks-default: true
                  value:
                    Item:
                      Id: abc123
                      SyncToken: example_value
                      Name: Example Title
                      Description: A sample description.
                      PurchaseDesc: example_value
                      Active: true
                      FullyQualifiedName: example_value
                      Taxable: true
                      SalesTaxIncluded: true
                      UnitPrice: 42.5
                      Type: Inventory
                      PurchaseCost: 42.5
                      QtyOnHand: 42.5
                      InvStartDate: '2026-01-15'
                      TrackQtyOnHand: true
                      Sku: example_value
                      SubItem: true
                      Level: 10
                      AbatementRate: 42.5
                      ReverseChargeRate: 42.5
                      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
components:
  schemas:
    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
    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'
    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
    TelephoneNumber:
      type: object
      description: Telephone number
      properties:
        FreeFormNumber:
          type: string
          description: Telephone number in free-form format
          maxLength: 30
          example: example_value
    ItemResponse:
      type: object
      properties:
        Item:
          $ref: '#/components/schemas/Item'
        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
    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: []
    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
    EmailAddress:
      type: object
      description: Email address
      properties:
        Address:
          type: string
          format: email
          description: Email address string
          maxLength: 100
          example: example_value
    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'
    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
    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
    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
          d

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/intuit/refs/heads/main/openapi/intuit-items-api-openapi.yml