api/construction/project-change-orders.md

---
title: Project Change Orders | Sage Intacct Developer
url: https://developer.intacct.com/api/construction/project-change-orders/
---

# Project Change Orders | Sage Intacct Developer

* Get Project Change Order Object Definition
* Query and List Project Change Orders
* Query and List Project Change Orders (Legacy)
* Get Project Change Order
* Get Project Change Order by ID
* Create Project Change Order
* Update Project Change Order
* Delete Project Change Order

---

You can use project change orders to group change requests in order to present them to the customer for approval, and ultimately, for billing.
Your project change order can be associated with a change request status, which is a user-defined object that is shared by change orders and change requests.

After creating a project change order, you can create links from one or more change requests to that change order. To do this, provide the project change order ID when creating or updating change requests.

When you get a project change order, the sum of the total cost for all the linked change requests is provided in the response. This is also true for the total price.

---

## Get Project Change Order Object Definition

#### `lookup`

> List all the fields and relationships for the project change order object:

```xml
<lookup>
    <object>PROJECTCHANGEORDER</object>
</lookup>
```

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| object | Required | string | Use `PROJECTCHANGEORDER` |

---

## Query and List Project Change Orders

#### `query`

> List information for project change orders where the total cost is greater than 1000:

```xml
<query>
    <object>PROJECTCHANGEORDER</object>
    <select>
        <field>PROJECTCHANGEORDERID</field>
        <field>TOTALCOST</field>
        <field>CUSTOMERID</field>
    </select>
    <filter>
        <greaterthan>
            <field>TOTALCOST</field>
            <value>1000</value>
        </greaterthan>
    </filter>
</query>
```

> List information for **change requests** linked to the project change order with the given ID:

```xml
<query>
    <object>CHANGEREQUEST</object>
    <select>
        <field>CHANGEREQUESTID</field>
        <field>PROJECTCHANGEORDERID</field>
        <field>PJCHANGEORDER.TOTALPRICE</field>
        <field>TOTALPRICE</field>
    </select>
    <filter>
        <equalto>
            <field>PROJECTCHANGEORDERID</field>
            <value>PCO-66</value>
        </equalto>
    </filter>
</query>
```

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| object | Required | string | Use `PROJECTCHANGEORDER` |
| filter | Optional | object | Filter expression to limit the response to only objects that match the expression. Check the value of a single field using operators such as equalto/like, or multiple fields using and/or. Query fields on related objects using the dot operator (for example, `VENDOR.CREDITLIMIT` on APBILL). |
| select | Required | sequence | The names of the fields that you want included in the response, and an optional aggregate function such as `count` or `sum`. Returning all fields is not supported. |
| orderby | Optional | object | Provide an `order` element with a field name and choose an ascending or descending sort order, for example:  `<order>   <field>RECORDNO</field>    <descending/>  </order>` |
| options | Optional | object | Query options:  * Set the `caseinsensitive` element to `true` for a case-insensitive query  `<caseinsensitive>true</caseinsensitive>` * In a multi-entity company, set the `showprivate` element to `true` to query data in private entities:   `<showprivate>true</showprivate>` * Specify the `returnformat` for the response: `xml` (default), `json`, or `csv`  `<returnformat>json</returnformat>` |
| pagesize | Optional | integer | Maximum number of matching objects to return in the response, between `1` and `2000` items (Default: `100`) |
| offset | Optional | integer | Point at which to start indexing into records (Default: `0`) |

---

## Query and List Project Change Orders (Legacy)

#### `readByQuery`

```xml
<readByQuery>
    <object>PROJECTCHANGEORDER</object>
    <fields>*</fields>
    <query/>
    <pagesize>100</pagesize>
</readByQuery>
```

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| object | Required | string | Use `PROJECTCHANGEORDER` |
| fields | Optional | string | Comma-separated list of fields on the object to list. For best performance and predictability, limit the number of fields. To return all fields, omit the element or provide `*` for the value. |
| query | Required | string | SQL-like query based on fields on the object. The following operators are supported: `<`, `>`, `>=`, `<=`, `=`, `like`, `not like`, `in`, `not in`, `IS NOT NULL`, `IS NULL`, `AND`, `OR`. Illegal XML characters must be properly encoded, and single quotes must be escaped with backslashes (`'Jane\'s Deli'`). Joins are not supported. |
| pagesize | Optional | integer | Custom page size between `1` and `1000` items (Default: `100`) |

