Get Revenue Contract
GET /accounting/revenue-contracts/{id}
Group: Accounting › Revenue Contracts · Operation ID: getRevenueContract
Returns the revenue contract with the given identifier, including its revenue lines, each line's revenue plan and that plan's period rows. Use the contract's id, not its revenueContractNumber.
Open in the interactive reference
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Api-Version |
header | "v1" |
yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1. |
id |
path | string | yes | The unique identifier for the revenue contract to return. |
Response
200 Success
Under data (getRevenueContractOutput):
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The unique identifier for the revenue contract. |
revenueContractNumber |
string | no | The revenue contract number, unique within the tenant. |
approvalStatus |
string | yes | The approval status of the contract. Possible values: 'draft', 'pendingApproval', 'revise', 'approved', 'rejected'. |
generalStatus |
string | no | The overall status of the contract, combining approval and any active revenue hold. Possible values: 'approved', 'approvedOnHold', 'pendingApproval', 'pendingApprovalOnHold'. |
revenueStatus |
string | no | The revenue-recognition progress across the contract's lines. Possible values: 'notStarted', 'notStartedOnHold', 'inProgress', 'inProgressOnHold', 'complete', 'completeModified'. |
isContractClosed |
boolean | yes | Whether the contract has been closed, with its open revenue moved to a new combined revenue contract. |
isContractCombined |
boolean | yes | Whether the contract is the combination target that absorbed a closed contract's open revenue. |
isLongTermContract |
boolean | no | Whether the recognition window from revenueStartDate to revenueEndDate exceeds 366 days. |
sspCompliant |
boolean | no | Whether every line not excluded from allocation is standalone-selling-price compliant. Absent when every line is excluded from allocation. |
currency |
string | yes | The currency the contract is denominated in. Every amount on the contract is in this currency. Format ISO 4217, for example 'USD'. |
functionalCurrency |
string | no | The owning entity's functional currency. Present only when it differs from the contract currency. Format ISO 4217, for example 'USD'. |
exchangeRate |
string (decimal) | yes | The rate used to convert the contract currency to the entity's functional currency. A ratio, not an amount, with no currency of its own. |
entityId |
string | no | The legal entity that owns this contract. See id on GET base/entities. |
entityName |
string | no | The name of the legal entity that owns this contract. |
customerId |
string | no | The customer this contract is with. See id on GET accounting/customers/:id. |
customerName |
string | no | The display name of the customer this contract is with. |
salesOrderId |
string | no | The sales order this contract was created from. See id on GET accounting/sales-orders/:id. |
salesOrderNumber |
string | no | The number of the sales order this contract was created from. |
modifiedRevenueContractId |
string | no | The revenue contract this one was combined or modified into. Absent when there is no such successor. See id on GET accounting/revenue-contracts/:id. |
closeContractDate |
string (date-time) | no | The date and time the contract was closed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Absent on an open contract. |
migrationDate |
string (date) | no | The date this contract's opening balances were migrated from a prior system. Format YYYY-MM-DD. Absent on a contract created natively. |
revenueStartDate |
string (date) | no | The earliest revenue-recognition start date across the contract's lines. Format YYYY-MM-DD. |
revenueEndDate |
string (date) | no | The latest revenue-recognition end date across the contract's lines. Format YYYY-MM-DD. |
salesEffectiveDate |
string (date) | no | The book date of the sales order this contract was created from. Format YYYY-MM-DD. |
totalContractValue |
string (decimal) | no | The total contract value, in the contract currency. It is the total price of the sales order this contract was created from, less the contract's cost-of-contract-value. |
totalContractAmount |
string (decimal) | no | The total contract amount across the contract's open lines, in the contract currency. |
totalCostOfContractValue |
string (decimal) | no | The total cost-of-contract-value excluded from the revenue calculation, in the contract currency. |
totalCostOfRevenue |
string (decimal) | no | The total cost of revenue recognized, in the contract currency. |
totalEstimatedTransactionPrice |
string (decimal) | no | The total estimated transaction price used in allocation, in the contract currency. |
totalFairValueAmount |
string (decimal) | no | The total fair value used in allocation, in the contract currency. |
totalVariableConsideration |
string (decimal) | no | The total variable consideration across the contract's lines, in the contract currency. |
deferredRevenue |
string (decimal) | no | The deferred revenue not yet recognized, in the contract currency. Zero once the contract is closed. |
revenueAmount |
string (decimal) | no | The total revenue across the contract's lines, in the contract currency. |
revenueRecognized |
string (decimal) | no | The cumulative revenue recognized to date, in the contract currency. |
revenueRemaining |
string (decimal) | no | The revenue remaining to be recognized, in the contract currency. |
remainingPerformanceObligation |
string (decimal) | no | The remaining performance obligation, in the contract currency. It is contract value plus returns and variable consideration, less committed recognized revenue. Zero once the contract is closed. |
unbilledReceivables |
string (decimal) | no | The sum of unbilled journal entries for this contract, in the contract currency. |
returnedAmount |
string (decimal) | no | The amount returned against the contract's revenue plan, in the contract currency. |
oneTimeDiscountAmount |
string (decimal) | no | The one-time discount allocated across the contract's lines, in the contract currency. |
pctRevenueRecognized |
string (decimal) | no | The fraction of total contract value recognized to date, from 0 to 1. 1 once the contract is closed. A ratio, not an amount, with no currency of its own. |
externalIdentifiers |
array of object | no | The contract's identifiers in other systems, one per configured field name. An empty array or absent when the contract has none. |
externalIdentifiers[].fieldName |
string | yes | The configured field name of the identifier, for example 'netsuiteRevenueContractId'. |
externalIdentifiers[].value |
string | yes | The identifier in the other system. |
externalIdentifiers[].externalUrl |
string | no | A link to the record in the other system. Absent when none is stored. |
lines |
array of object | no | The contract's revenue lines, in line order, each with its revenue plan nested. An empty array when the contract has no lines. |
lines[].id |
string | yes | The unique identifier for the revenue contract line. |
lines[].revenueContractLineNumber |
string | no | The revenue contract line number, unique within the contract. |
lines[].type |
string | yes | The kind of line. Possible values: 'standard', 'thresholdIncrement', 'overage'. |
lines[].currency |
string | yes | The currency the line is denominated in. Every amount on the line and its revenue plan is in this currency. Format ISO 4217, for example 'USD'. |
lines[].functionalCurrency |
string | no | The owning entity's functional currency. Present only when it differs from the line currency. Format ISO 4217, for example 'USD'. |
lines[].exchangeRate |
string (decimal) | no | The rate used to convert the line currency to the functional currency. A ratio, not an amount, with no currency of its own. |
lines[].generalStatus |
string | no | The overall status of the line, combining approval and any active revenue hold. Possible values: 'notStarted', 'notStartedOnHold', 'inProgress', 'inProgressOnHold', 'complete', 'completeModified'. |
lines[].revenueStatus |
string | no | The revenue-recognition progress for the line. Possible values: 'notStarted', 'notStartedOnHold', 'inProgress', 'inProgressOnHold', 'complete', 'completeModified'. |
lines[].isClosed |
boolean | yes | Whether the line has been closed, with its open revenue moved to a combined contract. |
lines[].isLongTerm |
boolean | no | Whether the line's recognition window exceeds 366 days. |
lines[].isEvergreen |
boolean | no | Whether the line has no fixed end date and recognizes indefinitely. |
lines[].sspCompliant |
boolean | no | Whether the line is standalone-selling-price compliant. |
lines[].isAllocationExcluded |
boolean | no | Whether the line is excluded from the contract's revenue allocation. |
lines[].productCode |
string | no | The code of the product the line covers, as it stood when the line was created. |
lines[].unitOfMeasure |
string | no | The unit the line's quantity is measured in. Possible values: 'instance', 'gigabyte', 'terabyte', 'user', 'seat', 'minute', 'hour', 'day', 'month', 'each', 'license', 'activeUser', 'megabyte', 'message', 'text', 'platform', 'employee', 'personnel', 'credit', 'currency', 'package', 'case', 'word', 'record'. |
lines[].performanceObligationName |
string | no | The name of the performance obligation the line satisfies. |
lines[].operationalPerformanceObligationNumber |
string | no | The number of the operational performance obligation the line is tracked under. |
lines[].revenueSchedulingTemplateName |
string | no | The name of the revenue scheduling template that generated the line's plan. |
lines[].revenueRecognitionPattern |
string | no | How revenue is recognized over the line's term. Possible values: 'upfront', 'overTime', 'asDelivered', 'asConsumed'. |
lines[].amortizationMethod |
string | no | How the line's amount is spread across periods. Possible values: 'exactDays', 'pointInTime', 'straightLineProRateFirstLast', 'straightLine', 'usageBased'. |
lines[].revenueSchedulingEvent |
string | yes | The event that starts recognition on the line. Possible values: 'revenueArrangementCreation', 'uponInvoicing', 'uponUsageConsumption', 'manualRelease', 'uponInvoicingPercentInvoiced', 'uponInvoicingFullAmount', 'serviceActivation'. |
lines[].revenueAccount |
string | no | The name of the revenue account the line recognizes into. |
lines[].deferredRevenueAccount |
string | no | The name of the deferred-revenue account the line defers into. |
lines[].revRecStartDate |
string (date) | no | The first day of the line's revenue-recognition window. Format YYYY-MM-DD. |
lines[].revRecEndDate |
string (date) | no | The last day of the line's revenue-recognition window, inclusive. Format YYYY-MM-DD. |
lines[].salesOrderBookingDate |
string (date) | no | The book date of the sales order line this line was created from. Format YYYY-MM-DD. |
lines[].revenueTerm |
string (decimal) | no | The length of the line's revenue term, in the line's scheduling unit. A count, not an amount. |
lines[].salesOrderProductLine |
string | no | The number of the sales order product line this line was created from. |
lines[].contractAmount |
string (decimal) | no | The contract amount booked on the line, in the line currency. |
lines[].adjustedContractAmount |
string (decimal) | no | The contract amount after modifications, in the line currency. |
lines[].listPrice |
string (decimal) | no | The undiscounted list price of the line, in the line currency. |
lines[].totalContractValue |
string (decimal) | no | The total contract value attributed to the line, in the line currency. |
lines[].totalCostOfContractValue |
string (decimal) | no | The cost-of-contract-value excluded from the line's revenue calculation, in the line currency. |
lines[].costOfRevenueAmount |
string (decimal) | no | The cost of revenue booked on the line, in the line currency. |
lines[].costOfRevenueRecognized |
string (decimal) | no | The cost of revenue recognized to date on the line, in the line currency. |
lines[].estimatedTransactionPrice |
string (decimal) | no | The estimated transaction price used for the line in allocation, in the line currency. |
lines[].fairValueAmount |
string (decimal) | no | The fair value used for the line in allocation, in the line currency. |
lines[].variableConsideration |
string (decimal) | no | The variable consideration on the line, in the line currency. |
lines[].extendedSSP |
string (decimal) | no | The extended standalone selling price of the line, unit standalone selling price times quantity, in the line currency. |
lines[].revenueAmount |
string (decimal) | no | The revenue allocated to the line, in the line currency. |
lines[].revenueRecognized |
string (decimal) | no | The revenue recognized to date on the line, in the line currency. |
lines[].revenueRemaining |
string (decimal) | no | The revenue still to be recognized on the line, in the line currency. |
lines[].deferredRevenueAmount |
string (decimal) | no | The deferred revenue outstanding on the line, in the line currency. |
lines[].remainingPerformanceObligation |
string (decimal) | no | The remaining performance obligation on the line, in the line currency. |
lines[].unbilledReceivables |
string (decimal) | no | The unbilled receivables on the line, in the line currency. |
lines[].unscheduledRevenue |
string (decimal) | no | The revenue on the line not yet scheduled into a plan period, in the line currency. |
lines[].totalInvoicedAmount |
string (decimal) | no | The total invoiced against the line to date, in the line currency. |
lines[].oneTimeDiscountAllocationAmount |
string (decimal) | no | The one-time discount allocated to the line, in the line currency. |
lines[].fvAllocationRatio |
string (decimal) | no | The share of the contract's fair value allocated to the line, from 0 to 1. A ratio, not an amount, with no currency of its own. |
lines[].revenuePlanHeader |
object | no | The line's revenue plan, the schedule revenue is recognized against. At most one per line. Absent when no plan has been generated for the line yet. |
lines[].revenuePlanHeader.id |
string | yes | The unique identifier for the revenue plan header. |
lines[].revenuePlanHeader.revenuePlanHeaderNumber |
string | no | The revenue plan header number. |
lines[].revenuePlanHeader.status |
string | no | The status of the plan. Possible values: 'notStarted', 'pendingRecognition', 'inProgress', 'complete', 'completeModified'. |
lines[].revenuePlanHeader.currency |
string | yes | The currency the plan is denominated in. Every amount on the plan and its plan lines is in this currency. Format ISO 4217, for example 'USD'. |
lines[].revenuePlanHeader.amortizationMethod |
string | no | How the plan spreads its amount across periods. Possible values: 'exactDays', 'pointInTime', 'straightLineProRateFirstLast', 'straightLine', 'usageBased'. |
lines[].revenuePlanHeader.revenueSchedulingEvent |
string | yes | The event that starts recognition on the plan. Possible values: 'revenueArrangementCreation', 'uponInvoicing', 'uponUsageConsumption', 'manualRelease', 'uponInvoicingPercentInvoiced', 'uponInvoicingFullAmount', 'serviceActivation'. |
lines[].revenuePlanHeader.isContractClosed |
boolean | yes | Whether the contract behind the plan has been closed. |
lines[].revenuePlanHeader.revRecStartDate |
string (date) | no | The first day of the plan's recognition window. Format YYYY-MM-DD. |
lines[].revenuePlanHeader.revRecEndDate |
string (date) | no | The last day of the plan's recognition window, inclusive. Format YYYY-MM-DD. |
lines[].revenuePlanHeader.comments |
string | no | Free-form comments recorded on the plan. |
lines[].revenuePlanHeader.amount |
string (decimal) | no | The total amount the plan schedules, in the plan currency. |
lines[].revenuePlanHeader.totalRecognized |
string (decimal) | no | The total recognized across the plan's lines to date, in the plan currency. |
lines[].revenuePlanHeader.remainingDeferred |
string (decimal) | no | The amount still deferred on the plan, in the plan currency. |
lines[].revenuePlanHeader.returnedAmount |
string (decimal) | no | The amount returned against the plan, in the plan currency. |
lines[].revenuePlanHeader.unscheduledRevenue |
string (decimal) | no | The plan amount not yet scheduled into a period, in the plan currency. |
lines[].revenuePlanHeader.revenuePlanLines |
array of object | no | The plan's period rows, the recognition schedule, one entry per planned period, earliest planned period first. An empty array when the plan has not been scheduled yet. |
lines[].revenuePlanHeader.revenuePlanLines[].id |
string | yes | The unique identifier for the revenue plan line. |
lines[].revenuePlanHeader.revenuePlanLines[].lineId |
string | no | The line identifier within the plan. |
lines[].revenuePlanHeader.revenuePlanLines[].revenuePlanType |
string | yes | What the plan line schedules. Possible values: 'revenueRecognition', 'returnRevenueRecognition', 'unCommittedRevenueRecognition', 'modificationDeferredRevenueAdjustment', 'allowance', 'overage', 'usageExpiration', 'costOfRevenue', 'unholdRevenuePeriod', 'retrospectiveAdjustment'. |
lines[].revenuePlanHeader.revenuePlanLines[].currency |
string | yes | The currency the plan line is denominated in. Format ISO 4217, for example 'USD'. |
lines[].revenuePlanHeader.revenuePlanLines[].plannedPeriod |
string | no | The name of the accounting period this row is planned for. |
lines[].revenuePlanHeader.revenuePlanLines[].plannedPeriodDate |
string (date) | no | The start date of the planned accounting period. Format YYYY-MM-DD. Plan lines are returned in ascending order of this date. |
lines[].revenuePlanHeader.revenuePlanLines[].postingPeriod |
string | no | The name of the accounting period the row was posted in, when it differs from the planned one. |
lines[].revenuePlanHeader.revenuePlanLines[].isPosted |
boolean | no | Whether the row has been posted to the general ledger. |
lines[].revenuePlanHeader.revenuePlanLines[].holdStatus |
string | no | Whether revenue on the row is held back. Possible values: 'notHold', 'holdPlaced', 'holdRemoved'. |
lines[].revenuePlanHeader.revenuePlanLines[].releaseUnit |
string | no | The unit the release amount is expressed in. Possible values: 'quantity', 'percent', 'amount'. |
lines[].revenuePlanHeader.revenuePlanLines[].releaseAmount |
string (decimal) | no | The amount or quantity released in this period, in the unit given by releaseUnit. |
lines[].revenuePlanHeader.revenuePlanLines[].pctRecognizedInPeriod |
string (decimal) | no | The fraction of the plan recognized in this period, from 0 to 1. A ratio, not an amount, with no currency of its own. |
lines[].revenuePlanHeader.revenuePlanLines[].cumulativePercentage |
string (decimal) | no | The fraction of the plan recognized cumulatively through this period, from 0 to 1. A ratio, not an amount, with no currency of its own. |
lines[].revenuePlanHeader.revenuePlanLines[].revenueAccount |
string | no | The name of the revenue account this row recognizes into. |
lines[].revenuePlanHeader.revenuePlanLines[].deferredRevenueAccount |
string | no | The name of the deferred-revenue account this row releases from. |
lines[].revenuePlanHeader.revenuePlanLines[].journalEntry |
string | no | The number of the journal entry this row posted through, once posted. |
lines[].revenuePlanHeader.revenuePlanLines[].amount |
string (decimal) | no | The amount scheduled for this period, in the plan line currency. |
lines[].revenuePlanHeader.revenuePlanLines[].revenueAmount |
string (decimal) | no | The revenue scheduled for this period, in the plan line currency. |
lines[].revenuePlanHeader.revenuePlanLines[].revenueRecognized |
string (decimal) | no | The revenue recognized in this period, in the plan line currency. |
lines[].revenuePlanHeader.revenuePlanLines[].cumulativeRecognition |
string (decimal) | no | The revenue recognized cumulatively through this period, in the plan line currency. |
lines[].revenuePlanHeader.revenuePlanLines[].unscheduledRevenue |
string (decimal) | no | The amount on this row not yet scheduled, in the plan line currency. |
lines[].revenuePlanHeader.revenuePlanLines[].postedAmount |
string (decimal) | no | The amount actually posted to the ledger for this row, in the plan line currency. |
lastModifiedDate |
string (date-time) | yes | The date and time the revenue contract last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
Errors
| Code | Status |
|---|---|
NOT_FOUND |
400 |
Statuses
400— Invalid request or business failure. Codes: NOT_FOUND401— Missing or invalid access token403— Not authorized404— Not found429— Too many requests500— Internal server error