Use cases

Here are use cases that demonstrate how to use the Project API for a few transactions. To demonstrate these use cases, we have added support for a few transactions so that you can configure a project ID.

App integration

The following figure provides an overview of how to integrate the Project API with your app.

qbo/docs/workflows/manage-projects/project-integration-diagram.png
qbo/docs/workflows/manage-projects/project-integration-diagram.png

x

Use case 1: Add an invoice transaction to a project

Step 1: Create or read a project. Use projectManagementCreateProject (mutation) or projectManagementProject (query).

Step 2: Create an invoice using the Accounting REST API and set the ProjectRef attributes with values from the project. For information about creating an invoice, see Create basic invoices.

Create invoice request using ProjectRef

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
   {
      "TxnDate": "2024-06-26",
      "CurrencyRef": {
         "value": "USD",
         "name": "United States Dollar"
      },
      "LinkedTxn": [],
      "Line": [
         {
            "Id": "1",
            "LineNum": 1,
            "Description": "Test1",
            "Amount": 50.99,
            "DetailType": "SalesItemLineDetail",
            "SalesItemLineDetail": {
               "ItemRef": {
                  "value": "2",
                  "name": "Hours"
               },
               "UnitPrice": 50.99,
               "Qty": 1,
               "ItemAccountRef": {
                  "value": "5",
                  "name": "Sales"
               },
               "TaxCodeRef": {
                  "value": "NON"
               }
            }
         },
         {
            "Amount": 50.99,
            "DetailType": "SubTotalLineDetail",
            "SubTotalLineDetail": {}
         }
      ],
      "Tag": [],
      "ProjectRef": {
         "value": "393363026"
      },
      "CustomerRef": {
         "value": "1",
         "name": "Test Customer"
      },
      "BillAddr": {
         "Id": "4",
         "Lat": "INVALID",
         "Long": "INVALID"
      },
      "FreeFormAddress": false,
      "SalesTermRef": {
         "value": "3",
         "name": "Net 30"
      },
      "TotalAmt": 50.99,
      "Balance": 50.99
   }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
   {
      "Invoice": {
         "Id": "5",
         "SyncToken": "0",
         "MetaData": {
            "CreateTime": "2024-06-26T09:20:16-07:00",
            "LastModifiedByRef": {
               "value": "9341452110907680"
            },
            "LastUpdatedTime": "2024-06-26T09:20:16-07:00"
         },
         "TxnDate": "2024-06-26",
         "CurrencyRef": {
            "value": "USD",
            "name": "United States Dollar"
         },
         "LinkedTxn": [],
         "Line": [
            {
               "Id": "1",
               "LineNum": 1,
               "Description": "Test1",
               "Amount": 50.99,
               "DetailType": "SalesItemLineDetail",
               "SalesItemLineDetail": {
                  "ItemRef": {
                     "value": "2",
                     "name": "Hours"
                  },
                  "UnitPrice": 50.99,
                  "Qty": 1,
                  "ItemAccountRef": {
                     "value": "5",
                     "name": "Sales"
                  },
                  "TaxCodeRef": {
                     "value": "NON"
                  }
               }
            },
            {
               "Amount": 50.99,
               "DetailType": "SubTotalLineDetail",
               "SubTotalLineDetail": {}
            }
         ],
         "ProjectRef": {
            "value": "393363026"
         },
         "CustomerRef": {
            "value": "1",
            "name": "Test Customer"
         },
         "BillAddr": {
            "Id": "2"
         },
         "ShipAddr": {
            "Id": "2"
         },
         "FreeFormAddress": true,
         "ShipFromAddr": {
            "Id": "5",
            "Line1": "2600 Marine Way",
            "Line2": "Mountain view, CA  94043 US"
         },
         "SalesTermRef": {
            "value": "3",
            "name": "Net 30"
         },
         "DueDate": "2024-07-26",
         "TotalAmt": 50.99,
         "Balance": 50.99
      },
      "time": "2024-06-26T09:20:16.310-07:00"
   }
Use case 2: Add an estimate transaction to a project

Step 1: Create or read a project. Use projectManagementCreateProject (mutation) or projectManagementProject (query).

Step 2: Create an estimate using the Accounting REST API and set the ProjectRef attributes with values from the project. For information about referencing a project to an estimate, see Estimate.

Create estimate request using ProjectRef

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
   {
      "TotalAmt": 31.5,
      "BillEmail": {
         "Address": "Cool_Cars@intuit.com"
      },
      "CustomerMemo": {
         "value": "Thank you for your business and have a great day!"
      },
      "ShipAddr": {
         "City": "Half Moon Bay",
         "Line1": "65 Ocean Dr.",
         "PostalCode": "94213",
         "Lat": "37.4300318",
         "Long": "-122.4336537",
         "CountrySubDivisionCode": "CA",
         "Id": "4"
      },
      "PrintStatus": "NeedToPrint",
      "EmailStatus": "NotSet",
      "BillAddr": {
         "City": "Half Moon Bay",
         "Line1": "65 Ocean Dr.",
         "PostalCode": "94213",
         "Lat": "37.4300318",
         "Long": "-122.4336537",
         "CountrySubDivisionCode": "CA",
         "Id": "4"
      },
      "Line": [
         {
            "Description": "Pest Control Services",
            "DetailType": "SalesItemLineDetail",
            "SalesItemLineDetail": {
               "TaxCodeRef": {
                  "value": "NON"
                  },
                  "Qty": 1,
                  "UnitPrice": 35,
                  "ItemRef": {
                  "name": "Pest Control",
                  "value": "1"
               }
            },
            "LineNum": 1,
            "Amount": 35.0,
            "Id": "1"
         },
         {
            "DetailType": "SubTotalLineDetail",
            "Amount": 35.0,
            "SubTotalLineDetail": {}
         },
         {
            "DetailType": "DiscountLineDetail",
            "Amount": 3.5,
            "DiscountLineDetail": {
               "DiscountAccountRef": {
                  "name": "Discounts given",
                  "value": "86"
               },
               "PercentBased": true,
               "DiscountPercent": 10
            }
         }
      ],
      "ProjectRef": {
         "value": "493722274"
      },
      "CustomerRef": {
         "value": "13"
      },
      "TxnTaxDetail": {
      "TotalTax": 0
      },
      "ApplyTaxAfterDiscount": false
   }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
   {
      "Estimate": {
         "domain": "QBO",
         "sparse": false,
         "Id": "14",
         "SyncToken": "0",
         "MetaData": {
            "CreateTime": "2024-12-31T09:18:57-08:00",
            "LastUpdatedTime": "2024-12-31T09:18:57-08:00"
         },
         "CustomField": [],
         "TxnDate": "2024-12-31",
         "CurrencyRef": {
            "value": "USD",
            "name": "United States Dollar"
         },
         "TxnStatus": "Pending",
         "Line": [
            {
               "Id": "1",
               "LineNum": 1,
               "Description": "Pest Control Services",
               "Amount": 35.00,
               "DetailType": "SalesItemLineDetail",
               "SalesItemLineDetail": {
                  "ItemRef": {
                     "value": "1",
                     "name": "Sales"
                  },
                  "UnitPrice": 35,
                  "Qty": 1,
                  "ItemAccountRef": {
                     "value": "5",
                     "name": "Sales"
                  },
                  "TaxCodeRef": {
                     "value": "NON"
                  }
               }
            },
            {
               "Amount": 35.00,
               "DetailType": "SubTotalLineDetail",
               "SubTotalLineDetail": {}
            },
            {
               "Amount": 3.50,
               "DetailType": "DiscountLineDetail",
               "DiscountLineDetail": {
                  "PercentBased": true,
                  "DiscountPercent": 10,
                  "DiscountAccountRef": {
                     "value": "86",
                     "name": "General business expenses:Uniforms"
                  }
               }
            }
         ],
         "ProjectRef": {
            "value": "493722274"
         },
         "CustomerRef": {
            "value": "14",
            "name": "Demo Address Test 3"
         },
         "CustomerMemo": {
            "value": "Thank you for your business and have a great day!"
         },
         "BillAddr": {
            "Id": "13",
            "Line1": "65 Ocean Dr.",
            "City": "Half Moon Bay",
            "CountrySubDivisionCode": "CA",
            "PostalCode": "94213"
         },
         "ShipAddr": {
            "Id": "14",
            "Line1": "65 Ocean Dr.",
            "City": "Half Moon Bay",
            "CountrySubDivisionCode": "CA",
            "PostalCode": "94213"
         },
         "FreeFormAddress": true,
         "ShipFromAddr": {
            "Id": "15",
            "Line1": "2600 Marine Way",
            "Line2": "Mountain View, CA  94043-1126",
            "Line3": "USA"
         },
         "TotalAmt": 31.50,
         "ApplyTaxAfterDiscount": false,
         "PrintStatus": "NeedToPrint",
         "EmailStatus": "NotSet",
         "BillEmail": {
            "Address": "Cool_Cars@intuit.com"
         }
      },
      "time": "2024-12-31T09:18:56.821-08:00"
   }
