Contract usage

A usage record contains the quantity of a contract line item that a customer used or consumed during a specific time period. Usage records are used for contract quantity-based billing and quantity-based revenue recognition.

List contract usage

get/objects/contracts/contract-usage

Returns up to 100 object references from the collection with a key, ID, and link for each contract usage. 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": "84",
      • "id": "RT-00001",
      • "href": "/objects/contracts/contract-usage/84"
      },
    • {
      • "key": "85",
      • "id": "RT-00002",
      • "href": "/objects/contracts/contract-usage/85"
      }
    ],
  • "ia::meta": {
    • "totalCount": 2,
    • "start": 1,
    • "pageSize": 100,
    • "next": null,
    • "previous": null
    }
}
Create contract usage
post/objects/contracts/contract-usage
Creates a new contract usage


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


required
object
The contract line associated with the usage record.


 
key
string
Contract detail key.


 
 Example:  "3"
id
string
Contract line ID.


 
 Example:  "3"
usageDate
required
string <date> 
The date associated with the usage. For recurring usage, the usage date is the effective date of the initial recurring usage record.


Usage records must be added oldest to newest. For information on the restrictions for this field, see the Usage date description on the Add Usage page.


 
 Example:  "2025-02-01"
quantity
required
string
The quantity of the item that was used.


 
 Example:  "1"
object
The contract associated with the usage record.


 
key
string
Contract key.


 
 Example:  "34"
id
string
Contract ID.


 
 Example:  "CAR-IMPLEMENTATION"
object
The item associated with the usage record.


 
key
string
Item key.


 
 Example:  "306"
id
string
Item ID.


 
 Example:  "LICNERP"
usageType
string
 Default:  "billingVariable"
Usage type.


    

  • billingCommitted - The usage record is associated with a committed quantity contract line. The usage quantity is used for billing and counts towards the committed quantity. It’s billed at the committed quantity rate.
    • 

  • billingOverage - The usage record is associated with a committed quantity contract line where the committed quantity has been completely consumed and overage is allowed for billing. The usage quantity is used for billing and is billed at the applicable billing price list rate.
    • 

  • billingVariable - The usage record is associated with a variable quantity contract line. The usage quantity is used for billing and is billed at the applicable billing price list rate.
    • 

  • revenue - The usage record is associated with a quantity-based revenue recognition contract line that may also use committed quantity billing. The usage quantity is used for quantity-based revenue recognition and may also be used for committed quantity billing.
    • 

  • trackedRevenue - The usage record is associated with a quantity-based revenue recognition contract line and the total revenue quantity has been used. The contract line may also use committed quantity billing and the "If usage exceeds the committed quantity" field is set to "Do nothing". You can report on this type of usage, but you cannot recognize or bill it.
    • 

  • trackedVariable - The usage record is associated with a committed quantity contract line where the committed quantity has been completely consumed and the "If usage exceeds the committed quantity" field = "Do nothing". You can report on this type of usage, but you cannot bill it.
    • 

  • canceled
    • 



 Enum: "billingCommitted" "billingOverage" "billingVariable" "canceled" "revenue" "trackedRevenue" "trackedVariable"  
 Example:  "revenue"
object
 
billedDate
string or null <date> 
The transaction date on the invoice associated with the usage record.


 
 Example:  "2022-01-01"
recurringUsageDate
string or null <date> 
The date the recurring usage record is available to bill. Intacct automatically sets this date when it creates the recurring usage record. This field is only applicable if the contract line has usage quantity recurs set to true.


 
 Example:  "2022-01-01"
servicePeriodStartDate
string or null <date> 
The beginning of the time frame during which the company's services are provided or consumed for this usage entry.


 
 Example:  "2025-04-01"
servicePeriodEndDate
string or null <date> 
The end of the time frame during which the company's services are provided or consumed for this usage entry.


 
 Example:  "2025-04-30"
Responses 
201
Created


400
Bad Request


