api/contracts-rev-mgmt/contracts.md

---
title: Contracts | Sage Intacct Developer
url: https://developer.intacct.com/api/contracts-rev-mgmt/contracts/
---

# Contracts | Sage Intacct Developer

* Get Contract Object Definition
* Query and List Contracts
* Query and List Contracts (Legacy)
* Get a Contract
* Get a Contract by ID
* Create Contract
* Update Contract
* Post Contract
* Renew Contract
* Clear All MEA Allocations
* Clear Individual MEA Allocations
* Delete Contract

---

Contract is a dimension that can be defined by the company and set on transactions to expand report functionality and insight.

---

## Get Contract Object Definition

#### `lookup`

> List all the fields and relationships for the contract object:

```xml
<lookup>
    <object>CONTRACT</object>
</lookup>
```

#### Parameters

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

---

## Query and List Contracts

#### `query`

> List the record number and description for each contract:

```xml
<query>
    <object>CONTRACT</object>
    <select>
        <field>RECORDNO</field>
        <field>CONTRACTID</field>
    </select>
</query>
```

> List the Evergreen template in use for each Evergreen contract:

```xml
<query>
    <object>CONTRACT</object>
    <filter>
        <equalto>
            <field>TERMTYPE</field>
            <value>Evergreen</value>
        </equalto>
    </filter>
    <select>
        <field>RECORDNO</field>
        <field>CONTRACTID</field>
        <field>EVERGREENMACRO</field>
    </select>
</query>
```

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| object | Required | string | Use `CONTRACT` |
| 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 Contracts (Legacy)

#### `readByQuery`

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

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| object | Required | string | Use `CONTRACT` |
| 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`) |

`query` Fields

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| STATE | Optional | string | Contract state.  * `I` - In progress * `R` - Renewed * `C` - Canceled * `N` - Not Renewed |
| BILLINGFREQUENCY | Optional | string | Billing frequency.  * `M` - Monthly * `Q` -- Quarterly * `A` - Annually |
| RENEWTERMPERIOD | Optional | string | Renewal term period.  * `Y` - Years * `M` - Months * `D` - Days |

---

## Get a Contract

#### `read`

```xml
<read>
    <object>CONTRACT</object>
    <keys>1</keys>
    <fields>*</fields>
</read>
```

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| object | Required | string | Use `CONTRACT` |
| keys | Required | string | Comma-separated list of contract `RECORDNO` 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 a Contract by ID

#### `readByName`

```xml
<readByName>
    <object>CONTRACT</object>
    <keys>C1000</keys>
    <fields>*</fields>
</readByName>
```

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| object | Required | string | Use `CONTRACT` |
| keys | Required | string | Comma-separated list of contract `CONTRACTID` 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 Contract

History

| Release | Changes |
| --- | --- |
| 2024 Release 4 | Added APPLICATION and ADDITIONALCONTACTNAME |
| 2022 Release 2 | Added TERMTYPE and EVERGREENMACRO |
| 2021 Release 1 | BILLINGFREQUENCY is now optional |
| 2020 Release 1 | Added STATE |
| 2019 Release 2 | Added CONTRACTTYPE, Added value of Annually for BILLINGFREQUENCY |
| 2018 Release 2 | Added RENEWALADVBILLBY and RENEWALADVBILLBYTYPE |
| 2018 Release 1 | Added ADVBILLBY and ADVBILLBYTYPE |

#### `create`

```xml
<create>
    <CONTRACT>
        <CONTRACTID>CTRC-003</CONTRACTID>
        <CUSTOMERID>C-103</CUSTOMERID>
        <NAME>North central contract</NAME>
        <BEGINDATE>04/01/2017</BEGINDATE>
        <ENDDATE>12/31/2017</ENDDATE>
        <BILLINGFREQUENCY>Monthly</BILLINGFREQUENCY>
        <TERMNAME>Net 30</TERMNAME>
        <LOCATIONID>US</LOCATIONID>
        <CURRENCY>USD</CURRENCY>
        <EXCHRATETYPE>Intacct Daily Rate</EXCHRATETYPE>
    </CONTRACT>