Use case 3: Attach a bill to a project

Step 1: Create or read a project. Use projectManagementCreateProject (mutation) or projectManagementProject (query).

Step 2: Create a bill using the Accounting REST API and set the ProjectRef attributes with values from the project. For information about referencing a project to a bill, see Bill.

Create bill request using ProjectRef

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
   {
      "Line": [
         {
            "DetailType": "AccountBasedExpenseLineDetail",
            "Amount": 200.0,
            "Id": "1",
            "ProjectRef":
               {
                  "value": "493722274"
               },
            "AccountBasedExpenseLineDetail": {
               "AccountRef": {
                  "value": "7"
               }
            }
         }
      ],
      "VendorRef": {
         "value": "15"
      }
   }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
   {
      "Bill": {
         "DueDate": "2024-12-31",
         "VendorAddr": {
            "Id": "16",
            "Line1": "Dianne's Auto Shop",
            "Line2": "Dianne Bradley",
            "Line3": "29834 Mustang Ave.",
            "City": "Millbrae",
            "Country": "U.S.A",
            "CountrySubDivisionCode": "CA",
            "PostalCode": "94030"
         },
         "Balance": 200.00,
         "domain": "QBO",
         "sparse": false,
         "Id": "15",
         "SyncToken": "0",
         "MetaData": {
            "CreateTime": "2024-12-31T09:31:19-08:00",
            "LastModifiedByRef": {
               "value": "9341453183669693"
            },
            "LastUpdatedTime": "2024-12-31T09:31:19-08:00"
         },
         "TxnDate": "2024-12-31",
         "CurrencyRef": {
            "value": "USD",
            "name": "United States Dollar"
         },
         "Line": [
            {
               "Id": "1",
               "LineNum": 1,
               "Amount": 200.00,
               "LinkedTxn": [],
               "DetailType": "AccountBasedExpenseLineDetail",
               "AccountBasedExpenseLineDetail": {
                  "AccountRef": {
                     "value": "7",
                     "name": "Billable Expense Income"
                  },
                  "BillableStatus": "NotBillable",
                  "TaxCodeRef": {
                     "value": "NON"
                  }
               },
               "ProjectRef": {
                  "value": "493722274"
               }
            }
         ],
         "VendorRef": {
            "value": "15",
            "name": "Dianne's Auto Shop"
         },
         "APAccountRef": {
            "value": "20",
            "name": "Accounts Payable (A/P)"
         },
         "TotalAmt": 200.00
      },
      "time": "2024-12-31T09:31:18.555-08:00"
   }
Use case 4: Attach a sales receipt to a project

Step 1: Create or read a project. Use projectManagementCreateProject (mutation) or projectManagementProject (query).

Step 2: Create a sales receipt using the Accounting REST API and send the ProjectRef attributes with values from the project. For information about referencing a project to a sales receipt, see SalesReceipt.

Create sales receipt request using ProjectRef

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
   {
      "Line": [{
         "Id": "1",
         "LineNum": 1,
         "Description": "Pest Control Services",
         "Amount": 35.0,
         "DetailType": "SalesItemLineDetail",
         "ProjectRef": {
            "value": "493722274"
         },
         "SalesItemLineDetail": {
            "ItemRef": {
               "value": "1",
               "name": "Pest Control"
            },
            "UnitPrice": 35,
            "Qty": 1,
            "TaxCodeRef": {
               "value": "NON"
            }
         }
      }]
   }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
   {
      "SalesReceipt": {
         "domain": "QBO",
         "sparse": false,
         "Id": "16",
         "SyncToken": "0",
         "MetaData": {
            "CreateTime": "2025-01-02T09:39:14-08:00",
            "LastUpdatedTime": "2025-01-02T09:39:14-08:00"
         },
         "CustomField": [],
         "TxnDate": "2025-01-02",
         "CurrencyRef": {
            "value": "USD",
            "name": "United States Dollar"
         },
         "Line": [
            {
               "Id": "1",
               "LineNum": 1,
               "Description": "Pest Control Services",
               "Amount": 35.00,
               "DetailType": "SalesItemLineDetail",
               "SalesItemLineDetail": {
                  "ItemRef": {
                     "value": "1",
                     "name": "Sales"
                  },
                  "UnitPrice": 35,
                  "Qty": 1,
                  "ItemAccountRef": {
                     "value": "5",
                     "name": "Sales"
                  },
                  "TaxCodeRef": {
                     "value": "NON"
                  }
               }
            },
            {
               "Amount": 35.00,
               "DetailType": "SubTotalLineDetail",
               "SubTotalLineDetail": {}
            }
         ],
         "ShipFromAddr": {
            "Id": "17",
            "Line1": "2600 Marine Way",
            "Line2": "Mountain View, CA  94043-1126",
            "Line3": "USA"
         },
         "TotalAmt": 35.00,
         "ApplyTaxAfterDiscount": false,
         "PrintStatus": "NeedToPrint",
         "EmailStatus": "NotSet",
         "Balance": 0,
         "DepositToAccountRef": {
            "value": "18",
            "name": "Payments to deposit"
         }
      },
      "time": "2025-01-02T09:39:14.026-08:00"
   }
