QuickBooks: Create a change order

← changeorder operations · Get started · OpenAPI downloads

Contract 2026-10-20 · Operation quickbooks.changeorder.create_a_change_order

Provider route: POST /v3/company/{realmID}/changeorder. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/quickbooks with npm, or alter-sdk-quickbooks with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { QuickBooksIntegration } from "@alter-ai/quickbooks";

async function execute(input: Parameters<QuickBooksIntegration["changeorder"]["create"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new QuickBooksIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.changeorder.create(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_quickbooks import QuickBooksIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = QuickBooksIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.changeorder.create(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Optional	Additional keys: not allowed
query.minorversion	integer	Optional	Must equal: 75
query.requestid	string	Optional	Minimum length: 1
body	object	Required within parent	Fields not accepted: Id, SyncToken Additional keys: not allowed
body.AcceptedBy	string	Optional	Name of the customer or representative who accepted the change order. Populated when TxnStatus is set to Accepted .
body.AcceptedDate	string	Optional	Date the change order was accepted. Populated when TxnStatus is set to Accepted .
body.ApplyTaxAfterDiscount	JSON	Optional	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.
body.ApplyTaxAfterDiscount (anyOf 1)	boolean	Alternative
body.ApplyTaxAfterDiscount (anyOf 2)	string	Alternative	One of: true, false
body.BillEmail	Model	Optional	Expand Full update companyinfo — request body — body Email Email address where the change order is sent. Required when EmailStatus is set to NeedToSend . Conditionally required
body.CustomerMemo	Model	Optional	Expand Void an invoice — request body — body Customer Memo User-entered message to the customer; visible on the Change Order document sent to the customer.
body.CustomerRef	Model	Required within parent	Expand Create a purchase order — request body — body Ship To 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.
body.DocNumber	string	Optional	Reference number for the change order (for example, CO-001 ). If not provided, the value is null.
body.EmailStatus	string	Optional	Email status of the change order. Valid values: NotSet , NeedToSend , EmailSent .
body.ExpirationDate	string	Optional	Date by which the change order must be accepted before it expires.
body.Line	array	Required within parent	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.
body.Line[]	Model	Each item	Expand Create a change order — request body — body Line item
body.LinkedTxn	array	Optional	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 .
body.LinkedTxn[]	Model	Each item	Expand Create a bill — request body — body Linked Txn item
body.MetaData	Model	Optional	Expand Read a bill — response body — Bill Meta Data Descriptive information about the object. The MetaData values are set by Data Services and are read only for all applications.
body.PrintStatus	string	Optional	Printing status of the change order. Valid values: NotSet , NeedToPrint , PrintComplete .
body.PrivateNote	string	Optional	Organization-private note about the change order. This note does not appear on documents sent to the customer.
body.ProjectRef	Model	Required within parent	Expand Create a purchase order — request body — body Ship To 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.
body.TotalAmt	JSON	Optional	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. Decimal string Read only: true
body.TotalAmt (anyOf 1)	number	Alternative
body.TotalAmt (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?$
body.TotalCostAmount	JSON	Optional	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. Decimal string Read only: true
body.TotalCostAmount (anyOf 1)	number	Alternative
body.TotalCostAmount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?$
body.TxnDate	string	Optional	The date entered by the user when this transaction occurred. If not supplied, the current date on the server is used.
body.TxnStatus	string	Optional	Current status of the change order. Valid values: Pending , Accepted , Closed , Rejected .
body.TxnTaxDetail	Model	Optional	Expand Create a bill — request body — body Txn Tax Detail Tax details for the transaction. Captures sales taxes calculated based on tax codes referenced by the transaction lines.
body.domain	string	Optional
body.sparse	boolean	Optional

Referenced models: Full update companyinfo — request body — body Email, Read a bill — response body — Bill Meta Data, Create a bill — request body — body Linked Txn item, Void an invoice — request body — body Customer Memo, Create a purchase order — request body — body Ship To, Create a change order — request body — body Line item, Create a bill — request body — body Txn Tax Detail

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: allowed
time	string	Optional
ChangeOrder	Model	Optional	Expand Read a change order — response body — Change Order

Referenced models: Read a change order — response body — Change Order

Policy, approvals and errors

SDK function policy ID: quickbooks.changeorder.create_a_change_order. Catalog operation: changeorder/create_a_change_order. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Official provider source