---

## Get Project Change Order

#### `read`

```xml
<read>
    <object>PROJECTCHANGEORDER</object>
    <keys>66</keys>
    <fields>*</fields>
</read>
```

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| object | Required | string | Use `PROJECTCHANGEORDER` |
| keys | Required | string | Comma-separated list of `RECORDNO` of the project change order to get |
| fields | Optional | string | Comma-separated list of fields on the object to get. To return all fields, omit the element or provide `*` for the value. For best performance and predictability, limit the number of fields. |
| returnFormat | Optional | string | Data format for the response body:  * `xml` (default) * `json` * `csv` |

---

## Get Project Change Order by ID

#### `readByName`

```xml
<readByName>
    <object>PROJECTCHANGEORDER</object>
    <keys>PCO-66</keys>
    <fields>*</fields>
</readByName>
```

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| object | Required | string | Use `PROJECTCHANGEORDER` |
| keys | Required | string | Comma-separated list of ID of the project change order to get |
| fields | Optional | string | Comma-separated list of fields on the object to get. To return all fields, omit the element or provide `*` for the value. For best performance and predictability, limit the number of fields. |
| returnFormat | Optional | string | Data format for the response body:  * `xml` (default) * `json` * `csv` |

---

## Create Project Change Order

History

| Release | Changes |
| --- | --- |
| 2024 Release 3 | Changed ITEMID to optional |
| 2022 Release 2 | Added PROJECTCONTRACTID and PROJECTCONTRACTLINEID |
| 2023 Release 1 | Removed the restriction that only draft project change orders are allowed |

#### `create`

> Creates a project change order:

```xml
<create>
    <PROJECTCHANGEORDER>
        <PROJECTCHANGEORDERID>PCO-66</PROJECTCHANGEORDERID>
        <PROJECTID>3</PROJECTID>
        <ITEMID>Design</ITEMID>
        <PROJECTCHANGEORDERDATE>6/30/2024</PROJECTCHANGEORDERDATE>
        <CHANGEREQUESTSTATUSNAME>Approved Changes</CHANGEREQUESTSTATUSNAME>
    </PROJECTCHANGEORDER>
</create>
```

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| PROJECTCHANGEORDER | Required | object | Object type to create. |