Use case 5: Create a project estimate

Note

Note: Project estimate is available only for QuickBooks Online Advanced and Intuit Enterprise Suite subscription plans. Project estimate is not available for non-US regions or Plus subscriptions.

If a ProjectRef value is passed when you create an estimate, a project estimate is created instead of a financial proposal estimate.

Here are some estimate use cases:

For details about estimates, see Estimate in the REST API Reference.

Create a financial proposal estimate

Create an estimate for a customer by passing the customer ID in CustomerRef.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
   {
      "TotalAmt": 100.5,
      "BillEmail": {
         "Address": "Cool_Cars@intuit.com"
      },
      "CustomerMemo": {
         "value": "Thank you for your business and have a great day!"
      },
      "ShipAddr": {
         "City": "Half Moon Bay",
         "Line1": "65 Ocean Dr.",
         "PostalCode": "94213",
         "Lat": "37.4300318",
         "Long": "-122.4336537",
         "CountrySubDivisionCode": "CA",
         "Id": "4"
      },
      "PrintStatus": "NeedToPrint",
      "EmailStatus": "NotSet",
      "BillAddr": {
         "City": "Half Moon Bay",
         "Line1": "65 Ocean Dr.",
         "PostalCode": "94213",
         "Lat": "37.4300318",
         "Long": "-122.4336537",
         "CountrySubDivisionCode": "CA",
         "Id": "4"
      },
      "Line": [
         {
            "Description": "Pest Control Services",
            "DetailType": "SalesItemLineDetail",
            "SalesItemLineDetail": {
               "TaxCodeRef": {
                  "value": "NON"
               },
               "Qty": 1,
               "UnitPrice": 126,
               "ItemRef": {
                  "name": "Pest Control",
                  "value": "1"
               }
            },
            "LineNum": 1,
            "Amount": 126.0,
            "CostAmount": 120.0,
            "HomeCostAmount": 120.0,
            "Id": "1"
         },
         {
            "DetailType": "SubTotalLineDetail",
            "Amount": 126.0,
            "SubTotalLineDetail": {}
         }
      ],
      "CustomerRef": {
         "value": "2"
      },
      "TxnTaxDetail": {
         "TotalTax": 0
      },
      "ApplyTaxAfterDiscount": false
   }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
   {
      "Estimate": {
         "domain": "QBO",
         "sparse": false,
         "Id": "4",
         "SyncToken": "0",
         "MetaData": {
            "CreateTime": "2026-02-02T12:26:39-08:00",
            "LastUpdatedTime": "2026-02-02T12:26:39-08:00"
         },
         "CustomField": [],
         "TxnDate": "2026-02-02",
         "CurrencyRef": {
            "value": "USD",
            "name": "United States Dollar"
         },
         "TxnStatus": "Pending",
         "Line": [
            {
               "Id": "1",
               "LineNum": 1,
               "Description": "Pest Control Services",
               "Amount": 126.0,
               "DetailType": "SalesItemLineDetail",
               "SalesItemLineDetail": {
                  "ItemRef": {
                     "value": "1",
                     "name": "test"
                  },
                  "UnitPrice": 126,
                  "Qty": 1,
                  "ItemAccountRef": {
                     "value": "4",
                     "name": "Services"
                  },
                  "TaxCodeRef": {
                     "value": "NON"
                  }
               },
               "CustomExtensions": []
            },
            {
               "Amount": 126.0,
               "DetailType": "SubTotalLineDetail",
               "SubTotalLineDetail": {}
            }
         ],
         "ProjectRef": {
            "value": "447322633"
         },
         "CustomerRef": {
            "value": "2",
            "name": "Tets"
         },
         "CustomerMemo": {
            "value": "Thank you for your business and have a great day!"
         },
         "BillAddr": {
            "Id": "11",
            "Line1": "65 Ocean Dr.",
            "City": "Half Moon Bay",
            "CountrySubDivisionCode": "CA",
            "PostalCode": "94213"
         },
         "ShipAddr": {
            "Id": "12",
            "Line1": "65 Ocean Dr.",
            "City": "Half Moon Bay",
            "CountrySubDivisionCode": "CA",
            "PostalCode": "94213"
         },
         "FreeFormAddress": true,
         "ShipFromAddr": {
            "Id": "13",
            "Line1": "2700 Coast Ave",
            "Line2": "Mountain View, CA 94043 US"
         },
         "TotalAmt": 126.0,
         "ApplyTaxAfterDiscount": false,
         "PrintStatus": "NeedToPrint",
         "EmailStatus": "NotSet",
         "BillEmail": {
            "Address": "Cool_Cars@intuit.com"
         }
      },
      "time": "2026-02-02T12:26:38.138-08:00"
   }

An estimate is created.

qbo/docs/workflows/manage-projects/projectestimate-usecase1.png
qbo/docs/workflows/manage-projects/projectestimate-usecase1.png

x

Create a project estimate for Intuit Enterprise Suite or QuickBooks Online Advanced