Request samples 
application/json
{
  • "contractLine": {
    • "key": "1"
    },
  • "usageDate": "2025-04-01",
  • "quantity": "3003.99",
  • "usageType": "revenue"
}
Response samples 
application/json
{
  • "ia::result": {
    • "id": "6",
    • "key": "6",
    • "href": "/objects/contracts/contract-usage/6"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Get a contract usage
get/objects/contracts/contract-usage/{key}
Returns detailed information for a specified contract usage.


SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned key for a contract usage.


 
 Example:  4532
Responses 
200
OK


400
Bad Request


Request samples 
Response samples 
application/json
{
  • "ia::result": {
    • "id": "4",
    • "key": "4",
    • "contractLine": {
      • "id": "122",
      • "key": "122",
      • "lineNumber": "1",
      • "href": "/objects/contracts/contract-line/122"
      },
    • "usageDate": "2025-01-15",
    • "quantity": "10",
    • "servicePeriodStartDate": null,
    • "servicePeriodEndDate": null,
    • "usageType": "revenue",
    • "documentId": "Contract Invoice-CONIN#0110#doc",
    • "revenueScheduleLine": {
      • "id": "5247",
      • "key": "5247",
      • "postingDate": "2025-01-15",
      • "amount": "25",
      • "href": "/objects/contracts/revenue-schedule-line/5247"
      },
    • "revenueSchedule": {
      • "id": "631",
      • "key": "631",
      • "href": "/objects/contracts/revenue-schedule/631"
      },
    • "revenue2Schedule": {
      • "id": null,
      • "key": null
      },
    • "audit": {
      • "createdDateTime": "2024-02-08T00:10:25Z",
      • "modifiedDateTime": "2024-02-08T00:10:25Z",
      • "createdByUser": {
        },
      • "createdBy": "109",
      • "modifiedByUser": {
        },
      • "modifiedBy": "109"
      },
    • "contractUsageBilling": {
      • "billedDate": "2017-01-31",
      • "recurringUsageDate": null
      },
    • "contract": {
      • "key": "38",
      • "id": "CON-028",
      • "name": "Professional Power",
      • "href": "/objects/contracts/contract/38"
      },
    • "item": {
      • "key": "2547",
      • "id": "11",
      • "name": "GP",
      • "href": "/objects/inventory-control/item/2547"
      },
    • "customer": {
      • "key": "2",
      • "id": "2",
      • "name": "Logic Solutions",
      • "href": "/objects/accounts-receivable/customer/2"
      },
    • "href": "/objects/contracts/contract-usage/4"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Update a contract usage
patch/objects/contracts/contract-usage/{key}
Updates an existing contract usage by setting field values. Any fields not provided remain unchanged.


SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned key for a contract usage.


 
 Example:  4532
Request Body schema: application/json
object
The contract associated with the usage record.


 
key
string
Contract key.


 
 Example:  "34"
id
string
Contract ID.


 
 Example:  "CAR-IMPLEMENTATION"
object
The contract line associated with the usage record.


 
key
string
Contract detail key.


 
 Example:  "3"
id
string
Contract line ID.


 
 Example:  "3"
usageDate
string <date> 
The date associated with the usage. For recurring usage, the usage date is the effective date of the initial recurring usage record.


Usage records must be added oldest to newest. For information on the restrictions for this field, see the Usage date description on the Add Usage page.


 
 Example:  "2025-02-01"
quantity
string
The quantity of the item that was used.


 
 Example:  "1"
object
The item associated with the usage record.


 
key
string
Item key.


 
 Example:  "306"
id
string
Item ID.


 
 Example:  "LICNERP"
usageType
string
 Default:  "billingVariable"
Usage type.


    

  • billingCommitted - The usage record is associated with a committed quantity contract line. The usage quantity is used for billing and counts towards the committed quantity. It’s billed at the committed quantity rate.
    • 

  • billingOverage - The usage record is associated with a committed quantity contract line where the committed quantity has been completely consumed and overage is allowed for billing. The usage quantity is used for billing and is billed at the applicable billing price list rate.
    • 

  • billingVariable - The usage record is associated with a variable quantity contract line. The usage quantity is used for billing and is billed at the applicable billing price list rate.
    • 

  • revenue - The usage record is associated with a quantity-based revenue recognition contract line that may also use committed quantity billing. The usage quantity is used for quantity-based revenue recognition and may also be used for committed quantity billing.
    • 

  • trackedRevenue - The usage record is associated with a quantity-based revenue recognition contract line and the total revenue quantity has been used. The contract line may also use committed quantity billing and the "If usage exceeds the committed quantity" field is set to "Do nothing". You can report on this type of usage, but you cannot recognize or bill it.
    • 

  • trackedVariable - The usage record is associated with a committed quantity contract line where the committed quantity has been completely consumed and the "If usage exceeds the committed quantity" field = "Do nothing". You can report on this type of usage, but you cannot bill it.
    • 

  • canceled
    • 



 Enum: "billingCommitted" "billingOverage" "billingVariable" "canceled" "revenue" "trackedRevenue" "trackedVariable"  
 Example:  "revenue"
object
 
billedDate
string or null <date> 
The transaction date on the invoice associated with the usage record.


 
 Example:  "2022-01-01"
recurringUsageDate
string or null <date> 
The date the recurring usage record is available to bill. Intacct automatically sets this date when it creates the recurring usage record. This field is only applicable if the contract line has usage quantity recurs set to true.


 
 Example:  "2022-01-01"
servicePeriodStartDate
string or null <date> 
The beginning of the time frame during which the company's services are provided or consumed for this usage entry.


 
 Example:  "2025-04-01"
servicePeriodEndDate
string or null <date> 
The end of the time frame during which the company's services are provided or consumed for this usage entry.


 
 Example:  "2025-04-30"
Responses 
200
OK


400
Bad Request


Request samples 
application/json
{
  • "quantity": "400"
}
Response samples 
application/json
{
  • "ia::result": {
    • "key": "12",
    • "id": "2021-LV2",
    • "href": "/objects/contracts/contract-usage/12"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Delete contract usage
delete/objects/contracts/contract-usage/{key}
Delete a contract usage. See the Intacct Help for restrictions on deleting contract usage.


SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned key for a contract usage.


 
 Example:  4532
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 usages
post/services/core/query
Use the query service to find contract usages 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
    }
}