`PROJECTCHANGEORDER`

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| PROJECTCHANGEORDERID | Required | string | Unique identifier for the project change order. (This parameter is optional if auto numbering is configured in your company, but you can still overwrite it.) |
| PROJECTID | Required | string | ID of an existing project |
| ITEMID | Optional | string | Billing item ID. Must be active and non-inventory. |
| PROJECTCHANGEORDERDATE | Required | string | Date for the project change order in the `mm/dd/yyyy` format |
| DESCRIPTION | Optional | string | Description for the project change order. |
| PROJECTCHANGEORDERSTATE | Optional | string | State of the project change order.  * `Draft` (default) * `Posted`  Does not affect the state of linked change requests. |
| CHANGEREQUESTSTATUSNAME | Optional | string | Name of a change request status to be inherited by linked change requests. |
| PROJECTCONTRACTID | Optional | string | `PROJECTCONTRACTID` of the project contract affected by this change order. Required if PROJECTCONTRACTLINEID is provided. |
| PROJECTCONTRACTLINEID | Optional | string | `PROJECTCONTRACTLINEID` of the specific project contract line that is affected by this change order. Required if PROJECTCONTRACTID is provided. |
| PRICEEFFECTIVEDATE | Optional | date | Price effective date of the project change order. Setting a value or null for this field will automatically set the PRICEEFFECTIVEDATE field on all linked change requests. |
| SCOPE | Optional | string | Details about the expected scope of work for the change request. Use 4000 or fewer characters. |
| INCLUSIONS | Optional | string | Details related to items that are explicitly included in the terms of this change request. Use 4000 or fewer characters. |
| EXCLUSIONS | Optional | string | Details related to items that are explicitly excluded in the terms of this change request. Use 4000 or fewer characters. |
| TERMS | Optional | string | Additional terms or performance obligations. Use 4000 or fewer characters. |
| SCHEDULEDSTARTDATE | Optional | date | Scheduled start date in the `mm/dd/yyyy` format |
| ACTUALSTARTDATE | Optional | date | Actual start date in the `mm/dd/yyyy` format |
| SCHEDULEDCOMPLETIONDATE | Optional | date | Original scheduled date for completion of the work in the `mm/dd/yyyy` format |
| REVISEDCOMPLETIONDATE | Optional | date | Revised completion date for the work (caused by changes) in the `mm/dd/yyyy` format. |
| SUBSTANTIALCOMPLETIONDATE | Optional | date | Date the work is considered substantially complete in the `mm/dd/yyyy` format. Typically used as a milestone to identify when payment obligations are due. |
| ACTUALCOMPLETIONDATE | Optional | date | Date the work is actually complete in the `mm/dd/yyyy` format |
| NOTICETOPROCEED | Optional | date | Date when a formal notice to proceed was given in the `mm/dd/yyyy` format |
| RESPONSEDUE | Optional | date | Date when a response is expected from an external party in the `mm/dd/yyyy` format |
| EXECUTEDON | Optional | date | Date the related contract document was formally executed in the `mm/dd/yyyy` format |
| SCHEDULEIMPACT | Optional | string | Details about any impacts on the current schedule. Use 100 or fewer characters. |
| INTERNALREFNO | Optional | string | Specifies an internal reference ID |
| INTERNALINITIATEDBYKEY | Optional | integer | Record number of the employee who initiated the change request |
| INTERNALINITIATEDBY | Optional | string | ID of the employee who initiated the change request |
| INTERNALINITIATEDBYNAME | Optional | string | Name of the employee who initiated the change request |
| INTERNALVERBALBYKEY | Optional | integer | Record number of of the employee who verbally agreed to the change request |
| INTERNALVERBALBY | Optional | string | ID of the employee who verbally agreed to the change request |
| INTERNALVERBALBYNAME | Optional | string | Name of the employee who verbally agreed to the change request |
| INTERNALISSUEDBYKEY | Optional | integer | Record number of the employee who issued the change request |
| INTERNALISSUEDBY | Optional | string | ID of the employee who issued the change request |
| INTERNALISSUEDBYNAME | Optional | string | Name of the employee who issued the change request |
| INTERNALISSUEDON | Optional | date | Date this change request was internally issued in the `mm/dd/yyyy` format |
| INTERNALAPPROVEDBYKEY | Optional | integer | Record number of the employee who internally approved the change request. |
| INTERNALAPPROVEDBY | Optional | string | ID of the employee who internally approved the change request |
| INTERNALAPPROVEDBYNAME | Optional | string | Name of the employee who internally approved the change request |
| INTERNALAPPROVEDON | Optional | date | Date this change request was internally approved in the `mm/dd/yyyy` format |
| INTERNALSIGNEDBYKEY | Optional | integer | Record number of the employee who signed for the change request |
| INTERNALSIGNEDBY | Optional | string | ID of the employee who signed for the change request |
| INTERNALSIGNEDBYNAME | Optional | string | Name of the employee who signed for the change request |
| INTERNALSIGNEDON | Optional | date | Date the change request was internally signed in the `mm/dd/yyyy` format. |
| INTERNALSOURCE | Optional | string | Internal source when the change request originated from another document or workflow. Can be an internal or external source. For example, a request for information (RFI) or a project change request. |
| INTERNALSOURCEREFNO | Optional | string | Internal source reference number or ID when the change request originated from another source. Can be an internal or external number. |
| EXTERNALREFNO | Optional | string | External reference number, such as one required by a vendor or customer, for this change request. |
| EXTERNALVERBALBYKEY | Optional | integer | Record number of the contact who verbally agreed to the change request. For example, a customer or vendor contact. |
| EXTERNALVERBALBY | Optional | string | Name of the contact who verbally agreed to the change request. For example, a customer or vendor contact. |
| EXTERNALAPPROVEDBYKEY | Optional | integer | Record number of the contact who approved the change request. For example, a customer or vendor contact. |
| EXTERNALAPPROVEDBY | Optional | string | Name of the contact who approved the change request. For example, a customer or vendor contact. |
| EXTERNALAPPROVEDON | Optional | date | Date the customer or vendor approved the change request in the `mm/dd/yyyy` format |
| EXTERNALSIGNEDBYKEY | Optional | integer | Record number of the contact who signed the change request. For example, a customer or vendor contact. |
| EXTERNALSIGNEDBY | Optional | string | Name of the contact who signed the change request. For example, a customer or vendor contact. |
| EXTERNALSIGNEDON | Optional | date | Date the customer or vendor signed for the change request the `mm/dd/yyyy` format |
| SUPDOCID | Optional | string | Attachments ID |
| *Custom field name* | varies | varies | Custom field names and values as defined for this object. For a multi-pick-list custom field, implode multiple field values with `#~#`. |