Create an estimate by passing the project ID in ProjectRef.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
   {
      "TotalAmt": 100.5,
      "BillEmail": {
         "Address": "Cool_Cars@intuit.com"
      },
      "CustomerMemo": {
         "value": "Thank you for your business and have a great day!"
      },
      "ShipAddr": {
         "City": "Half Moon Bay",
         "Line1": "65 Ocean Dr.",
         "PostalCode": "94213",
         "Lat": "37.4300318",
         "Long": "-122.4336537",
         "CountrySubDivisionCode": "CA",
         "Id": "4"
      },
      "PrintStatus": "NeedToPrint",
      "EmailStatus": "NotSet",
      "BillAddr": {
         "City": "Half Moon Bay",
         "Line1": "65 Ocean Dr.",
         "PostalCode": "94213",
         "Lat": "37.4300318",
         "Long": "-122.4336537",
         "CountrySubDivisionCode": "CA",
         "Id": "4"
      },
      "Line": [
         {
            "Description": "Pest Control Services",
            "DetailType": "SalesItemLineDetail",
            "SalesItemLineDetail": {
               "TaxCodeRef": {
                  "value": "NON"
               },
               "Qty": 1,
               "UnitPrice": 126,
               "ItemRef": {
                  "name": "Pest Control",
                  "value": "1"
               }
            },
            "LineNum": 1,
            "Amount": 126.0,
            "CostAmount": 120.0,
            "HomeCostAmount": 120.0,
            "Id": "1"
         },
         {
            "DetailType": "SubTotalLineDetail",
            "Amount": 126.0,
            "SubTotalLineDetail": {}
         }
      ],
      "CustomerRef": {
         "value": "2"
      },
      "ProjectRef": {
         "value": "447322633"
      },
      "TxnTaxDetail": {
         "TotalTax": 0
      },
      "ApplyTaxAfterDiscount": false
   }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
   {
      "Estimate": {
         "domain": "QBO",
         "sparse": false,
         "Id": "5",
         "SyncToken": "0",
         "MetaData": {
            "CreateTime": "2026-02-02T12:26:39-08:00",
            "LastUpdatedTime": "2026-02-02T12:26:39-08:00"
         },
         "CustomField": [],
         "TxnDate": "2026-02-02",
         "CurrencyRef": {
            "value": "USD",
            "name": "United States Dollar"
         },
         "TxnStatus": "Pending",
         "Line": [
            {
               "Id": "1",
               "LineNum": 1,
               "Description": "Pest Control Services",
               "Amount": 126.0,
               "DetailType": "SalesItemLineDetail",
               "SalesItemLineDetail": {
                  "ItemRef": {
                     "value": "1",
                     "name": "test"
                  },
                  "UnitPrice": 126,
                  "Qty": 1,
                  "ItemAccountRef": {
                     "value": "4",
                     "name": "Services"
                  },
                  "TaxCodeRef": {
                     "value": "NON"
                  }
               },
               "CustomExtensions": []
            },
            {
               "Amount": 126.0,
               "DetailType": "SubTotalLineDetail",
               "SubTotalLineDetail": {}
            }
         ],
         "ProjectRef": {
            "value": "447322633"
         },
         "CustomerRef": {
            "value": "2",
            "name": "Tets"
         },
         "CustomerMemo": {
            "value": "Thank you for your business and have a great day!"
         },
         "BillAddr": {
            "Id": "11",
            "Line1": "65 Ocean Dr.",
            "City": "Half Moon Bay",
            "CountrySubDivisionCode": "CA",
            "PostalCode": "94213"
         },
         "ShipAddr": {
            "Id": "12",
            "Line1": "65 Ocean Dr.",
            "City": "Half Moon Bay",
            "CountrySubDivisionCode": "CA",
            "PostalCode": "94213"
         },
         "FreeFormAddress": true,
         "ShipFromAddr": {
            "Id": "13",
            "Line1": "2700 Coast Ave",
            "Line2": "Mountain View, CA 94043 US"
         },
         "TotalAmt": 126.0,
         "ApplyTaxAfterDiscount": false,
         "PrintStatus": "NeedToPrint",
         "EmailStatus": "NotSet",
         "BillEmail": {
            "Address": "Cool_Cars@intuit.com"
         }
      },
      "time": "2026-02-02T12:26:38.138-08:00"
   }

A project estimate is created.

qbo/docs/workflows/manage-projects/projectestimate-usecase2.png
qbo/docs/workflows/manage-projects/projectestimate-usecase2.png

x

Here is the customization widget with the Project estimate conversion setting on.

qbo/docs/workflows/manage-projects/projectestimate-usecase3.png
qbo/docs/workflows/manage-projects/projectestimate-usecase3.png

x

Create a financial proposal estimate with project reference for QuickBooks Online Plus subscriptions

Create an estimate and pass the project ID in ProjectRef. In this case, for QuickBooks Online Plus subscriptions, passing the Project ID in ProjectRef does not create a Project Estimate but instead creates a Financial Proposal Estimate.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
   {
      "TotalAmt": 100.5,
      "BillEmail": {
         "Address": "Cool_Cars@intuit.com"
      },
      "CustomerMemo": {
         "value": "Thank you for your business and have a great day!"
      },
      "ShipAddr": {
         "City": "Half Moon Bay",
         "Line1": "65 Ocean Dr.",
         "PostalCode": "94213",
         "Lat": "37.4300318",
         "Long": "-122.4336537",
         "CountrySubDivisionCode": "CA",
         "Id": "4"
      },
      "PrintStatus": "NeedToPrint",
      "EmailStatus": "NotSet",
      "BillAddr": {
         "City": "Half Moon Bay",
         "Line1": "65 Ocean Dr.",
         "PostalCode": "94213",
         "Lat": "37.4300318",
         "Long": "-122.4336537",
         "CountrySubDivisionCode": "CA",
         "Id": "4"
      },
      "Line": [
         {
            "Description": "Pest Control Services",
            "DetailType": "SalesItemLineDetail",
            "SalesItemLineDetail": {
               "TaxCodeRef": {
                  "value": "NON"
               },
               "Qty": 1,
               "UnitPrice": 126,
               "ItemRef": {
                  "name": "Pest Control",
                  "value": "1"
               }
            },
            "LineNum": 1,
            "Amount": 126.0,
            "CostAmount": 120.0,
            "HomeCostAmount": 120.0,
            "Id": "1"
         },
         {
            "DetailType": "SubTotalLineDetail",
            "Amount": 126.0,
            "SubTotalLineDetail": {}
         }
      ],
      "CustomerRef": {
         "value": "2"
      },
      "ProjectRef": {
         "value": "447322633"
      },
      "TxnTaxDetail": {
         "TotalTax": 0
      },
      "ApplyTaxAfterDiscount": false
   }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
   {
      "Estimate": {
         "domain": "QBO",
         "sparse": false,
         "Id": "5",
         "SyncToken": "0",
         "MetaData": {
            "CreateTime": "2026-02-02T12:26:39-08:00",
            "LastUpdatedTime": "2026-02-02T12:26:39-08:00"
         },
         "CustomField": [],
         "TxnDate": "2026-02-02",
         "CurrencyRef": {
            "value": "USD",
            "name": "United States Dollar"
         },
         "TxnStatus": "Pending",
         "Line": [
            {
               "Id": "1",
               "LineNum": 1,
               "Description": "Pest Control Services",
               "Amount": 126.0,
               "DetailType": "SalesItemLineDetail",
               "SalesItemLineDetail": {
                  "ItemRef": {
                     "value": "1",
                     "name": "test"
                  },
                  "UnitPrice": 126,
                  "Qty": 1,
                  "ItemAccountRef": {
                     "value": "4",
                     "name": "Services"
                  },
                  "TaxCodeRef": {
                     "value": "NON"
                  }
               },
               "CustomExtensions": []
            },
            {
               "Amount": 126.0,
               "DetailType": "SubTotalLineDetail",
               "SubTotalLineDetail": {}
            }
         ],
         "CustomerRef": {
            "value": "2",
            "name": "Tets"
         },
         "CustomerMemo": {
            "value": "Thank you for your business and have a great day!"
         },
         "BillAddr": {
            "Id": "11",
            "Line1": "65 Ocean Dr.",
            "City": "Half Moon Bay",
            "CountrySubDivisionCode": "CA",
            "PostalCode": "94213"
         },
         "ShipAddr": {
            "Id": "12",
            "Line1": "65 Ocean Dr.",
            "City": "Half Moon Bay",
            "CountrySubDivisionCode": "CA",
            "PostalCode": "94213"
         },
         "FreeFormAddress": true,
         "ShipFromAddr": {
            "Id": "13",
            "Line1": "2700 Coast Ave",
            "Line2": "Mountain View, CA 94043 US"
         },
         "TotalAmt": 126.0,
         "ApplyTaxAfterDiscount": false,
         "PrintStatus": "NeedToPrint",
         "EmailStatus": "NotSet",
         "BillEmail": {
            "Address": "Cool_Cars@intuit.com"
         }
      },
      "time": "2026-02-02T12:26:38.138-08:00"
   }