</create>
```

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| CONTRACT | Required | object | Object type to create |

`CONTRACT`

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| CONTRACTID | Optional | string | Unique ID for the contract. Required if company does not use document sequencing, or you can provide a value to use instead of the document sequence value. |
| CUSTOMERID | Required | string | Customer ID |
| NAME | Required | string | Contract name |
| STATE | Optional | string | State in which to create the contract.  * `In progress` (default) * `Draft` - The contract that will not yet post to the general ledger.  Use the post function to move a contract from `Draft` to `In progress`. |
| CONTRACTTYPE | Optional | string | Contract type |
| BILLTOCONTACTNAME | Optional | string | Bill to contact name. Leave blank to use customer’s default. |
| DESCRIPTION | Optional | string | Description |
| SHIPTOCONTACTNAME | Optional | string | Ship to contact name. Leave blank to use customer’s default. |
| BEGINDATE | Required | string | Start date in format `mm/dd/yyyy` |
| ENDDATE | Optional | string | End date in format `mm/dd/yyyy`. Required when the term type is Termed. |
| BILLINGFREQUENCY | Optional | string | Billing frequency.  * `Monthly` * `Quarterly` * `Annually` |
| TERMNAME | Required | string | Payment term |
| TERMTYPE | Required | string | Indicates the term type for the contract.  * `Termed` - a traditional payment term such as Net 30 (default) * `Evergreen` - perpetual contract |
| APPLICATION | Required | string | Indicates whether the contract is a full contract (`C`) or a dimension-only contract (`O`). The contract dimension is used to categorize Order Entry transactions without a subscription to the Contracts application. Default is full contract (`C`). |
| ADDITIONALCONTACTNAME | Optional | string | Name of an additional contact. |
| EVERGREENMACRO | Optional | string | Perpetual (Evergreen) template. Required for an `Evergreen` term type. |
| PRCLIST | Optional | string | Billing price list |
| MEAPRCLIST | Optional | string | Fair value price list |
| ADVBILLBY | Optional | integer | Bill in advance. Number of months or days before the start date. Overrides bill-in-advance settings on the customer. |
| ADVBILLBYTYPE | Optional | string | Bill-in-advance time period. Required if using bill in advance.  * `days` * `months` |
| RENEWALADVBILLBY | Optional | integer | Bill in advance for renewals. Number of months or days before the start date. |
| RENEWALADVBILLBYTYPE | Optional | string | Bill-in-advance time period for renewals. Required if using bill in advance for renewals.  * `days` * `months` |
| SUPDOCID | Optional | string | Attachments ID |
| LOCATIONID | Required | string | Location ID |
| DEPARTMENTID | Optional | string | Department ID |
| PROJECTID | Optional | string | Project ID |
| VENDORID | Optional | string | Vendor ID |
| EMPLOYEEID | Optional | string | Employee ID |
| CLASSID | Optional | string | Class ID |
| CURRENCY | Optional | string | Transaction currency. Required if company is configured for multi-currency. |
| EXCHRATETYPE | Optional | string | Exchange rate type. Required if company is configured for multi-currency (Leave blank to use `Intacct Daily Rate`) |
| RENEWAL | Optional | boolean | Renewal.  * `false` - No (default) * `true` - Yes  Applicable only for termed contracts. |
| RENEWALMACRO | Optional | string | Renewal template. Only used if `RENEWAL` is `true`. |
| RENEWTERMLENGTH | Optional | integer | Term length. Only used if `RENEWAL` is `true`. |
| RENEWTERMPERIOD | Optional | string | Period. Only used if `RENEWAL` is `true`.  * `Years` * `Months` (default) * `Days` |
| *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 `#~#`. |

---

## Update Contract

History

| Release | Changes |
| --- | --- |
| 2022 Release 2 | Added TERMTYPE and EVERGREENMACRO |
| 2019 Release 2 | Added CONTRACTTYPE, Added value of Annually for BILLINGFREQUENCY |
| 2018 Release 2 | Added RENEWALADVBILLBY and RENEWALADVBILLBYTYPE |
| 2018 Release 1 | Added ADVBILLBY and ADVBILLBYTYPE |

#### `update`

```xml
<update>
    <CONTRACT>
        <CONTRACTID>CTRC-003</CONTRACTID>
        <NAME>North central contract for services</NAME>
        <DEPARTMENTID>300</DEPARTMENTID>
    </CONTRACT>
</update>
```

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| CONTRACT | Create | object | Object type to update. |

