Search Revenue Contract

POST /accounting/revenue-contracts/search

Group: Accounting › Revenue Contracts · Operation ID: searchRevenueContract

Returns the revenue contracts that match the given filters. Each match is the full contract, including its revenue lines, revenue plans and period rows. For a cheaper header-only list, use GET accounting/revenue-contracts.

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.

Request body

Required, application/json: searchRevenueContractInput.

Field Type Required Description
filters object no The filters to apply. A revenue contract must match every filter you send. Omit to return all revenue contracts.
filters.id string no Limits results to the revenue contract with this id.
filters.revenueContractNumber string no Limits results to the revenue contract with this number. The match is exact.
filters.approvalStatus string no Limits results to contracts in this approval status. Possible values: 'draft', 'pendingApproval', 'revise', 'approved', 'rejected'. Any other value matches no contract.
filters.generalStatus string no Limits results to contracts in this general status. Possible values: 'approved', 'approvedOnHold', 'pendingApproval', 'pendingApprovalOnHold'. Any other value matches no contract.
filters.revenueStatus string no Limits results to contracts in this revenue-recognition status. Possible values: 'notStarted', 'notStartedOnHold', 'inProgress', 'inProgressOnHold', 'complete', 'completeModified'. Any other value matches no contract.
filters.currency string no Limits results to contracts in this currency. Format ISO 4217, for example 'USD'.
filters.isContractClosed boolean no Limits results to closed contracts when true, or open contracts when false.
filters.isContractCombined boolean no Limits results to combination-target contracts when true, or ordinary contracts when false.
filters.customerId string no Limits results to contracts with this customer. See id on GET accounting/customers/:id. An id that matches no customer returns no contracts.
filters.entityId string no Limits results to contracts owned by this legal entity. See id on GET base/entities. An id that matches no entity returns no contracts.
filters.salesOrderId string no Limits results to contracts created from this sales order. See id on GET accounting/sales-orders/:id. An id that matches no sales order returns no contracts.
filters.externalIdentifier object no Limits results to the contract with this external identifier. Give both fieldName and value. A fieldName alone would match every system's value for that key.
filters.externalIdentifier.fieldName string yes The configured field name of the identifier, for example 'netsuiteRevenueContractId'.
filters.externalIdentifier.value string yes The identifier value to match, exactly as the other system stores it.
filters.revenueStartDate object no Limits results to contracts whose revenueStartDate falls in this range. Omit either bound to leave that side open. Both bounds are inclusive.
filters.revenueStartDate.start string (date) no The earliest revenueStartDate to include, inclusive. Format YYYY-MM-DD.
filters.revenueStartDate.end string (date) no The latest revenueStartDate to include, inclusive. Format YYYY-MM-DD.
filters.revenueEndDate object no Limits results to contracts whose revenueEndDate falls in this range. Omit either bound to leave that side open. Both bounds are inclusive.
filters.revenueEndDate.start string (date) no The earliest revenueEndDate to include, inclusive. Format YYYY-MM-DD.
filters.revenueEndDate.end string (date) no The latest revenueEndDate to include, inclusive. Format YYYY-MM-DD.
page object no Pagination controls. Omit for the first page.
page.cursor string no The cursor from the previous response's pagination.nextCursor. Omit for the first page.
page.size number no The number of revenue contracts per page. Defaults to 50. A value above 200 is treated as 200, not rejected.

Example:

{
  "filters": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "revenueContractNumber": "<revenueContractNumber>",
    "approvalStatus": "<approvalStatus>",
    "generalStatus": "<generalStatus>",
    "revenueStatus": "<revenueStatus>",
    "currency": "<currency>",
    "isContractClosed": true,
    "isContractCombined": true,
    "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "salesOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "externalIdentifier": {
      "fieldName": "<fieldName>",
      "value": "<value>"
    },
    "revenueStartDate": {
      "start": "2026-01-15",
      "end": "2026-01-15"
    },
    "revenueEndDate": {
      "start": "2026-01-15",
      "end": "2026-01-15"
    }
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}

Response

200 Success

Under data (searchRevenueContractOutput):