Here is a financial proposal estimate in the QuickBooks Online UI:

qbo/docs/workflows/manage-projects/projectestimate-usecase4.png
qbo/docs/workflows/manage-projects/projectestimate-usecase4.png

x

Here is the widget without a project estimate conversion:

qbo/docs/workflows/manage-projects/projectestimate-usecase5.png
qbo/docs/workflows/manage-projects/projectestimate-usecase5.png

x

Use case 6: Manage a project budget

Note

Note: Project Budget is available only for US companies subscribed to QuickBooks Online Advanced with the Construction Pack Add-on or Intuit Enterprise Suite, with the Projects feature enabled.

The Project Budget API allows you to create, read, update, and delete project-based budgets. Project budgets enable tracking of planned revenue and costs for specific projects, with support for detailed line items, view settings, metadata, and pagination for budget details.

Project budget use cases

Here are some project budget use cases:

Create a project budget

Step 1: Create or read a project. Use projectManagementCreateProject (mutation) or projectManagementProject (query). For an example of how to create a project, see Create a project.

Step 2: Create the project budget. Use businessPlanningCreateBudget (mutation) with the returned Project ID as linkedEntityId. Pass the ID returned from create or read project as the linkedEntityId value to create the project budget. Set budgetType to PROJECT.

Mutation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
   businessPlanningCreateBudget($budgetInput: BusinessPlanning_BudgetInput!) {
      businessPlanningCreateBudget(budgetInput: $budgetInput) {
         budget {
            budgetId
            budgetName
            budgetType
            startDate
            endDate
            linkedEntityId
            total
            state
            budgetMetaData {
               createdBy
               createdAt
            }
            budgetDetails {
               sequenceId
               order
               type
               itemId
               unitCost
               quantity
               amount
               description
               date
               accountId
               klassId
               locationId
            }
         }
      }
   }

Input

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
   {
      "budgetInput": {
         "budgetName": "Project STTA4123423TE",
         "budgetType": "PROJECT",
         "startDate": "2026-01-01",
         "endDate": "2026-12-31",
         "linkedEntityId": "791242075",
         "total": 50000.00,
         "viewSettings": {
            "archived": false,
            "budgetDetails": [
               {
                  "sequenceId": "1",
                  "order": "1",
                  "type": "ITEM",
                  "itemId": "5001",
                  "unitCost": 100.00,
                  "quantity": 10,
                  "amount": 1000.00,
                  "description": "Design Services",
                  "date": "2024-01-15",
                  "accountId": "79",
                  "klassId": "1001"
               },
               {
                  "sequenceId": "2",
                  "order": "2",
                  "type": "ITEM",
                  "itemId": "5002",
                  "unitCost": 150.00,
                  "quantity": 20,
                  "amount": 3000.00,
                  "description": "Development Services",
                  "date": "2024-02-01",
                  "accountId": "79"
               }
            ]
         }
      }
   }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
   {
      "data": {
         "businessPlanningCreateBudget": {
            "budget": {
               "budgetId": "100000001",
               "budgetName": "Project Alpha Budget",
               "budgetType": "PROJECT",
               "startDate": "2024-01-01",
               "endDate": "2024-12-31",
               "linkedEntityId": "53115889",
               "total": 50000.00,
               "state": "DRAFT",
               "syncToken": "0",
               "budgetMetaData": {
                  "createdBy": "user123",
                  "createdAt": "2024-01-15T10:30:00.000Z"
               },
               "budgetDetails": [
                  {
                     "sequenceId": "1",
                     "order": "1",
                     "type": "ITEM",
                     "itemId": "5001",
                     "unitCost": 100.00,
                     "quantity": 10,
                     "amount": 1000.00,
                     "description": "Design Services",
                     "date": "2024-01-15",
                     "accountId": "79",
                     "klassId": "1001",
                     "locationId": null
                  }
               ]
            },
            "clientMutationId": "create-budget-001"
         }
      }
   }
Read project budget

Retrieves a project budget.

Use businessPlanningBudget (mutation), passing the Budget ID as the budgetId value.

Query

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
   query businessPlanningBudget($budgetId: ID!) {
      businessPlanningBudget(budgetId: $budgetId) {
         budgetId
         budgetName
         budgetType
         startDate
         endDate
         linkedEntityId
         total
         state
         deleted
         budgetMetaData {
            createdBy
            createdAt
            lastUpdatedBy
            updatedAt
         }
         viewSettings {
            archived
         }
         budgetDetails {
            sequenceId
            order
            type
            itemId
            unitCost
            quantity
            amount
            description
            date
            accountId
            klassId
            locationId
            dimensions {
               id
               values
            }
            customFields {
               id
               values
            }
         }
      }
   }

Variables

1
2
3
   {
      "budgetId": "100000001"
   }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
   {
      "data": {
         "businessPlanningBudget": {
            "budgetId": "100000001",
            "budgetName": "Project Alpha Budget",
            "budgetType": "PROJECT",
            "startDate": "2024-01-01",
            "endDate": "2024-12-31",
            "linkedEntityId": "53115889",
            "total": 50000.00,
            "state": "DRAFT",
            "deleted": false,
            "budgetMetaData": {
               "createdBy": "user123",
               "createdAt": "2024-01-15T10:30:00.000Z",
               "lastUpdatedBy": "user123",
               "updatedAt": "2024-01-15T10:30:00.000Z"
            },
            "viewSettings": {
               "archived": false
            },
            "budgetDetails": [
               {
                  "sequenceId": "1",
                  "order": "1",
                  "type": "ITEM",
                  "itemId": "5001",
                  "unitCost": 100.00,
                  "quantity": 10,
                  "amount": 1000.00,
                  "description": "Design Services",
                  "date": "2024-01-15",
                  "accountId": "79",
                  "klassId": "1001",
                  "locationId": null,
                  "dimensions": [],
                  "customFields": []
               }
            ]
         }
      }
   }
Read project budget details (line items) with pagination

For budgets with many line items, use budgetDetailsPaginated instead of budgetDetails for improved performance and control over sorting, filtering, and cursor-based traversal.

