Contract lines

A contract line is a header containing multiple schedule lines and is tied directly to a contract.

List contract lines

get/objects/contracts/contract-line

Returns up to 100 object references from the collection with a key, ID, and link for each contract line. This operation is mostly for use in testing; use the query service to find objects that meet certain criteria and to specify properties that are returned.

SecurityOAuth2
Responses
200

OK

400

Bad Request

Request samples 
Response samples 
application/json
{
  • "ia::result": [
    • {
      • "key": "1",
      • "id": "1",
      • "href": "/objects/contracts/contract-line/1"
      },
    • {
      • "key": "2",
      • "id": "2",
      • "href": "/objects/contracts/contract-line/2"
      },
    • {
      • "key": "3",
      • "id": "3",
      • "href": "/objects/contracts/contract-line/3"
      }
    ],
  • "ia::meta": {
    • "totalCount": 3,
    • "start": 1,
    • "pageSize": 100,
    • "next": null,
    • "previous": null
    }
}
Create a contract line
post/objects/contracts/contract-line
Creates a new contract line.


SecurityOAuth2 
Request 
Request Body schema: application/json
required
Contract line to create


required
object
contract


 
key
string
Contract unique key


 
 Example:  "249"
id
string
Contract unique identifier


 
 Example:  "CON-0045"
required
object
 
key
string
Item Key


 
 Example:  "13"
id
string
Item ID


 
 Example:  "API3.0"
required
object
 
amountFrequency
string or null
Flat/fixed amount frequency


 Enum: "includeWithEveryInvoice" null "oneTime" "useBillingTemplate"  
 Example:  "oneTime"
object
Billing template to use.


 
key
string
Key


 
 Example:  "12"
id
string
Contract Billing Template ID


 
 Example:  "12P_BeginingPeriod"
method
string or null
 Default:  "fixedPrice"
Billing method


 Enum: "fixedPrice" null "projectMaterials" "projectT&M" "projectTime" "quantityBased"  
 Example:  "fixedPrice"
usageQuantityReset
string or null
 Default:  null
Reset usage quantity


 Enum: "afterEachInvoice" "afterEachRenewal" null  
 Example:  "afterEachRenewal"
isUsageQuantityRecurring
boolean
 Default:  false
Usage quantity recurs


 
 Example:  false
committedQuantityEndAction
string or null
 Default:  null
On contract line end date


 Enum: "billUnusedQuantity" "cancelUnusedQuantity" "doNothing" null  
 Example:  "billUnusedQuantity"
committedQuantityExcess
string or null
 Default:  null
If usage exceeds the committed quantity


 Enum: "billOverage" "doNotAllowOverage" "doNothing" null  
 Example:  "billOverage"
quantityType
string or null
 Default:  null
Quantity type


 Enum: "committed" null "variable"  
 Example:  "variable"
durationInPeriods
string
Duration (in periods)


 
 Example:  "3"
proratePartialPeriods
boolean
 Default:  false
Prorate partial periods?


 
 Example:  false
frequency
string or null
 Default:  null
Billing frequency


 Enum: "annually" "monthly" null "quarterly"  
 Example:  "monthly"
startDate
string <date> 
Billing start


 
 Example:  "2022-01-01"
endDate
string <date> 
Billing end


 
 Example:  "2022-04-30"
memo
string or null
Memo


 
 Example:  "Cash customer"
quantity
string or null
Quantity


 
 Example:  "8"
rate
string or null
Rate


 
 Example:  "100"
multiplier
string or null
Multiplier


 
 Example:  "1"
discount
string
 Default:  "0"
Discount


 
 Example:  "10"
flatFixedAmount
string
Flat/fixed amount


 
 Example:  "100"
baseFlatFixedAmount
string
Base flat/fixed amount


 
 Example:  "100"
required
object
 
object
Location or entity associated with the contract. This field is required in a multi-entity environment. Contract lines are restricted to the specified location or entity or to a child of the location or entity.


 
key
string
Location Key


 
 Example:  "22"
id
string
Location


 
 Example:  "LOC-22"
object
Department associated with the contract.


 
key
string or null
Department Key


 
 Example:  "11"
id
string or null
Department


 
 Example:  "DEP-11"
object
 
key
string or null
Class Key


 
 Example:  "731"
id
string or null
Class ID


 
 Example:  "REST_CLS_001"
