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 query 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

Department Key

Example: "11"
id
string

Department

Example: "DEP-11"
name
string

Department name

Example: "Human Resources"
object
key
string

Class Key

Example: "731"
id
string

Class ID

Example: "REST_CLS_001"
object
id
string

Task ID

Example: "1"
key
string

Task Key

Example: "1"
object
key
string

Vendor Key

Example: "357"
id
string

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

Project Key

Example: "2"
id
string

Project ID

Example: "NET-XML30-2"
object
key
string

Employee Key

Example: "10"
id
string

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",
      • "createdBy": "1",
      • "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

Department Key

Example: "11"
id
string

Department

Example: "DEP-11"
name
string

Department name

Example: "Human Resources"
object
key
string

Class Key

Example: "731"
id
string

Class ID

Example: "REST_CLS_001"
object
id
string

Task ID

Example: "1"
key
string

Task Key

Example: "1"
object
key
string

Vendor Key

Example: "357"
id
string

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

Project Key

Example: "2"
id
string

Project ID

Example: "NET-XML30-2"
object
key
string

Employee Key

Example: "10"
id
string

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
    }
}

Query contract lines

post/services/core/query

Use the query service to find contract lines that meet certain criteria and to specify the properties that are returned.

SecurityOAuth2
Responses
200

OK

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
    }
}