Query

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
   query businessPlanningBudget($budgetId: ID!, $budgetDetailsInput: BusinessPlanning_FetchBudgetDetailsInput) {
      businessPlanningBudget(budgetId: $budgetId) {
         budgetId
         budgetName
         budgetType
         startDate
         endDate
         linkedEntityId
         total
         state
         syncToken
         budgetDetailsPaginated(budgetDetailsInput: $budgetDetailsInput) {
            edges {
               cursor
               node {
                  sequenceId
                  order
                  type
                  itemId
                  unitCost
                  quantity
                  amount
                  description
                  date
                  accountId
                  klassId
                  locationId
               }
            }
            pageInfo {
               startCursor
               endCursor
               hasPreviousPage
               hasNextPage
            }
            totalCount
         }
      }
   }

Variables

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
   {
      "budgetId": "100000001",
      "budgetDetailsInput": {
         "first": 10,
         "after": null,
         "sortBy": [
            {
               "field": "SEQUENCE_ID",
               "direction": "ASC"
            }
         ]
      }
   }

Paginated response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
   {
      "data": {
         "businessPlanningBudget": {
            "budgetId": "100000001",
            "budgetName": "Project Alpha Budget",
            "budgetType": "PROJECT",
            "budgetDetailsPaginated": {
               "edges": [
                  {
                     "cursor": "YnVkZ2V0RGV0YWlsOjE=",
                     "node": {
                        "sequenceId": "1",
                        "order": "1",
                        "type": "ITEM",
                        "itemId": "5001",
                        "unitCost": 100.00,
                        "quantity": 10,
                        "amount": 1000.00,
                        "description": "Design Services",
                        "date": "2024-01-15",
                        "accountId": "79",
                        "klassId": "1001",
                        "locationId": null
                     }
                  }
               ],
               "pageInfo": {
                  "startCursor": "YnVkZ2V0RGV0YWlsOjE=",
                  "endCursor": "YnVkZ2V0RGV0YWlsOjE=",
                  "hasPreviousPage": false,
                  "hasNextPage": true
               },
               "totalCount": 25
            }
         }
      }
   }
Update a project budget

Updates an entire project budget.

Step 1: Use businessPlanningBudget (query) to get the budgetId value.

Step 2: Use businessPlanningUpdateBudget (mutation), passing the Budget ID as the budgetId value.

Mutation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
   mutation businessPlanningUpdateBudget($budgetInput: BusinessPlanning_BudgetInput!) {
      businessPlanningUpdateBudget(budgetInput: $budgetInput) {
         budget {
            budgetId
            budgetName
            budgetType
            startDate
            endDate
            linkedEntityId
            total
            state
            syncToken
            budgetMetaData {
               lastUpdatedBy
               updatedAt
            }
            budgetDetails {
               sequenceId
               order
               type
               itemId
               unitCost
               quantity
               amount
               description
               date
               accountId
               klassId
               locationId
            }
         }
         clientMutationId
      }
   }

Variables

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
   {
      "budgetInput": {
         "budgetId": "100000001",
         "budgetName": "Project Alpha Budget - Updated",
         "budgetType": "PROJECT",
         "startDate": "2024-01-01",
         "endDate": "2024-12-31",
         "linkedEntityId": "53115889",
         "total": 75000.00,
         "state": "LOCKED",
         "syncToken": "0",
         "budgetDetails": [
            {
               "sequenceId": "1",
               "order": "1",
               "type": "ITEM",
               "itemId": "5001",
               "unitCost": 150.00,
               "quantity": 15,
               "amount": 2250.00,
               "description": "Design Services - Extended",
               "date": "2024-01-15",
               "accountId": "79",
               "klassId": "1001"
            }
         ],
         "clientMutationId": "update-budget-001"
      }
   }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
   {
      "data": {
         "businessPlanningUpdateBudget": {
            "budget": {
               "budgetId": "100000001",
               "budgetName": "Project Alpha Budget - Updated",
               "budgetType": "PROJECT",
               "startDate": "2024-01-01",
               "endDate": "2024-12-31",
               "linkedEntityId": "53115889",
               "total": 75000.00,
               "state": "LOCKED",
               "syncToken": "1",
               "budgetMetaData": {
                  "lastUpdatedBy": "user123",
                  "updatedAt": "2024-01-16T14:00:00.000Z"
               },
               "budgetDetails": [
                  {
                     "sequenceId": "1",
                     "order": "1",
                     "type": "ITEM",
                     "itemId": "5001",
                     "unitCost": 150.00,
                     "quantity": 15,
                     "amount": 2250.00,
                     "description": "Design Services - Extended",
                     "date": "2024-01-15",
                     "accountId": "79",
                     "klassId": "1001",
                     "locationId": null
                  }
               ]
            },
            "clientMutationId": "update-budget-001"
         }
      }
   }
Update specific lines of a project budget

When updating or deleting line items, you must pass the correct sequenceId from the original query or response. If the sequenceId value doesn’t match, the system creates a new line instead of updating. This can cause duplicate lines or failed deletes.

To delete a line item use an update call (businessPlanningUpdateBudget) with the deleted: true flag on the line item:

1
2
3
4
5
6
7
8
   mutation { businessPlanningUpdateBudget
      (input: {
                 budgetId: "123" budgetName: "My Project Budget"
                 syncToken: "5"budgetDetails: [
                    { sequenceId: "456"  # The line item to delete deleted: true}
                 ]
      })
   }
Delete project budget

Deletes one or more project budgets.

Step 1: Use businessPlanningUpdateBudget (mutation) to get budgetId values.

Step 2: Delete the project budget, using businessPlanningDeleteBudgets (mutation) with the IDs of the budgets to delete.

Mutation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
   mutation businessPlanningDeleteBudgets($budgetIdsInput: BusinessPlanning_BudgetIdsInput!) {
      businessPlanningDeleteBudgets(budgetIdsInput: $budgetIdsInput) {
         budgetResponseList {
            budgetId
            status
            description
         }
         clientMutationId
      }
   }

Variables

1
2
3
4
5
6
   {
      "budgetIdsInput": {
         "budgetIds": ["100000001", "100000002"],
         "clientMutationId": "delete-budgets-001"
      }
   }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
   {
      "data": {
         "businessPlanningDeleteBudgets": {
            "budgetResponseList": [
               {
                  "budgetId": "100000001",
                  "status": true,
                  "description": "Budget deleted successfully"
               },
               {
                  "budgetId": "100000002",
                  "status": true,
                  "description": "Budget deleted successfully"
               }
            ],
            "clientMutationId": "delete-budgets-001"
         }
      }
   }
Use case 7: Create a change order

Note

Note: Change order creation is available only for US companies subscribed to QuickBooks Online Advanced with the Construction Pack Add-on or Intuit Enterprise Suite, with the Projects feature enabled.

In construction, field services, and project-based businesses, the original scope of work often shifts after a project begins. Here are some common scenarios that require a change order:

In QuickBooks Online, a change order is a project-scoped transaction that represents a formal modification to an existing approved estimate tied to a project:

The change order captures additions, removals, or adjustments to the original scope of work, such as extra materials, revised labor costs, or newly discovered tasks, without altering the original estimate record. Change orders are surfaced natively in the QuickBooks Online Projects experience and roll up into the project’s total budget, helping contractors and project managers track approved scope changes alongside original estimates.

Working with change orders

Before you create a change order, there must be an existing project for the company (created through the UI or the Projects API) and an existing project estimate that includes a ProjectRef value pointing to the target project. This is the parent estimate to be linked to the change order. A change order applies to one parent estimate.

A change order is linked to an existing project estimate through the LinkedTxn array on each line of the change order, referencing the parent estimate’s ID with TxnType: "Estimate". LinkedTxn is mandatory on every line. All lines within a change order must reference the same parent estimate (TxnId). The estimate referenced by TxnId must itself have a ProjectRef.

Change order use cases

Here are some use cases:

Create a change order

Creates a change order linked to an existing project estimate.

Step 1: Use Read an estimate to get the project ID.

Step 2: Create the change order, including the following in the request:

Request

POST /v3/company/{realmId}/changeorder

Request body

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 {
    "TxnDate": "2024-09-15",
    "ExpirationDate": "2024-10-15",
    "TxnStatus": "Pending",
    "ProjectRef": {
      "value": "39298034",
      "name": "Kitchen Renovation - Phase 2"
    },
    "LinkedTxn": [
        { "TxnId": "512", "TxnType": "Estimate" }
    ],
    "CustomerRef": {
      "value": "58",
      "name": "Acme Construction Corp"
    },
    "CustomerMemo": {
      "value": "This change order covers additional structural reinforcement discovered during demolition."
    },
    "PrivateNote": "Approved verbally by site manager on 2024-09-14.",
    "DocNumber": "CO-001",
    "Line": [
      {
        "LineNum": 1,
        "Description": "Structural steel — additional load-bearing beam (LB-200)",
        "Amount": 2400.00,
        "CostAmount": 600.00,
        "DetailType": "SalesItemLineDetail",
        "SalesItemLineDetail": {
           "ItemRef": {
              "value": "21",
              "name": "Structural Materials"
            },
            "UnitPrice": 800.00,
            "UnitCostPrice": 200.00,
        "Qty": 3,
        "TaxCodeRef": {
          "value": "TAX"
          }
        }
      },
      {
        "LineNum": 2,
        "Description": "Labor — structural reinforcement installation (20 hrs)",
        "Amount": 2000.00,
        "CostAmount": 1000.00,
        "DetailType": "SalesItemLineDetail",
        "SalesItemLineDetail": {
           "ItemRef": {
              "value": "7",
              "name": "Labor"
            },
            "UnitPrice": 100.00,
                "UnitCostPrice": 50.00,
            "Qty": 20,
            "TaxCodeRef": {
                "value": "NON"
            }
         }
      }
    ],
  "EmailStatus": "NeedToSend",
  "PrintStatus": "NeedToPrint",
  "BillEmail": {
      "Address": "client@acmeconstruction.com"
  },
  "TotalAmt": 4400.00,
  "TotalCostAmount": 1600.00
 }

Response

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
  {
    "ChangeOrder": {
      "Id": "621",
      "SyncToken": "0",
      "MetaData": {
        "CreateTime": "2024-09-15T08:30:00-07:00",
        "LastUpdatedTime": "2024-09-15T08:30:00-07:00"
      },
      "DocNumber": "CO-001",
      "TxnDate": "2024-09-15",
      "ExpirationDate": "2024-10-15",
      "TxnStatus": "Pending",
      "LinkedTxn": [
          { "TxnId": "512", "TxnType": "Estimate" }
      ],
      "ProjectRef": {
        "value": "39298034",
        "name": "Kitchen Renovation - Phase 2"
      },
      "CustomerRef": {
        "value": "58",
        "name": "Acme Construction Corp"
      },
      "CustomerMemo": {
        "value": "This change order covers additional structural reinforcement discovered during demolition."
      },
      "PrivateNote": "Approved verbally by site manager on 2024-09-14.",
      "Line": [
        {
          "Id": "1",
          "LineNum": 1,
          "Description": "Structural steel — additional load-bearing beam (LB-200)",
          "Amount": 2400.00,
          "CostAmount": 600.00,
          "DetailType": "SalesItemLineDetail",
          "SalesItemLineDetail": {
            "ItemRef": {
              "value": "21",
              "name": "Structural Materials"
            },
            "UnitPrice": 800.00,
            "UnitCostPrice": 200.00,
            "Qty": 3,
            "TaxCodeRef": {
              "value": "TAX"
            }
          },
          "LinkedTxn": [
            {
              "TxnId": "512",
              "TxnType": "Estimate"
            }
          ]
        },
        {
          "Id": "2",
          "LineNum": 2,
          "Description": "Labor — structural reinforcement installation (20 hrs)",
          "Amount": 2000.00,
          "CostAmount": 1000.00,
          "DetailType": "SalesItemLineDetail",
          "SalesItemLineDetail": {
            "ItemRef": {
              "value": "7",
              "name": "Labor"
            },
            "UnitPrice": 100.00,
            "UnitCostPrice": 50.00,
            "Qty": 20,
            "TaxCodeRef": {
              "value": "NON"
            }
          },
          "LinkedTxn": [
            {
              "TxnId": "512",
              "TxnType": "Estimate"
            }
          ]
        },
        {
          "Amount": 4400.00,
          "DetailType": "SubTotalLineDetail",
          "SubTotalLineDetail": {}
        }
      ],
      "TxnTaxDetail": {
        "TotalTax": 216.00
      },
      "TotalAmt": 4616.00,
      "TotalCostAmt": 1616.00,
      "ApplyTaxAfterDiscount": false,
      "PrintStatus": "NeedToPrint",
      "EmailStatus": "NeedToSend",
      "BillEmail": {
        "Address": "client@acmeconstruction.com"
      }
    },
    "time": "2024-09-15T08:30:00.000-07:00"
  }
Read a change order

Retrieves a single change order by its ID.

Use Read change order, passing the Change Order ID in the Id field.

Request

GET https://quickbooks.api.intuit.com/v3/company/9341453493041623/changeorder/621

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
  {
    "ChangeOrder": {
      "Id": "621",
      "SyncToken": "1",
      "MetaData": {
        "CreateTime": "2024-09-15T08:30:00-07:00",
        "LastUpdatedTime": "2024-09-16T11:00:00-07:00"
      },
      "DocNumber": "CO-001",
      "TxnDate": "2024-09-15",
      "TxnStatus": "Accepted",
      "AcceptedBy": "John Smith",
      "AcceptedDate": "2024-09-16",
      "LinkedTxn": [
          { "TxnId": "512", "TxnType": "Estimate" }
      ],
      "ProjectRef": {
        "value": "39298034",
        "name": "Kitchen Renovation - Phase 2"
      },
      "CustomerRef": {
        "value": "58",
        "name": "Acme Construction Corp"
      },
      "Line": [
        {
          "Id": "1",
          "LineNum": 1,
          "Description": "Structural steel — additional load-bearing beam (LB-200)",
          "Amount": 2400.00,
          "DetailType": "SalesItemLineDetail",
          "SalesItemLineDetail": {
            "ItemRef": { "value": "21", "name": "Structural Materials" },
            "UnitPrice": 800.00,
            "Qty": 3,
            "TaxCodeRef": { "value": "TAX" }
          },
          "LinkedTxn": [
            { "TxnId": "512", "TxnType": "Estimate" }
          ]
        },
        {
          "Id": "2",
          "LineNum": 2,
          "Description": "Labor — structural reinforcement installation (20 hrs)",
          "Amount": 2000.00,
          "DetailType": "SalesItemLineDetail",
          "SalesItemLineDetail": {
            "ItemRef": { "value": "7", "name": "Labor" },
            "UnitPrice": 100.00,
            "Qty": 20,
            "TaxCodeRef": { "value": "NON" }
          },
          "LinkedTxn": [
            { "TxnId": "512", "TxnType": "Estimate" }
          ]
        }
      ],
      "TotalAmt": 4616.00,
      "TxnTaxDetail": { "TotalTax": 216.00 },
      "PrintStatus": "PrintComplete",
      "EmailStatus": "EmailSent"
    },
    "time": "2024-09-16T11:00:00.000-07:00"
  }
Update a change order

Updates an existing change order. Only the fields that you include in the request body are modified. Lines present in the stored record but absent from the update request will be removed.

Step 1: Create or read a change order. Use POST /v3/company/{realmId}/changeorder or GET https://quickbooks.api.intuit.com/v3/company/…/changeorder/change_order_id.

Step 2: Use Full update change order. Include the Change Order ID in the Id field and the current SyncToken and send the complete desired state of the Line array using the POST operation.

Note

Note: When updating lines, include all existing lines you want to retain. Lines omitted from the update request will be deleted (full-replace behavior for the Line array). Always re-include LinkedTxn on every line. Request Body (Sparse Update — Status Change + New Line)

Request

POST /v3/company/{realmId}/changeorder

Request body

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
  {
      "Id": "621",
      "SyncToken": "1",
      "sparse": true,
      "TxnStatus": "Accepted",
      "AcceptedBy": "John Smith",
      "AcceptedDate": "2024-09-16",
      "LinkedTxn": [
          { "TxnId": "512", "TxnType": "Estimate" }
      ],
      "Line": [
          {
              "Id": "1",
              "LineNum": 1,
              "Description": "Structural steel — additional load-bearing beam (LB-200)",
              "Amount": 2400.00,
              "DetailType": "SalesItemLineDetail",
              "SalesItemLineDetail": {
                  "ItemRef": { "value": "21", "name": "Structural Materials" },
                  "UnitPrice": 800.00,
                  "Qty": 3,
                  "TaxCodeRef": { "value": "TAX" }
              }
          },
          {
              "Id": "2",
              "LineNum": 2,
              "Description": "Labor — structural reinforcement installation (20 hrs)",
              "Amount": 2000.00,
              "DetailType": "SalesItemLineDetail",
              "SalesItemLineDetail": {
                  "ItemRef": { "value": "7", "name": "Labor" },
                  "UnitPrice": 100.00,
                  "Qty": 20,
                  "TaxCodeRef": { "value": "NON" }
              }
          },
          {
              "LineNum": 3,
              "Description": "Permit fee — structural modification",
              "Amount": 350.00,
              "DetailType": "SalesItemLineDetail",
              "SalesItemLineDetail": {
                  "ItemRef": { "value": "33", "name": "Permit Fees" },
                  "UnitPrice": 350.00,
                  "Qty": 1,
                  "TaxCodeRef": { "value": "NON" }
              }
          }
      ]
  }

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
  {
      "ChangeOrder": {
          "Id": "621",
          "SyncToken": "2",
          "MetaData": {
              "CreateTime": "2024-09-15T08:30:00-07:00",
              "LastUpdatedTime": "2024-09-16T11:00:00-07:00"
      },
      "DocNumber": "CO-001",
      "TxnDate": "2024-09-15",
      "TxnStatus": "Accepted",
      "AcceptedBy": "John Smith",
      "AcceptedDate": "2024-09-16",
      "ProjectRef": {
          "value": "39298034",
          "name": "Kitchen Renovation - Phase 2"
      },
      "CustomerRef": {
          "value": "58",
          "name": "Acme Construction Corp"
      },
      "LinkedTxn": [
          { "TxnId": "512", "TxnType": "Estimate" }
      ],
      "Line": [
          {
              "Id": "1",
              "LineNum": 1,
              "Amount": 2400.00,
              "DetailType": "SalesItemLineDetail",
              "SalesItemLineDetail": {
                  "ItemRef": { "value": "21", "name": "Structural Materials" },
                  "UnitPrice": 800.00,
                  "Qty": 3,
                  "TaxCodeRef": { "value": "TAX" }
              },
              "LinkedTxn": [{ "TxnId": "512", "TxnType": "Estimate" }]
          },
          {
              "Id": "2",
              "LineNum": 2,
              "Amount": 2000.00,
              "DetailType": "SalesItemLineDetail",
              "SalesItemLineDetail": {
                  "ItemRef": { "value": "7", "name": "Labor" },
                  "UnitPrice": 100.00,
                  "Qty": 20,
                  "TaxCodeRef": { "value": "NON" }
          },
          "LinkedTxn": [{ "TxnId": "512", "TxnType": "Estimate" }]
          },
          {
              "Id": "3",
              "LineNum": 3,
              "Amount": 350.00,
              "DetailType": "SalesItemLineDetail",
              "SalesItemLineDetail": {
                  "ItemRef": { "value": "33", "name": "Permit Fees" },
                  "UnitPrice": 350.00,
                  "Qty": 1,
                  "TaxCodeRef": { "value": "NON" }
              },
              "LinkedTxn": [{ "TxnId": "512", "TxnType": "Estimate" }]
          }
      ],
      "TotalAmt": 4966.00,
      "TxnTaxDetail": { "TotalTax": 216.00 }
      },
      "time": "2024-09-16T11:00:00.000-07:00"
  }
Delete a change order

Deletes a change order permanently. The project’s contracted total is reduced accordingly. Deleting a change order does not modify the parent Project Estimate. Only the project’s cumulative total is recalculated.

Step 1: Read a change order to get the Change Order ID.

Step 2: Delete the change order, passing the Change Order ID as the Id value and the current SyncToken.

Request

POST /v3/company/{realmId}/changeorder?operation=delete

Request body

1
2
3
4
  {
    "Id": "621",
    "SyncToken": "2"
  }

Response

1
2
3
4
5
6
7
8
9
  {
    "ChangeOrder": {
      "Id": "621",
      "SyncToken": "3",
      "status": "Deleted",
      "domain": "QBO"
    },
    "time": "2024-09-17T09:45:00.000-07:00"
  }