object
 
id
string or null
Task ID


 
 Example:  "1"
key
string or null
Task Key


 
 Example:  "1"
object
 
key
string or null
Vendor Key


 
 Example:  "357"
id
string or null
Vendor ID


 
 Example:  "1605212096809"
object
Customer that the contract is associated with. The customer cannot be changed after a contract line has been posted to the contract.


 
key
string
Customer Key


 
 Example:  "250"
id
string
Customer ID


 
 Example:  "CUS-RT-0011"
object
 
key
string or null
Project Key


 
 Example:  "2"
id
string or null
Project ID


 
 Example:  "NET-XML30-2"
object
 
key
string or null
Employee Key


 
 Example:  "10"
id
string or null
Employee ID


 
 Example:  "EMP-10"
state
string
 Default:  "inProgress"
State


 Enum: "canceled" "closed" "completed" "draft" "inProgress" "notRenewed" "renewalForecast" "renewalOnly" "revalued"  
 Example:  "completed"
startDate
string <date> 
Line start


 
 Example:  "2024-01-01"
endDate
string <date> 
Line end


 
 Example:  "2024-04-30"
changeType
string or null
 Default:  null
Change type


 Enum: "addOnMRR" "churnMRR" "downgrade" "newMRR" null "renewalDowngrade" "renewalUpgrade"  
 Example:  "newMRR"
itemDescription
string
Item description


 
 Example:  "API usage"
deliveryStatus
string
 Default:  "delivered"
Delivery status


 Enum: "delivered" "undelivered"  
 Example:  "undelivered"
postingDate
string <date> 
GL posting date


 
 Example:  "2024-01-01"
memo
string or null
Post Memo


 
 Example:  "POSTING LINE"
shipToSource
string
 Default:  "contractValue"
Specifies where the ship-to contact information should come from


 Enum: "contractValue" "userSpecifiedValue"  
 Example:  "contractValue"
billToSource
string
 Default:  "contractValue"
Specifies where the bill-to contact information should come from


 Enum: "contractValue" "userSpecifiedValue"  
 Example:  "contractValue"
revenueDeferralStatus
string
 Default:  "deferRevenueUntilItemIsDelivered"
Revenue recognition deferral status


 Enum: "deferRevenueUntilAllItemsAreDelivered" "deferRevenueUntilItemIsDelivered"  
 Example:  "deferRevenueUntilItemIsDelivered"
isRecurring
boolean
 Default:  false
Recurring


 
 Example:  false
object
 
exchangeRateDate
string <date> 
Exchange rate date


 
 Example:  "2024-01-01"
exchangeRate
string <decimal-precision-12> 
Exchange rate


 
 Example:  "1.345"
object
 
memo
string or null
Memo


 
 Example:  "Cash customer"
object
 
object
 
object
 
startDate
string <date> 
Revenue 1 start date


 
 Example:  "2022-04-01"
endDate
string <date> 
Revenue 1 end date


 
 Example:  "2022-04-30"
object
 
object
 
startDate
string <date> 
Revenue 1 start date


 
 Example:  "2018-04-01"
endDate
string <date> 
Revenue 1 end date


 
 Example:  "2022-04-30"
totalQuantity
string
Total revenue quantity


 
 Example:  "30"
memo
string or null
Memo


 
 Example:  "Cash customer"
object
 
renew
boolean
 Default:  false
Renew


 
 Example:  false
object
 
key
string
Key


 
 Example:  "17"
id
string
Contract revenue template ID


 
 Example:  "12P_BeginingPeriod"
Responses 
201
Created


400
Bad Request