`CONTRACT`

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| RECORDNO | Optional | integer | Record number of contract. Required if not using `CONTRACTID`. |
| CONTRACTID | Optional | string | Contract ID to update. Required if not using `RECORDNO`. |
| CUSTOMERID | Optional | string | Customer ID |
| NAME | Optional | string | Contract name |
| CONTRACTTYPE | Optional | string | Contract type |
| BILLTOCONTACTNAME | Optional | string | Bill to contact name. Leave blank to use customer’s default. |
| DESCRIPTION | Optional | string | Description |
| SHIPTOCONTACTNAME | Optional | string | Ship to contact name. Leave blank to use customer’s default. |
| BEGINDATE | Required | string | Start date in format `mm/dd/yyyy` |
| ENDDATE | Optional | string | End date in format `mm/dd/yyyy`. Required when the term type is Termed. |
| BILLINGFREQUENCY | Optional | string | Billing frequency.  * `Monthly` * `Quarterly` * `Annually` |
| TERMNAME | Required | string | Payment term |
| TERMTYPE | Optional | string | Indicates the term type for the contract.  * `Termed` - a traditional payment term such as Net 30 (default) * `Evergreen` - perpetual contract |
| APPLICATION | Required | string | Indicates whether the contract is a full contract (`C`) or a dimension-only contract (`O`). The contract dimension is used to categorize Order Entry transactions without a subscription to the Contracts application. Default is full contract (`C`). |
| ADDITIONALCONTACTNAME | Optional | string | Name of an additional contact. |
| EVERGREENMACRO | Optional | string | Perpetual (Evergreen) template. Required for an `Evergreen` term type. |
| PRCLIST | Optional | string | Billing price list |
| MEAPRCLIST | Optional | string | Fair value price list |
| ADVBILLBY | Optional | integer | Bill in advance. Number of months or days before the start date. Overrides bill-in-advance settings on the customer. |
| ADVBILLBYTYPE | Optional | string | Bill-in-advance time period. Required if using bill in advance.  * `days` * `months` |
| RENEWALADVBILLBY | Optional | integer | Bill in advance for renewals. Number of months or days before the start date. |
| RENEWALADVBILLBYTYPE | Optional | string | Bill-in-advance time period for renewals. Required if using bill in advance for renewals.  * `days` * `months` |
| SUPDOCID | Optional | string | Attachments ID |
| LOCATIONID | Required | string | Location ID |
| DEPARTMENTID | Optional | string | Department ID |
| PROJECTID | Optional | string | Project ID |
| VENDORID | Optional | string | Vendor ID |
| EMPLOYEEID | Optional | string | Employee ID |
| CLASSID | Optional | string | Class ID |
| CURRENCY | Optional | string | Transaction currency. Required if company is configured for multi-currency. |
| EXCHRATETYPE | Optional | string | Exchange rate type. Required if company is configured for multi-currency (Leave blank to use `Intacct Daily Rate`) |
| RENEWAL | Optional | boolean | Renewal.  * `false` - No (default) * `true` - Yes  Applicable only for termed contracts. |
| RENEWALMACRO | Optional | string | Renewal template. Only used if `RENEWAL` is `true`. |
| RENEWTERMLENGTH | Optional | integer | Term length. Only used if `RENEWAL` is `true`. |
| RENEWTERMPERIOD | Optional | string | Period. Only used if `RENEWAL` is `true`.  * `Years` * `Months` (default) * `Days` |
| *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 `#~#`. |

---

## Post Contract

You can post a contract that is in `Draft` state so that it is fully validated and posted to the GL. The state of a posted contract is changed from `Draft` to `In progress`.

If your draft contract is missing required parameter values, check the error messages from the `post` response and use the update function to correct any issues before trying to post again.

#### `post`

```xml
<post>
    <CONTRACT>
        <RECORDNO>127</RECORDNO>
        <GLPOSTINGDATE>01/01/2020</GLPOSTINGDATE>
        <POSTMEMO>Contract has been finalized</POSTMEMO>
    </CONTRACT>
</post>
```

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| object | Required | object | Use `CONTRACT` |

`CONTRACT`

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| RECORDNO | Required | string | Record number of the contract to post |
| GLPOSTDATE | Required | string | GL posting date in format `mm/dd/yyyy` |
| POSTMEMO | Optional | string | Memo about the post |

---

## Renew Contract

Forces the renewal of a contract that failed to renew at the scheduled time. This can be useful if you uploaded multiple contracts as part of an integration and want to avoid manually renewing them in the Sage Intacct UI. (A contract must have )

#### `renew`

```xml
<renew>
    <CONTRACT>
        <CONTRACTID>CTRC-003</CONTRACTID>
    </CONTRACT>
</renew>
```

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| CONTRACT | Required | object | Object type to renew. |

`CONTRACT`

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| CONTRACTID | Required | string | ID of the contract to renew. The contract’s state must be `In progress`, and there must be at least one contract line. |

---

## Clear All MEA Allocations

You can clear MEA allocations to reset the applicable revenue schedules to the amounts that existed prior to the allocations. Clearing MEA allocations unposts previously posted revenue, so the applicable reporting periods must be open.

#### `clearallmea`

```xml
<clearallmea>
    <CONTRACT>
        <CONTRACTID>CTRC-003</CONTRACTID>
    </CONTRACT>
</clearallmea>
```

#### Parameters

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

`CONTRACT`

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| CONTRACTID | Required | string | Contract ID for which to clear all MEA allocations. |

---

## Clear Individual MEA Allocations

You can clear individual MEA allocations one at a time, starting with the current one and working back in time.

#### `clearlastactivemea`

```xml
<clearlastactivemea>
    <CONTRACT>
        <CONTRACTID>CTRC-003</CONTRACTID>
    </CONTRACT>
</clearlastactivemea>
```

#### Parameters

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

`CONTRACT`

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| CONTRACTID | Required | string | Contract ID for which to clear the current MEA allocation. |

---

## Delete Contract

#### `delete`

```xml
<delete>
    <object>CONTRACT</object>
    <keys>112</keys>
</delete>
```

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| object | Required | string | Use `CONTRACT` |
| keys | Required | string | Comma-separated list of contract `RECORDNO` to delete. |

---

Provide feedback