Field Type Required Description
items array of object yes The revenue contracts on this page, most recently created first. An empty array when nothing matches.
items[].id string yes The unique identifier for the revenue contract.
items[].revenueContractNumber string no The revenue contract number, unique within the tenant.
items[].approvalStatus string yes The approval status of the contract. Possible values: 'draft', 'pendingApproval', 'revise', 'approved', 'rejected'.
items[].generalStatus string no The overall status of the contract, combining approval and any active revenue hold. Possible values: 'approved', 'approvedOnHold', 'pendingApproval', 'pendingApprovalOnHold'.
items[].revenueStatus string no The revenue-recognition progress across the contract's lines. Possible values: 'notStarted', 'notStartedOnHold', 'inProgress', 'inProgressOnHold', 'complete', 'completeModified'.
items[].isContractClosed boolean yes Whether the contract has been closed, with its open revenue moved to a new combined revenue contract.
items[].isContractCombined boolean yes Whether the contract is the combination target that absorbed a closed contract's open revenue.
items[].isLongTermContract boolean no Whether the recognition window from revenueStartDate to revenueEndDate exceeds 366 days.
items[].sspCompliant boolean no Whether every line not excluded from allocation is standalone-selling-price compliant. Absent when every line is excluded from allocation.
items[].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'.
items[].functionalCurrency string no The owning entity's functional currency. Present only when it differs from the contract currency. Format ISO 4217, for example 'USD'.
items[].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.
items[].entityId string no The legal entity that owns this contract. See id on GET base/entities.
items[].entityName string no The name of the legal entity that owns this contract.
items[].customerId string no The customer this contract is with. See id on GET accounting/customers/:id.
items[].customerName string no The display name of the customer this contract is with.
items[].salesOrderId string no The sales order this contract was created from. See id on GET accounting/sales-orders/:id.
items[].salesOrderNumber string no The number of the sales order this contract was created from.
items[].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.
items[].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.
items[].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.
items[].revenueStartDate string (date) no The earliest revenue-recognition start date across the contract's lines. Format YYYY-MM-DD.
items[].revenueEndDate string (date) no The latest revenue-recognition end date across the contract's lines. Format YYYY-MM-DD.
items[].salesEffectiveDate string (date) no The book date of the sales order this contract was created from. Format YYYY-MM-DD.
items[].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.
items[].totalContractAmount string (decimal) no The total contract amount across the contract's open lines, in the contract currency.
items[].totalCostOfContractValue string (decimal) no The total cost-of-contract-value excluded from the revenue calculation, in the contract currency.
items[].totalCostOfRevenue string (decimal) no The total cost of revenue recognized, in the contract currency.
items[].totalEstimatedTransactionPrice string (decimal) no The total estimated transaction price used in allocation, in the contract currency.
items[].totalFairValueAmount string (decimal) no The total fair value used in allocation, in the contract currency.
items[].totalVariableConsideration string (decimal) no The total variable consideration across the contract's lines, in the contract currency.
items[].deferredRevenue string (decimal) no The deferred revenue not yet recognized, in the contract currency. Zero once the contract is closed.
items[].revenueAmount string (decimal) no The total revenue across the contract's lines, in the contract currency.
items[].revenueRecognized string (decimal) no The cumulative revenue recognized to date, in the contract currency.
items[].revenueRemaining string (decimal) no The revenue remaining to be recognized, in the contract currency.
items[].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.
items[].unbilledReceivables string (decimal) no The sum of unbilled journal entries for this contract, in the contract currency.
items[].returnedAmount string (decimal) no The amount returned against the contract's revenue plan, in the contract currency.
items[].oneTimeDiscountAmount string (decimal) no The one-time discount allocated across the contract's lines, in the contract currency.
items[].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.
items[].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.
items[].externalIdentifiers[].fieldName string yes The configured field name of the identifier, for example 'netsuiteRevenueContractId'.
items[].externalIdentifiers[].value string yes The identifier in the other system.
items[].externalIdentifiers[].externalUrl string no A link to the record in the other system. Absent when none is stored.
items[].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.
items[].lines[].id string yes The unique identifier for the revenue contract line.
items[].lines[].revenueContractLineNumber string no The revenue contract line number, unique within the contract.
items[].lines[].type string yes The kind of line. Possible values: 'standard', 'thresholdIncrement', 'overage'.
items[].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'.
items[].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'.
items[].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.
items[].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'.
items[].lines[].revenueStatus string no The revenue-recognition progress for the line. Possible values: 'notStarted', 'notStartedOnHold', 'inProgress', 'inProgressOnHold', 'complete', 'completeModified'.
items[].lines[].isClosed boolean yes Whether the line has been closed, with its open revenue moved to a combined contract.
items[].lines[].isLongTerm boolean no Whether the line's recognition window exceeds 366 days.
items[].lines[].isEvergreen boolean no Whether the line has no fixed end date and recognizes indefinitely.
items[].lines[].sspCompliant boolean no Whether the line is standalone-selling-price compliant.
items[].lines[].isAllocationExcluded boolean no Whether the line is excluded from the contract's revenue allocation.
items[].lines[].productCode string no The code of the product the line covers, as it stood when the line was created.
items[].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'.
items[].lines[].performanceObligationName string no The name of the performance obligation the line satisfies.
items[].lines[].operationalPerformanceObligationNumber string no The number of the operational performance obligation the line is tracked under.
items[].lines[].revenueSchedulingTemplateName string no The name of the revenue scheduling template that generated the line's plan.
items[].lines[].revenueRecognitionPattern string no How revenue is recognized over the line's term. Possible values: 'upfront', 'overTime', 'asDelivered', 'asConsumed'.
items[].lines[].amortizationMethod string no How the line's amount is spread across periods. Possible values: 'exactDays', 'pointInTime', 'straightLineProRateFirstLast', 'straightLine', 'usageBased'.
items[].lines[].revenueSchedulingEvent string yes The event that starts recognition on the line. Possible values: 'revenueArrangementCreation', 'uponInvoicing', 'uponUsageConsumption', 'manualRelease', 'uponInvoicingPercentInvoiced', 'uponInvoicingFullAmount', 'serviceActivation'.
items[].lines[].revenueAccount string no The name of the revenue account the line recognizes into.
items[].lines[].deferredRevenueAccount string no The name of the deferred-revenue account the line defers into.
items[].lines[].revRecStartDate string (date) no The first day of the line's revenue-recognition window. Format YYYY-MM-DD.
items[].lines[].revRecEndDate string (date) no The last day of the line's revenue-recognition window, inclusive. Format YYYY-MM-DD.
items[].lines[].salesOrderBookingDate string (date) no The book date of the sales order line this line was created from. Format YYYY-MM-DD.
items[].lines[].revenueTerm string (decimal) no The length of the line's revenue term, in the line's scheduling unit. A count, not an amount.
items[].lines[].salesOrderProductLine string no The number of the sales order product line this line was created from.
items[].lines[].contractAmount string (decimal) no The contract amount booked on the line, in the line currency.
items[].lines[].adjustedContractAmount string (decimal) no The contract amount after modifications, in the line currency.
items[].lines[].listPrice string (decimal) no The undiscounted list price of the line, in the line currency.
items[].lines[].totalContractValue string (decimal) no The total contract value attributed to the line, in the line currency.
items[].lines[].totalCostOfContractValue string (decimal) no The cost-of-contract-value excluded from the line's revenue calculation, in the line currency.
items[].lines[].costOfRevenueAmount string (decimal) no The cost of revenue booked on the line, in the line currency.
items[].lines[].costOfRevenueRecognized string (decimal) no The cost of revenue recognized to date on the line, in the line currency.
items[].lines[].estimatedTransactionPrice string (decimal) no The estimated transaction price used for the line in allocation, in the line currency.
items[].lines[].fairValueAmount string (decimal) no The fair value used for the line in allocation, in the line currency.
items[].lines[].variableConsideration string (decimal) no The variable consideration on the line, in the line currency.
items[].lines[].extendedSSP string (decimal) no The extended standalone selling price of the line, unit standalone selling price times quantity, in the line currency.
items[].lines[].revenueAmount string (decimal) no The revenue allocated to the line, in the line currency.
items[].lines[].revenueRecognized string (decimal) no The revenue recognized to date on the line, in the line currency.
items[].lines[].revenueRemaining string (decimal) no The revenue still to be recognized on the line, in the line currency.
items[].lines[].deferredRevenueAmount string (decimal) no The deferred revenue outstanding on the line, in the line currency.
items[].lines[].remainingPerformanceObligation string (decimal) no The remaining performance obligation on the line, in the line currency.
items[].lines[].unbilledReceivables string (decimal) no The unbilled receivables on the line, in the line currency.
items[].lines[].unscheduledRevenue string (decimal) no The revenue on the line not yet scheduled into a plan period, in the line currency.
items[].lines[].totalInvoicedAmount string (decimal) no The total invoiced against the line to date, in the line currency.
items[].lines[].oneTimeDiscountAllocationAmount string (decimal) no The one-time discount allocated to the line, in the line currency.
items[].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.
items[].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.
items[].lines[].revenuePlanHeader.id string yes The unique identifier for the revenue plan header.
items[].lines[].revenuePlanHeader.revenuePlanHeaderNumber string no The revenue plan header number.
items[].lines[].revenuePlanHeader.status string no The status of the plan. Possible values: 'notStarted', 'pendingRecognition', 'inProgress', 'complete', 'completeModified'.
items[].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'.
items[].lines[].revenuePlanHeader.amortizationMethod string no How the plan spreads its amount across periods. Possible values: 'exactDays', 'pointInTime', 'straightLineProRateFirstLast', 'straightLine', 'usageBased'.
items[].lines[].revenuePlanHeader.revenueSchedulingEvent string yes The event that starts recognition on the plan. Possible values: 'revenueArrangementCreation', 'uponInvoicing', 'uponUsageConsumption', 'manualRelease', 'uponInvoicingPercentInvoiced', 'uponInvoicingFullAmount', 'serviceActivation'.
items[].lines[].revenuePlanHeader.isContractClosed boolean yes Whether the contract behind the plan has been closed.
items[].lines[].revenuePlanHeader.revRecStartDate string (date) no The first day of the plan's recognition window. Format YYYY-MM-DD.
items[].lines[].revenuePlanHeader.revRecEndDate string (date) no The last day of the plan's recognition window, inclusive. Format YYYY-MM-DD.
items[].lines[].revenuePlanHeader.comments string no Free-form comments recorded on the plan.
items[].lines[].revenuePlanHeader.amount string (decimal) no The total amount the plan schedules, in the plan currency.
items[].lines[].revenuePlanHeader.totalRecognized string (decimal) no The total recognized across the plan's lines to date, in the plan currency.
items[].lines[].revenuePlanHeader.remainingDeferred string (decimal) no The amount still deferred on the plan, in the plan currency.
items[].lines[].revenuePlanHeader.returnedAmount string (decimal) no The amount returned against the plan, in the plan currency.
items[].lines[].revenuePlanHeader.unscheduledRevenue string (decimal) no The plan amount not yet scheduled into a period, in the plan currency.
items[].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.
items[].lines[].revenuePlanHeader.revenuePlanLines[].id string yes The unique identifier for the revenue plan line.
items[].lines[].revenuePlanHeader.revenuePlanLines[].lineId string no The line identifier within the plan.
items[].lines[].revenuePlanHeader.revenuePlanLines[].revenuePlanType string yes What the plan line schedules. Possible values: 'revenueRecognition', 'returnRevenueRecognition', 'unCommittedRevenueRecognition', 'modificationDeferredRevenueAdjustment', 'allowance', 'overage', 'usageExpiration', 'costOfRevenue', 'unholdRevenuePeriod', 'retrospectiveAdjustment'.
items[].lines[].revenuePlanHeader.revenuePlanLines[].currency string yes The currency the plan line is denominated in. Format ISO 4217, for example 'USD'.
items[].lines[].revenuePlanHeader.revenuePlanLines[].plannedPeriod string no The name of the accounting period this row is planned for.
items[].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.
items[].lines[].revenuePlanHeader.revenuePlanLines[].postingPeriod string no The name of the accounting period the row was posted in, when it differs from the planned one.
items[].lines[].revenuePlanHeader.revenuePlanLines[].isPosted boolean no Whether the row has been posted to the general ledger.
items[].lines[].revenuePlanHeader.revenuePlanLines[].holdStatus string no Whether revenue on the row is held back. Possible values: 'notHold', 'holdPlaced', 'holdRemoved'.
items[].lines[].revenuePlanHeader.revenuePlanLines[].releaseUnit string no The unit the release amount is expressed in. Possible values: 'quantity', 'percent', 'amount'.
items[].lines[].revenuePlanHeader.revenuePlanLines[].releaseAmount string (decimal) no The amount or quantity released in this period, in the unit given by releaseUnit.
items[].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.
items[].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.
items[].lines[].revenuePlanHeader.revenuePlanLines[].revenueAccount string no The name of the revenue account this row recognizes into.
items[].lines[].revenuePlanHeader.revenuePlanLines[].deferredRevenueAccount string no The name of the deferred-revenue account this row releases from.
items[].lines[].revenuePlanHeader.revenuePlanLines[].journalEntry string no The number of the journal entry this row posted through, once posted.
items[].lines[].revenuePlanHeader.revenuePlanLines[].amount string (decimal) no The amount scheduled for this period, in the plan line currency.
items[].lines[].revenuePlanHeader.revenuePlanLines[].revenueAmount string (decimal) no The revenue scheduled for this period, in the plan line currency.
items[].lines[].revenuePlanHeader.revenuePlanLines[].revenueRecognized string (decimal) no The revenue recognized in this period, in the plan line currency.
items[].lines[].revenuePlanHeader.revenuePlanLines[].cumulativeRecognition string (decimal) no The revenue recognized cumulatively through this period, in the plan line currency.
items[].lines[].revenuePlanHeader.revenuePlanLines[].unscheduledRevenue string (decimal) no The amount on this row not yet scheduled, in the plan line currency.
items[].lines[].revenuePlanHeader.revenuePlanLines[].postedAmount string (decimal) no The amount actually posted to the ledger for this row, in the plan line currency.
items[].lastModifiedDate string (date-time) yes The date and time the revenue contract last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
pagination object yes The pagination cursor for this page.
pagination.nextCursor string no The cursor for the next page. Pass it as page.cursor. Absent on the last page.
pagination.hasMore boolean yes True when more revenue contracts remain beyond this page.

Statuses