QuickBooks Change Order API

openapi: 3.2.0
info:
  title: QuickBooks Online Accounting Change Order 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: ChangeOrder
  description: A change order represents a modification to the scope of work on an existing project estimate. It captures additions or deletions to the original contracted work, and rolls up into the project's total budget alongside the parent estimate. Change orders are available for US companies on QuickBooks Online Advanced with the Construction Pack or Intuit Enterprise Suite, with the Projects feature enabled.
paths:
  /v3/company/{realmID}/changeorder:
    post:
      operationId: createChangeOrder
      summary: Create a change order / Delete a change order / Full update a change order
      tags:
      - ChangeOrder
      x-source: https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/changeorder
      x-intuit-operation: POST /v3/company/<realmID>/changeorder
      description: 'Change order creation is available only for US companies on QuickBooks Online Advanced with the Construction Pack Add-on or Intuit Enterprise Suite, with the Projects feature enabled.

        A change order must have ProjectRef populated with a valid, active project.

        A change order must have at least one line with DetailType: "SalesItemLineDetail".

        Every line must include a LinkedTxn array referencing the parent project estimate using TxnType: "Estimate". All lines must reference the same parent estimate.

        CustomerRef must match the customer on the parent project estimate.


        **Delete a change order** (POST /v3/company//changeorder?operation=delete): This operation deletes the Change Order object specified in the request body. Include a minimum of ChangeOrder.Id and ChangeOrder.SyncToken in the request body. This action is irreversible. Deleting a change order does not modify the parent project estimate; only the project''s cumulative total is recalculated.


        **Full update a change order** (POST /v3/company//changeorder): Use this operation to update any of the writable fields of an existing Change Order object. The request body must include all writable fields of the existing object as returned in a read response. Writable fields omitted from the request body are set to NULL. The ID of the object to update is specified in the request body.


        Note: When updating lines, include all existing lines you want to retain. Lines omitted from the request body will be deleted. Always re-include LinkedTxn on every line.'
      parameters:
      - name: realmID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/changeorderrequest'
              - $ref: '#/components/schemas/changeorderresponse'
          application/json or application/xml:
            schema:
              $ref: '#/components/schemas/deleterequest'
        required: true
        description: The minimum elements to create a change order are listed here.
      responses:
        '200':
          description: The change order response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changeorderresponse'
        '400':
          $ref: '#/components/responses/Fault'
        '401':
          $ref: '#/components/responses/Fault'
        '429':
          $ref: '#/components/responses/Throttled'
      security:
      - oauth2:
        - com.intuit.quickbooks.accounting
      x-intuit-variants:
      - name: Delete a change order
        operationId: deleteChangeOrder
        x-source: https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/changeorder
        x-intuit-operation: POST /v3/company/<realmID>/changeorder?operation=delete
        description: This operation deletes the Change Order object specified in the request body. Include a minimum of ChangeOrder.Id and ChangeOrder.SyncToken in the request body. This action is irreversible. Deleting a change order does not modify the parent project estimate; only the project's cumulative total is recalculated.
        requestSchema:
          $ref: '#/components/schemas/deleterequest'
      - name: Full update a change order
        operationId: updateChangeOrder
        x-source: https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/changeorder
        x-intuit-operation: POST /v3/company/<realmID>/changeorder
        description: 'Use this operation to update any of the writable fields of an existing Change Order object. The request body must include all writable fields of the existing object as returned in a read response. Writable fields omitted from the request body are set to NULL. The ID of the object to update is specified in the request body.


          Note: When updating lines, include all existing lines you want to retain. Lines omitted from the request body will be deleted. Always re-include LinkedTxn on every line.'
        requestSchema:
          $ref: '#/components/schemas/changeorderresponse'
  /v3/company/{realmID}/changeorder/{changeorderId}:
    get:
      operationId: readChangeOrder
      summary: Read a change order
      tags:
      - ChangeOrder
      x-source: https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/changeorder
      x-intuit-operation: GET /v3/company/<realmID>/changeorder/<changeorderId>
      description: Retrieves the details of a change order that has been previously created.
      parameters:
      - name: realmID
        in: path
        required: true
        schema:
          type: string
      - name: changeorderId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The change order response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changeorderresponse'
        '400':
          $ref: '#/components/responses/Fault'
        '401':
          $ref: '#/components/responses/Fault'
        '429':
          $ref: '#/components/responses/Throttled'
      security:
      - oauth2:
        - com.intuit.quickbooks.accounting
components:
  schemas:
    linkedtxn:
      type: object
      title: linkedtxn
      properties:
        TxnLineId:
          type: string
          description: 'Required for Deposit and Bill entities. The line number of a specific line of the linked transaction. If supplied, the

            TxnId and

            TxnType attributes of the linked transaction must also be populated.'
          x-intuit-required: Conditionally required
        TxnId:
          type: string
          description: Transaction Id of the related transaction.
          x-intuit-required: Required
        TxnType:
          type: string
          description: Transaction type of the linked object.
          x-intuit-required: Required
      required:
      - TxnId
      - TxnType
    changeorderresponse:
      type: object
      title: changeorderresponse
      properties:
        TxnDate:
          type: string
          format: date
          description: The date entered by the user when this transaction occurred. For posting transactions, this is the posting date that affects the financial statements. If not supplied, the current date on the server is used. Sort order is ASC by default.
          x-intuit-required: Optional
          x-intuit-default: current server date
          x-intuit-filterable: true
          x-intuit-sortable: true
        PrintStatus:
          type: string
          description: 'Printing status of the change order. Valid values: NotSet, NeedToPrint, PrintComplete.'
          x-intuit-required: Optional
          x-intuit-default: <span class="literal">NotSet</span>
        TxnStatus:
          type: string
          description: 'Current status of the change order. Valid values: Pending (default — created but not yet reviewed), Accepted (customer approved; project contracted total increases accordingly), Closed (converted to an Invoice or manually closed), Rejected (customer declined; does not affect project total).'
          x-intuit-required: Optional
          x-intuit-default: Pending
        LinkedTxn:
          type: array
          items:
            $ref: '#/components/schemas/linkedtxn'
          description: One or more linked transaction references at the header level, reflecting the parent project estimate. Also appears on each line item. Use LinkedTxn.TxnId as the ID in a separate Estimate read request to retrieve details of the linked object. TxnType must always be Estimate.
          x-intuit-required: Required
        TotalAmt:
          type: number
          description: Total amount of the transaction including all line charges and taxes. Calculated by QuickBooks business logic from the sum of all line Amount values plus applicable tax. Do not include in create or update request bodies; any value supplied is overwritten.
        AcceptedDate:
          type: string
          format: date
          description: Date the change order was accepted. Populated when TxnStatus is set to Accepted.
          x-intuit-required: Optional
        ExpirationDate:
          type: string
          format: date
          description: Date by which the change order must be accepted before it expires.
          x-intuit-required: Optional
        ApplyTaxAfterDiscount:
          type: boolean
          description: If false or null, sales tax is calculated first and then any discount is applied. If true, the discount is subtracted first and then sales tax is calculated.
          x-intuit-required: Optional
          x-intuit-default: false
        DocNumber:
          type: string
          description: Reference number for the change order (for example, CO-001). If not provided, the value is null.
          x-intuit-required: Optional
          x-intuit-filterable: true
          x-intuit-sortable: true
        PrivateNote:
          type: string
          description: Organization-private note about the change order. This note does not appear on documents sent to the customer.
          x-intuit-required: Optional
        Line:
          type: array
          items:
            $ref: '#/components/schemas/line'
          description: 'Individual line items describing the work being added or removed. Supports SalesItemLineDetail and SubTotalLineDetail line types. Every line must include a LinkedTxn array referencing the parent project estimate with TxnType: "Estimate". All lines must reference the same parent estimate. The Line array uses full-replace behavior on update — lines omitted from an update request are deleted.'
          x-intuit-required: Required
        CustomerMemo:
          allOf:
          - $ref: '#/components/schemas/memoref'
          description: User-entered message to the customer; visible on the Change Order document sent to the customer.
          x-intuit-required: Optional
        ProjectRef:
          allOf:
          - $ref: '#/components/schemas/referencetype'
          description: Reference to the project this change order belongs to. Must reference an active project. Without a valid ProjectRef, the change order will not appear in the Projects dashboard.
          x-intuit-required: Required
          x-intuit-filterable: true
        CustomerRef:
          allOf:
          - $ref: '#/components/schemas/referencetype'
          description: Reference to the customer associated with this change order. Must match the customer on the parent project estimate. Use Customer.Id and Customer.DisplayName from the Customer object for CustomerRef.value and CustomerRef.name, respectively.
          x-intuit-required: Required
          x-intuit-filterable: true
        TxnTaxDetail:
          allOf:
          - $ref: '#/components/schemas/txntaxdetail'
          description: Tax details for the transaction. Captures sales taxes calculated based on tax codes referenced by the transaction lines.
          x-intuit-required: Optional
        SyncToken:
          type: string
          description: Version number of the object. It is used to lock an object for use by one app at a time. As soon as an application modifies an object, its SyncToken is incremented. Attempts to modify an object specifying an older SyncToken fail. Only the latest version of the object is maintained by QuickBooks Online.
          x-intuit-required: Required for update
        AcceptedBy:
          type: string
          description: Name of the customer or representative who accepted the change order. Populated when TxnStatus is set to Accepted.
          x-intuit-required: Optional
        TotalCostAmount:
          type: number
          description: Total cost amount of the transaction, calculated from the sum of all line CostAmount values. Calculated by QuickBooks business logic; any value supplied is overwritten.
        EmailStatus:
          type: string
          description: 'Email status of the change order. Valid values: NotSet, NeedToSend, EmailSent.'
          x-intuit-required: Optional
          x-intuit-default: <span class="literal">NotSet</span>
        MetaData:
          allOf:
          - $ref: '#/components/schemas/modificationmetadata'
          description: Descriptive information about the object. The MetaData values are set by Data Services and are read only for all applications.
          x-intuit-required: Optional
        BillEmail:
          allOf:
          - $ref: '#/components/schemas/emailaddress'
          description: Email address where the change order is sent. Required when EmailStatus is set to NeedToSend.
          x-intuit-required: Conditionally required
        Id:
          type: string
          description: Unique identifier for this object.
          x-intuit-required: Required for update
          x-intuit-filterable: true
      required:
      - CustomerRef
      - Line
      - LinkedTxn
      - ProjectRef
    deleterequest:
      type: object
      title: deleterequest
      properties:
        SyncToken:
          type: string
          description: Version number of the object. It is used to lock an object for use by one app at a time. As soon as an application modifies an object, its SyncToken is incremented. Attempts to modify an object specifying an older SyncToken fails. Only the latest version of the object is maintained by QuickBooks Online.
          x-intuit-required: Required
        id:
          type: string
          description: Unique identifier for this object.
          x-intuit-required: Required
          x-intuit-filterable: true
      required:
      - SyncToken
      - id
    txntaxdetail:
      type: object
      title: txntaxdetail
      properties:
        TxnTaxCodeRef:
          allOf:
          - $ref: '#/components/schemas/referencetype'
          description: 'Reference to the transaction tax code. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively. If specified and sales tax is disabled (Preferences.TaxPrefs.UsingSalesTax is set to false), this element is ignored and not returned. For sales transactions, only: if automated sales tax is enabled (Preferences.TaxPrefs.PartnerTaxEnabled is set to true) the supplied transaction tax code is replaced by the automated sales tax engine recommendation.'
          x-intuit-required: Optional
        TotalTax:
          type: number
          description: Total tax calculated for the transaction, excluding any tax lines manually inserted into the transaction line list.
          x-intuit-required: Optional
        TaxLine:
          type: array
          items:
            $ref: '#/components/schemas/line'
          x-intuit-required: Optional
    memoref:
      type: object
      title: memoref
      properties:
        value:
          type: string
          description: User-entered message to the customer; this message is visible to the end user on their transactions.
          x-intuit-required: Required
      required:
      - value
    referencetype:
      type: object
      title: referencetype
      properties:
        name:
          type: string
          description: An identifying name for the object being referenced by value and is derived from the field that holds the common name of that object. This varies by context and specific type of object referenced. For example, references to a Customer object use Customer.DisplayName to populate this field. Optionally returned in responses, implementation dependent.
          x-intuit-required: Optional
        value:
          type: string
          description: The ID for the referenced object as found in the Id field of the object payload. The context is set by the type of reference and is specific to the QuickBooks company file.
          x-intuit-required: Required
      required:
      - value
    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
    emailaddress:
      type: object
      title: emailaddress
      properties:
        Address:
          type: string
          description: An email address. The address format must follow the RFC 822 standard.
          x-intuit-required: Optional
    changeorderrequest:
      type: object
      title: changeorderrequest
      properties:
        DocNumber:
          type: string
          description: Reference number for the change order (for example, CO-001). If not provided, the value is null.
          x-intuit-required: Optional
          x-intuit-filterable: true
          x-intuit-sortable: true
        TxnStatus:
          type: string
          description: 'Current status of the change order. Valid values: Pending, Accepted, Closed, Rejected.'
          x-intuit-required: Optional
          x-intuit-default: Pending
        PrivateNote:
          type: string
          description: Organization-private note about the change order. This note does not appear on documents sent to the customer.
          x-intuit-required: Optional
        TxnDate:
          type: string
          format: date
          description: The date entered by the user when this transaction occurred. If not supplied, the current date on the server is used.
          x-intuit-required: Optional
          x-intuit-default: current server date
          x-intuit-filterable: true
          x-intuit-sortable: true
        BillEmail:
          allOf:
          - $ref: '#/components/schemas/emailaddress'
          description: Email address where the change order is sent. Required when EmailStatus is set to NeedToSend.
          x-intuit-required: Conditionally required
        CustomerMemo:
          allOf:
          - $ref: '#/components/schemas/memoref'
          description: User-entered message to the customer; visible on the Change Order document sent to the customer.
          x-intuit-required: Optional
        ProjectRef:
          allOf:
          - $ref: '#/components/schemas/referencetype'
          description: Reference to the project this change order belongs to. The project must be active. Without a valid ProjectRef, the change order will not appear in the Projects dashboard.
          x-intuit-required: Required
          x-intuit-filterable: true
        PrintStatus:
          type: string
          description: 'Printing status of the change order. Valid values: NotSet, NeedToPrint, PrintComplete.'
          x-intuit-required: Optional
          x-intuit-default: <span class="literal">NotSet</span>
        ExpirationDate:
          type: string
          format: date
          description: Date by which the change order must be accepted before it expires.
          x-intuit-required: Optional
        Line:
          type: object
          x-intuit-type: Change Order line object
          description: 'Individual line items describing the work being added or removed. Each line must include a LinkedTxn array referencing the parent project estimate with TxnType: "Estimate". All lines must reference the same parent estimate. Supports SalesItemLineDetail line type.'
          x-intuit-required: Required
        CustomerRef:
          allOf:
          - $ref: '#/components/schemas/referencetype'
          description: Reference to the customer associated with this change order. Must match the customer on the parent project estimate. Query the Customer name list resource to determine the appropriate Customer object for this reference. Use Customer.Id and Customer.DisplayName from that object for CustomerRef.value and CustomerRef.name, respectively.
          x-intuit-required: Required
          x-intuit-filterable: true
        EmailStatus:
          type: string
          description: 'Email status of the change order. Valid values: NotSet, NeedToSend, EmailSent.'
          x-intuit-required: Optional
          x-intuit-default: <span class="literal">NotSet</span>
      required:
      - CustomerRef
      - Line
      - ProjectRef
    modificationmetadata:
      type: object
      title: modificationmetadata
      properties:
        CreateTime:
          type: string
          format: date-time
          description: Time the entity was created in the source domain.
          x-intuit-filterable: true
          x-intuit-sortable: true
        LastUpdatedTime:
          type: string
          format: date-time
          description: Time the entity was last updated in the source domain.
          x-intuit-filterable: true
          x-intuit-sortable: true
    line:
      type: object
      title: line
      properties:
        Received:
          type: string
          description: Supported for Purchase Order only. The amount/quantity received of the line, which depends on the type of the line. It can represent the received amount or received quantity based on the line type detail. Applies to existing and new entities.
        LinkedTxn:
          type: array
          items: {}
          description: Transaction to which the current entity is related. For example, an invoice line may link to a sales order or estimate.
          x-intuit-required: Optional
        Description:
          type: string
          description: Free form text description of the line item that appears in the printed record.
          x-intuit-required: Optional
        ProjectRef:
          allOf:
          - $ref: '#/components/schemas/referencetype'
          description: Reference to the Project ID associated with this transaction.
          x-intuit-required: Conditionally required
        LineNum:
          type: number
          description: Specifies the position of the line in the collection of transaction lines. Positive integer
          x-intuit-required: Optional
        Amount:
          type: number
          description: The amount of the line item.
          x-intuit-required: Required
        Id:
          type: string
          description: 'The Id of the line item. Its use in requests is as folllows:

            If

            Idis greater than zero and exists for the company, the request is considered an update operation for a line item.


            If no

            Idis provided, the

            Idprovided is less than or equal to zero, or the

            Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.


            Available in all objects that use lines and support the update operation.'
          x-intuit-required: Required for update
      required:
      - Amount
  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.