ContractCost
IMPORTANT The SOAP API entered a limited enhancement phase in Q4 2020. Access to version 1.6 will eventually be deactivated. At this time, there is no end-of-lifecycle date.
This entity describes a cost associated with an Autotask Contract. A cost is a billing item for products or materials. Cost items can be billable or non-billable. Billable cost items appear in Approve and Post.
Entity details
You can also retrieve this information with the Web Services API call The getEntityInfo() SOAP API call.
| Entity Name: | ContractCost |
| Can Create: |
|
| Can Update: |
Only when Billed = false |
| Can Query: |
|
| Can Delete: |
Only when Billed = false |
| Can Have UDFs: |
Conditions and requirements
General
- Resources with security levels that specify limited or no contract visibility cannot create, update, or query this entity.
- create(), update(), delete(), and query() require Security Level permission to access the Contracts module.
- ContractCost must have either a ProductID or AllocationCodeID.
- ContractCost cannot be created, deleted, or queried if ContractID references a Block, Retainer, or Incident type Contract unless AllocationCodeID references a Block Purchase, Incident Purchase, or Retainer Purchase Material Cost Code; then, only the following fields can be updated: Name, Description, CostType, PurchaseOrderNumber, InternalPurchaseOrderNumber.
- If the Multi-currency Installed Module is enabled, the following fields will return the relevant Customer Currency values instead of the Internal Currency values: BillableAmount and UnitPrice.
- The following fields will return the saved Internal Currency values: InternalCurrencyBillableAmount and InternalCurrencyUnitPrice
Special field attributes
| Field | Conditions and Requirements |
|---|---|
|
AllocationCodeID |
AllocationCodeID must reference a Material Cost Code type allocation code. On create(), or update() when ProductID has changed and is not Null, if no value is supplied for the AllocationCodeID, UnitCost, or UnitPrice fields, then those fields take their values from the Product. On create() or update() when AllocationCodeID has changed and is not Null, if there is no Contract Cost Default set for the Material Cost Code associated with the AllocationCodeID, and if no value is supplied for the UnitCost and UnitPrice fields, then those fields take their values from the Material Cost Code. |
|
BillableAmount |
BillableAmount = UnitQuantity * UnitPrice. If UnitPrice is Null, the value will be set to the value from the Material Cost Code associated with AllocationCodeID. The API will round the UnitQuantity, UnitCost, and UnitPrice values to 4 decimal places prior to any calculations for the total price or extended cost. |
|
BillableToAccount |
If no value is specified for BillableToAccount, the value is set to True |
|
Billed |
When Billed = True (cost has been approved and posted), ContractCost is read only. update() and delete() are allowed only when Billed = False (cost has not been approved and posted). |
|
ContractID |
After a ContractCost is created, ContractID cannot be updated. If ContractID references a Contract that has set a Contract Cost Default for the Material Cost Code associated with the AllocationCodeID, and no value was supplied for UnitPrice, UnitCost, or BillableToAccount, then these fields take their values from the Contract Cost Default. |
|
ExtendedCost |
ExtendedCost = UnitQuantity * UnitCost. If UnitCost is Null, the value will be set to the value from the Material Cost Code associated with AllocationCodeID. This entity field will return no information if the user account making the query does not have sufficient privileges to view cost data in the Autotask UI. Additionally, if an update request does not have the necessary permissions, the API will ignore the call's values for the field even if they are blank or would be otherwise required. The API will round the UnitQuantity, UnitCost, and UnitPrice values to 4 decimal places prior to any calculations for the total price or extended cost. |
|
Status |
Status is read only. On create(), when Procurement is enabled, Status is set as follows: If ProductID is null, then Status = Ready to Ship. If ProductID references a Product where DoesNotRequireProcurement = True, then Status = Ready to Ship. If ProductID references a Product where DoesNotRequireProcurement = False and the Product is not available in Inventory, then Status = Need To Order. If ProductID references a Product where DoesNotRequireProcurement = False and the Product is available in Inventory, then Status = Ready to Ship. If Status = Need To Order and ExtendedCost is > the value set in the system setting "Require approval before ordering..." then Status is automatically set to Waiting Approval. When Procurement is disabled, Status = Pending |
|
UnitCost |
This entity field will return no information if the user account making the query does not have sufficient privileges to view cost data in the Autotask UI. Additionally, if an update request does not have the necessary permissions, the API will ignore the call's values for the field even if they are blank or would be otherwise required. |
Field definitions
About this table
The following table describes the standard Autotask field objects for this entity.
- To retrieve more detailed information specific to a particular Autotask implementation, use the Web Services API call The getFieldInfo() SOAP API call.
- For information on entity UDFs, use getUDFInfo().
- For String datatypes, the number in parentheses ( ) indicates the maximum number of characters allowed.
- LT indicates Local Term.
For more information about fields marked as picklists, review our Understanding picklists article.
| Field Name | Label | Datatype | Read Only | Is Required | Reference Name | Picklist |
|---|---|---|---|---|---|---|
| AllocationCodeID | Allocation Code | long | AllocationCode | |||
| BillableAmount | Billable Amount | double |
|
|||
| BillableToAccount | Billable To Account | Boolean | ||||
| Billed | Billed | Boolean |
|
|||
| ContractID | Contract | long |
|
Contract | ||
| ContractServiceBundleID | Contract Service Bundle ID | long | ContractServiceBundle | |||
| ContractServiceID | Contract Service ID | long | ContractService | |||
| CostType | Cost Type | integer |
|
|
||
| CreateDate | Create Date | datetime |
|
|||
| CreatorResourceID | Created By | long |
|
Resource | ||
| DatePurchased | Date Purchased | datetime |
|
|||
| Description | Product Description | string (2000) | ||||
| ExtendedCost | Extended Cost | double |
|
|||
| id | id | long |
|
|
||
| InternalCurrencyBillableAmount (Multi-currency module only) | Internal Currency Billable Amount | double |
|
|||
| InternalCurrencyUnitPrice (Multi-currency module only) | Internal Currency Unit Price | double |
|
|||
| InternalPurchaseOrderNumber | Internal Purchase Order Number | string (50) | ||||
| Name | Name | string (100) |
|
|||
| Notes | Notes | string (2000) | ||||
| ProductID | Product | long | Product | |||
| PurchaseOrderNumber | Purchase Order Number | string (50) | ||||
| Status | Status | long |
|
|
||
| StatusLastModifiedBy | Last Modified By | long |
|
|||
| StatusLastModifiedDate | Last Modified Date | datetime |
|
|||
| UnitCost | Unit Cost | double | ||||
| UnitPrice | Unit Price | double | ||||
| UnitQuantity | Unit Quantity | double |
|