Request samples 
application/json
{
  • "contract": {
    • "key": "1"
    },
  • "item": {
    • "key": "2"
    },
  • "dimensions": {
    • "location": {
      • "key": "1"
      }
    },
  • "startDate": "2022-01-01",
  • "endDate": "2022-12-31",
  • "billing": {
    • "quantity": "12",
    • "rate": "12",
    • "multiplier": "1",
    • "discount": "0",
    • "method": "fixedPrice",
    • "amountFrequency": "includeWithEveryInvoice",
    • "frequency": "monthly",
    • "flatFixedAmount": "144",
    • "baseFlatFixedAmount": "144",
    • "totalFlatFixedAmount": "1728",
    • "totalBaseFlatFixedAmount": "1728"
    },
  • "changeType": "newMRR",
  • "lineType": "sale",
  • "revenue": {
    • "journal1": {
      • "revenueTemplate": {
        }
      }
    },
  • "postingDate": "2022-01-01"
}
Response samples 
application/json
{
  • "ia::result": {
    • "id": "26",
    • "key": "26",
    • "href": "/objects/contracts/contract-line/26"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Get a contract line
get/objects/contracts/contract-line/{key}
Returns detailed information for a specified contract line.


SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned key for the contract line.


 
 Example:  99
Responses 
200
OK


400
Bad Request


Request samples 
Response samples 
application/json
{
  • "ia::result": {
    • "id": "3",
    • "key": "3",
    • "contract": {
      • "key": "1",
      • "id": "CON-001",
      • "state": "inProgress",
      • "name": "10-17 MEA bundle",
      • "href": "/objects/contracts/contract/1"
      },
    • "parent": {
      • "id": null,
      • "key": null,
      • "lineNumber": null
      },
    • "state": "inProgress",
    • "lineNumber": 3,
    • "recurringBillingPeriod": null,
    • "startDate": "2017-01-01",
    • "endDate": "2017-12-31",
    • "cancelationDate": null,
    • "item": {
      • "key": "2552",
      • "id": "16",
      • "name": "Service - Gold",
      • "href": "/objects/inventory-control/item/2552"
      },
    • "itemDescription": null,
    • "revenueDeferralStatus": "deferRevenueUntilItemIsDelivered",
    • "billing": {
      • "quantity": null,
      • "rate": null,
      • "multiplier": null,
      • "discount": "0",
      • "template": {
        },
      • "schedule": {
        },
      • "startDate": "2017-01-01",
      • "endDate": "2017-12-31",
      • "method": "fixedPrice",
      • "amountFrequency": "useBillingTemplate",
      • "frequency": null,
      • "flatFixedAmount": "200",
      • "baseFlatFixedAmount": "200",
      • "totalFlatFixedAmount": "200",
      • "totalBaseFlatFixedAmount": "200",
      • "usageQuantityReset": "afterEachRenewal",
      • "isUsageQuantityRecurring": false,
      • "holdDate": null,
      • "resumeDate": null,
      • "memo": null,
      • "durationInPeriods": null,
      • "proratePartialPeriods": false,
      • "quantityType": null,
      • "committedQuantityEndAction": null,
      • "committedQuantityExcess": null
      },
    • "currency": {
      • "exchangeRateDate": "2017-01-01",
      • "exchangeRate": "1.000000000000"
      },
    • "contacts": {
      • "billTo": {
        },
      • "shipTo": {
        }
      },
    • "billToSource": "contractValue",
    • "shipToSource": "contractValue",
    • "renewal": {
      • "renew": false,
      • "billingTemplate": {
        }
      },
    • "isRecurring": false,
    • "lineType": "sale",
    • "revenue": {
      • "journal1": {
        },
      • "journal2": {
        },
      • "totalQuantity": null,
      • "holdDate": null,
      • "resumeDate": null,
      • "memo": null
      },
    • "dimensions": {
      • "location": {
        },
      • "department": {
        },
      • "task": {
        },
      • "customer": {
        },
      • "nsp::product_line1": {
        },
      • "nsp::region": {
        },
      • "nsp::vertical": {
        },
      • "project": {
        },
      • "vendor": {
        },
      • "employee": {
        },
      • "class": {
        }
      },
    • "audit": {
      • "createdDateTime": "2017-10-17T19:05:49Z",
      • "modifiedDateTime": "2019-03-20T17:08:44Z",
      • "createdByUser": {
        },
      • "createdBy": "1",
      • "modifiedByUser": {
        },
      • "modifiedBy": "109"
      },
    • "changeType": null,
    • "priceCalculationMemo": "Flat Amount: 200, Rate 0 per 1; Quantity  less included units 0",
    • "deliveryStatus": "delivered",
    • "deliveryDate": "2017-01-01",
    • "postingDate": "2017-01-01",
    • "expense": {
      • "holdDate": null,
      • "resumeDate": null,
      • "memo": null
      },
    • "memo": null,
    • "renewalTriggerDate": null,
    • "lineRenewalDate": null,
    • "href": "/objects/contracts/contract-line/3"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Update a contract line
patch/objects/contracts/contract-line/{key}
Updates an existing contract line by setting field values. Any fields not provided remain unchanged.


SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned key for the contract line.


 
 Example:  99
Request Body schema: application/json
state
string
 Default:  "inProgress"
State


 Enum: "canceled" "closed" "completed" "draft" "inProgress" "notRenewed" "renewalForecast" "renewalOnly" "revalued"  
 Example:  "completed"
startDate
string <date> 
Line start


 
 Example:  "2024-01-01"
endDate
string <date> 
Line end


 
 Example:  "2024-04-30"
changeType
string or null
 Default:  null
Change type


 Enum: "addOnMRR" "churnMRR" "downgrade" "newMRR" null "renewalDowngrade" "renewalUpgrade"  
 Example:  "newMRR"
itemDescription
string
Item description


 
 Example:  "API usage"
deliveryStatus
string
 Default:  "delivered"
Delivery status


 Enum: "delivered" "undelivered"  
 Example:  "undelivered"
postingDate
string <date> 
GL posting date


 
 Example:  "2024-01-01"
memo
string or null
Post Memo


 
 Example:  "POSTING LINE"
shipToSource
string
 Default:  "contractValue"
Specifies where the ship-to contact information should come from


 Enum: "contractValue" "userSpecifiedValue"  
 Example:  "contractValue"
billToSource
string
 Default:  "contractValue"
Specifies where the bill-to contact information should come from


 Enum: "contractValue" "userSpecifiedValue"  
 Example:  "contractValue"
revenueDeferralStatus
string
 Default:  "deferRevenueUntilItemIsDelivered"
Revenue recognition deferral status


 Enum: "deferRevenueUntilAllItemsAreDelivered" "deferRevenueUntilItemIsDelivered"  
 Example:  "deferRevenueUntilItemIsDelivered"
isRecurring
boolean
 Default:  false
Recurring


 
 Example:  false
object
 
exchangeRateDate
string <date> 
Exchange rate date


 
 Example:  "2024-01-01"
exchangeRate
string <decimal-precision-12> 
Exchange rate


 
 Example:  "1.345"
object
 
amountFrequency
string or null
Flat/fixed amount frequency


 Enum: "includeWithEveryInvoice" null "oneTime" "useBillingTemplate"  
 Example:  "oneTime"
object
Billing template to use.


 
key
string
Key


 
 Example:  "12"
id
string
Contract Billing Template ID


 
 Example:  "12P_BeginingPeriod"
method
string or null
 Default:  "fixedPrice"
Billing method


 Enum: "fixedPrice" null "projectMaterials" "projectT&M" "projectTime" "quantityBased"  
 Example:  "fixedPrice"
usageQuantityReset
string or null
 Default:  null
Reset usage quantity


 Enum: "afterEachInvoice" "afterEachRenewal" null  
 Example:  "afterEachRenewal"
isUsageQuantityRecurring
boolean
 Default:  false
Usage quantity recurs


 
 Example:  false
committedQuantityEndAction
string or null
 Default:  null
On contract line end date


 Enum: "billUnusedQuantity" "cancelUnusedQuantity" "doNothing" null  
 Example:  "billUnusedQuantity"
committedQuantityExcess
string or null
 Default:  null
If usage exceeds the committed quantity


 Enum: "billOverage" "doNotAllowOverage" "doNothing" null  
 Example:  "billOverage"
quantityType
string or null
 Default:  null
Quantity type


 Enum: "committed" null "variable"  
 Example:  "variable"
durationInPeriods
string
Duration (in periods)


 
 Example:  "3"
proratePartialPeriods
boolean
 Default:  false
Prorate partial periods?


 
 Example:  false
frequency
string or null
 Default:  null
Billing frequency


 Enum: "annually" "monthly" null "quarterly"  
 Example:  "monthly"
startDate
string <date> 
Billing start


 
 Example:  "2022-01-01"
endDate
string <date> 
Billing end


 
 Example:  "2022-04-30"
memo
string or null
Memo


 
 Example:  "Cash customer"
quantity
string or null
Quantity


 
 Example:  "8"
rate
string or null
Rate


 
 Example:  "100"
multiplier
string or null
Multiplier


 
 Example:  "1"
discount
string
 Default:  "0"
Discount


 
 Example:  "10"
flatFixedAmount
string
Flat/fixed amount


 
 Example:  "100"
baseFlatFixedAmount
string
Base flat/fixed amount


 
 Example:  "100"
object
 
memo
string or null
Memo


 
 Example:  "Cash customer"
object
 
object
 
object
 
startDate
string <date> 
Revenue 1 start date


 
 Example:  "2022-04-01"
endDate
string <date> 
Revenue 1 end date


 
 Example:  "2022-04-30"
object
 
object
 
startDate
string <date> 
Revenue 1 start date


 
 Example:  "2018-04-01"
endDate
string <date> 
Revenue 1 end date


 
 Example:  "2022-04-30"
totalQuantity
string
Total revenue quantity


 
 Example:  "30"
memo
string or null
Memo


 
 Example:  "Cash customer"
object
 
renew
boolean
 Default:  false
Renew


 
 Example:  false
object
 
key
string
Key


 
 Example:  "17"
id
string
Contract revenue template ID


 
 Example:  "12P_BeginingPeriod"
object
contract


 
key
string
Contract unique key


 
 Example:  "249"
id
string
Contract unique identifier


 
 Example:  "CON-0045"
object
 
key
string
Item Key


 
 Example:  "13"
id
string
Item ID


 
 Example:  "API3.0"
object
 
object
Location or entity associated with the contract. This field is required in a multi-entity environment. Contract lines are restricted to the specified location or entity or to a child of the location or entity.


 
key
string
Location Key


 
 Example:  "22"
id
string
Location


 
 Example:  "LOC-22"
object
Department associated with the contract.


 
key
string or null
Department Key


 
 Example:  "11"
id
string or null
Department


 
 Example:  "DEP-11"
object
 
key
string or null
Class Key


 
 Example:  "731"
id
string or null
Class ID


 
 Example:  "REST_CLS_001"
object
 
id
string or null
Task ID


 
 Example:  "1"
key
string or null
Task Key


 
 Example:  "1"
object
 
key
string or null
Vendor Key


 
 Example:  "357"
id
string or null
Vendor ID


 
 Example:  "1605212096809"
object
Customer that the contract is associated with. The customer cannot be changed after a contract line has been posted to the contract.


 
key
string
Customer Key


 
 Example:  "250"
id
string
Customer ID


 
 Example:  "CUS-RT-0011"
object
 
key
string or null
Project Key


 
 Example:  "2"
id
string or null
Project ID


 
 Example:  "NET-XML30-2"
object
 
key
string or null
Employee Key


 
 Example:  "10"
id
string or null
Employee ID


 
 Example:  "EMP-10"
Responses 
200
OK


400
Bad Request


Request samples 
application/json
{
  • "item": {
    • "key": "3"
    },
  • "dimensions": {
    • "location": {
      • "key": "1"
      }
    },
  • "startDate": "2022-01-01",
  • "endDate": "2022-12-31",
  • "billing": {
    • "quantity": "12",
    • "rate": "12",
    • "multiplier": "1",
    • "discount": "0",
    • "method": "fixedPrice",
    • "amountFrequency": "includeWithEveryInvoice",
    • "frequency": "monthly",
    • "flatFixedAmount": "144",
    • "baseFlatFixedAmount": "144",
    • "totalFlatFixedAmount": "1728",
    • "totalBaseFlatFixedAmount": "1728"
    },
  • "changeType": "newMRR",
  • "lineType": "sale",
  • "revenue": {
    • "journal1": {
      • "revenueTemplate": {
        }
      },
    • "journal2": {
      • "revenueTemplate": {
        }
      }
    },
  • "postingDate": "2022-01-01"
}
Response samples 
application/json
{
  • "ia::result": {
    • "id": "3",
    • "key": "3",
    • "href": "/objects/contracts/contract-line/3"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Delete a contract line
delete/objects/contracts/contract-line/{key}
Deletes a contract line.


SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned key for the contract line.


 
 Example:  99
Responses 
204
No Content


400
Bad Request


Request samples 
Response samples 
application/json
{
  • "ia::result": {
    • "ia::error": {
      • "code": "invalidRequest",
      • "message": "A POST request requires a payload",
      • "errorId": "REST-1028",
      • "additionalInfo": {
        },
      • "supportId": "Kxi78%7EZuyXBDEGVHD2UmO1phYXDQAAAAo"
      }
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 0,
    • "totalError": 1
    }
}