`customfield`

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| customfieldname | Optional | string | Custom field ID |
| customfieldvalue | Optional | varies | Custom field value. For a multi-pick-list custom field, implode multiple field values with `#~#`. |

---

## Update Project Change Order

History

| Release | Changes |
| --- | --- |
| 2022 Release 2 | Added PROJECTCONTRACTID and PROJECTCONTRACTLINEID |
| 2023 Release 1 | Removed the restriction that only draft project change orders are allowed |

#### `update`

> Sets the change request status of a project change order to `Approved Changes`:

```xml
<update>
    <PROJECTCHANGEORDER>
        <PROJECTCHANGEORDERID>PCO-66</PROJECTCHANGEORDERID>
        <CHANGEREQUESTSTATUSNAME>Approved Changes</CHANGEREQUESTSTATUSNAME>
    </PROJECTCHANGEORDER>
</update>
```

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| PROJECTCHANGEORDER | Required | object | Object to update |

`PROJECTCHANGEORDER`

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| RECORDNO | Optional | integer | `RECORDNO` of the project change order to update. Required if not using `PROJECTCHANGEORDERID`. |
| PROJECTCHANGEORDERID | Optional | string | Unique identifier for the project change order to update. Required if not using `RECORDNO`. |
| PROJECTID | Optional | string | ID of an existing project |
| ITEMID | Optional | string | Billing item ID. Must be active and non-inventory. |
| PROJECTCHANGEORDERDATE | Optional | string | Date for the project change order in the `mm/dd/yyyy` format |
| DESCRIPTION | Optional | string | Description for the project change order. |
| PROJECTCHANGEORDERSTATE | Optional | string | State of the project change order, either `Draft` or `Posted`. Does not affect the state of linked change requests. You cannot change the state from `Posted` to `Draft`. (Default: `Draft`) |
| CHANGEREQUESTSTATUSNAME | Optional | string | Name of a change request status to be inherited by linked change requests. |
| PROJECTCONTRACTID | Optional | string | `PROJECTCONTRACTID` of the project contract affected by this change order. Required if PROJECTCONTRACTLINEID is provided. |
| PROJECTCONTRACTLINEID | Optional | string | `PROJECTCONTRACTLINEID` of the specific project contract line that is affected by this change order. Required if PROJECTCONTRACTID is provided. |
| PRICEEFFECTIVEDATE | Optional | date | Price effective date of the project change order. Updating this field will automatically update the PRICEEFFECTIVEDATE field on all linked change requests. |
| SCOPE | Optional | string | Details about the expected scope of work for the change request. Use 4000 or fewer characters. |
| INCLUSIONS | Optional | string | Details related to items that are explicitly included in the terms of this change request. Use 4000 or fewer characters. |
| EXCLUSIONS | Optional | string | Details related to items that are explicitly excluded in the terms of this change request. Use 4000 or fewer characters. |
| TERMS | Optional | string | Additional terms or performance obligations. Use 4000 or fewer characters. |
| SCHEDULEDSTARTDATE | Optional | date | Scheduled start date in the `mm/dd/yyyy` format |
| ACTUALSTARTDATE | Optional | date | Actual start date in the `mm/dd/yyyy` format |
| SCHEDULEDCOMPLETIONDATE | Optional | date | Original scheduled date for completion of the work in the `mm/dd/yyyy` format |
| REVISEDCOMPLETIONDATE | Optional | date | Revised completion date for the work (caused by changes) in the `mm/dd/yyyy` format. |
| SUBSTANTIALCOMPLETIONDATE | Optional | date | Date the work is considered substantially complete in the `mm/dd/yyyy` format. Typically used as a milestone to identify when payment obligations are due. |
| ACTUALCOMPLETIONDATE | Optional | date | Date the work is actually complete in the `mm/dd/yyyy` format |
| NOTICETOPROCEED | Optional | date | Date when a formal notice to proceed was given in the `mm/dd/yyyy` format |
| RESPONSEDUE | Optional | date | Date when a response is expected from an external party in the `mm/dd/yyyy` format |
| EXECUTEDON | Optional | date | Date the related contract document was formally executed in the `mm/dd/yyyy` format |
| SCHEDULEIMPACT | Optional | string | Details about any impacts on the current schedule. Use 100 or fewer characters. |
| INTERNALREFNO | Optional | string | Specifies an internal reference ID |
| INTERNALINITIATEDBYKEY | Optional | integer | Record number of the employee who initiated the change request |
| INTERNALINITIATEDBY | Optional | string | ID of the employee who initiated the change request |
| INTERNALINITIATEDBYNAME | Optional | string | Name of the employee who initiated the change request |
| INTERNALVERBALBYKEY | Optional | integer | Record number of of the employee who verbally agreed to the change request |
| INTERNALVERBALBY | Optional | string | ID of the employee who verbally agreed to the change request |
| INTERNALVERBALBYNAME | Optional | string | Name of the employee who verbally agreed to the change request |
| INTERNALISSUEDBYKEY | Optional | integer | Record number of the employee who issued the change request |
| INTERNALISSUEDBY | Optional | string | ID of the employee who issued the change request |
| INTERNALISSUEDBYNAME | Optional | string | Name of the employee who issued the change request |
| INTERNALISSUEDON | Optional | date | Date this change request was internally issued in the `mm/dd/yyyy` format |
| INTERNALAPPROVEDBYKEY | Optional | integer | Record number of the employee who internally approved the change request. |
| INTERNALAPPROVEDBY | Optional | string | ID of the employee who internally approved the change request |
| INTERNALAPPROVEDBYNAME | Optional | string | Name of the employee who internally approved the change request |
| INTERNALAPPROVEDON | Optional | date | Date this change request was internally approved in the `mm/dd/yyyy` format |
| INTERNALSIGNEDBYKEY | Optional | integer | Record number of the employee who signed for the change request |
| INTERNALSIGNEDBY | Optional | string | ID of the employee who signed for the change request |
| INTERNALSIGNEDBYNAME | Optional | string | Name of the employee who signed for the change request |
| INTERNALSIGNEDON | Optional | date | Date the change request was internally signed in the `mm/dd/yyyy` format. |
| INTERNALSOURCE | Optional | string | Internal source when the change request originated from another document or workflow. Can be an internal or external source. For example, a request for information (RFI) or a project change request. |
| INTERNALSOURCEREFNO | Optional | string | Internal source reference number or ID when the change request originated from another source. Can be an internal or external number. |
| EXTERNALREFNO | Optional | string | External reference number, such as one required by a vendor or customer, for this change request. |
| EXTERNALVERBALBYKEY | Optional | integer | Record number of the contact who verbally agreed to the change request. For example, a customer or vendor contact. |
| EXTERNALVERBALBY | Optional | string | Name of the contact who verbally agreed to the change request. For example, a customer or vendor contact. |
| EXTERNALAPPROVEDBYKEY | Optional | integer | Record number of the contact who approved the change request. For example, a customer or vendor contact. |
| EXTERNALAPPROVEDBY | Optional | string | Name of the contact who approved the change request. For example, a customer or vendor contact. |
| EXTERNALAPPROVEDON | Optional | date | Date the customer or vendor approved the change request in the `mm/dd/yyyy` format |
| EXTERNALSIGNEDBYKEY | Optional | integer | Record number of the contact who signed the change request. For example, a customer or vendor contact. |
| EXTERNALSIGNEDBY | Optional | string | Name of the contact who signed the change request. For example, a customer or vendor contact. |
| EXTERNALSIGNEDON | Optional | date | Date the customer or vendor signed for the change request the `mm/dd/yyyy` format |
| SUPDOCID | Optional | string | Attachments ID |
| *Custom field name* | varies | varies | Custom field names and values as defined for this object. For a multi-pick-list custom field, implode multiple field values with `#~#`. |

`customfield`

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| customfieldname | Optional | string | Custom field ID |
| customfieldvalue | Optional | varies | Custom field value. For a multi-pick-list custom field, implode multiple field values with `#~#`. |

---

## Delete Project Change Order

#### `delete`

```xml
<delete>
    <object>PROJECTCHANGEORDER</object>
    <keys>66</keys>
</delete>
```

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| object | Required | string | Use `PROJECTCHANGEORDER` |
| keys | Required | integer | `RECORDNO` of the project change order to delete |

---

Provide feedback