Search Accounting Product Lines

POST /accounting/product-lines/search

Group: Accounting › Products › Product Lines · Operation ID: searchAccountingProductLines

Search product lines by free text (name, product line number) plus structured filters, and page through the matches. POST so term and identifiers travel in the JSON body rather than the URL. Read-only. Returns the full record for each match, including tax records, pricing and external identifiers; matching nothing is an empty items array with HTTP 200, not a 404. Every request must carry the Api-Version header.

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: searchAccountingProductLinesInput.

Field Type Required Description
filters object no Search filters, nested as one object so they map onto the POST body. All are optional and are ANDed; omit the whole object to match all product lines.
filters.term string no Case-insensitive SUBSTRING match against name and productLineNumber.
filters.productId string no Restrict to lines of this product (a UUID). An id that matches no product yields an empty page, not an error.
filters.productLineNumber string no Exact match on the system-generated product line number.
filters.crmProductId string no Exact match on the CRM system's own identifier for the line.
filters.lineType string no Restrict to this line type. One of 'recurring', 'oneTime', 'commitWithOverage', 'payAsYouGo', 'usage', 'prepaid', 'billableTime', 'billableTravelExpense', 'billablePassThrough'.
filters.priceModel string no Restrict to this price model. One of 'flat', 'perUnit', 'tiered', 'volume', 'stairstep', 'rateCard', 'thresholdBased'.
filters.pricingTerm string no Restrict to this pricing term. One of 'monthly', 'biMonthly', 'once', 'quarterly', 'semiAnnually', 'annually'.
filters.invoiceFrequency string no Restrict to this invoice frequency. One of 'monthly', 'biMonthly', 'quarterly', 'semiAnnually', 'annually', 'once', 'custom', 'template', 'milestone', 'allAtOnce', 'termEnd'.
filters.unitOfMeasure string no Restrict to this unit of measure, e.g. 'user', 'seat', 'hour'.
filters.taxMode string no Restrict to this tax mode. One of 'TaxInclusive', 'TaxExclusive'.
filters.enforceListPrice boolean no Restrict to lines that do (or do not) enforce the list price.
filters.hasUsage boolean no Restrict to Prepaid lines with (or without) a paired Usage line.
filters.parentProductLineId string no Restrict to the Usage line(s) paired with this Prepaid product line (a UUID). An id that matches nothing yields an empty page.
filters.dataSource string no Exact match on the upstream system or import job that produced the line, e.g. 'Salesforce'.
filters.createdDate object no Filter by creation instant. Bounds are inclusive.
filters.createdDate.start string no Inclusive lower bound (ISO 8601 UTC, YYYY-MM-DDTHH:mm:ss.sssZ).
filters.createdDate.end string no Inclusive upper bound (ISO 8601 UTC, YYYY-MM-DDTHH:mm:ss.sssZ).
filters.lastModifiedDate object no Filter by last-changed instant. Bounds are inclusive.
filters.lastModifiedDate.start string no Inclusive lower bound (ISO 8601 UTC, YYYY-MM-DDTHH:mm:ss.sssZ).
filters.lastModifiedDate.end string no Inclusive upper bound (ISO 8601 UTC, YYYY-MM-DDTHH:mm:ss.sssZ).
filters.externalIdentifier object no Match one identifier owned by another system. Both members are required. Not unique across lines, so this returns the ordinary items array.
filters.externalIdentifier.fieldName string yes Configured key of the external identifier — a stable camelCase slug, not the human-readable label. Must match an active ProductLineExternalIdentifierConfiguration or the call fails with UNKNOWN_EXTERNAL_IDENTIFIER.
filters.externalIdentifier.value string yes The identifier as the source system holds it. Matched exactly, case-sensitively.
page object no Pagination controls. Omit for the first page.
page.cursor string no Opaque forward cursor from a previous response's pagination.nextCursor; omit for the first page. Do not construct manually.
page.size number no Maximum number of product lines to return. Defaults to 50, capped at 200; the server may return fewer, but never more.

Example:

{
  "filters": {
    "term": "<term>",
    "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "productLineNumber": "<productLineNumber>",
    "crmProductId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "lineType": "<lineType>",
    "priceModel": "<priceModel>",
    "pricingTerm": "<pricingTerm>",
    "invoiceFrequency": "<invoiceFrequency>",
    "unitOfMeasure": "<unitOfMeasure>",
    "taxMode": "<taxMode>",
    "enforceListPrice": true,
    "hasUsage": true,
    "parentProductLineId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "dataSource": "<dataSource>",
    "createdDate": {
      "start": "<start>",
      "end": "<end>"
    },
    "lastModifiedDate": {
      "start": "<start>",
      "end": "<end>"
    },
    "externalIdentifier": {
      "fieldName": "<fieldName>",
      "value": "<value>"
    }
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}

Response

200 Success

Under data (searchAccountingProductLinesOutput):

Field Type Required Description
items array of object yes Matching product lines for this page. Empty when nothing matches.
items[].id string yes Id of the product line (a UUID) — the public identifier of this record.
items[].productId string yes Id of the parent product (a UUID) — GET accounting/products/:id.
items[].productName string no Display name of the parent product.
items[].productLineNumber string no System-generated product line number, unique per tenant. Absent until one has been assigned.
items[].name string yes Product line display name.
items[].lineType string no Line type. One of 'recurring', 'oneTime', 'commitWithOverage', 'payAsYouGo', 'usage', 'prepaid', 'billableTime', 'billableTravelExpense', 'billablePassThrough'.
items[].priceModel string no Price model. One of 'flat', 'perUnit', 'tiered', 'volume', 'stairstep', 'rateCard', 'thresholdBased'.
items[].pricingTerm string no Pricing term. One of 'monthly', 'biMonthly', 'once', 'quarterly', 'semiAnnually', 'annually'.
items[].invoiceFrequency string no Invoice frequency. One of 'monthly', 'biMonthly', 'quarterly', 'semiAnnually', 'annually', 'once', 'custom', 'template', 'milestone', 'allAtOnce', 'termEnd'.
items[].unitOfMeasure string no Unit of measure quantities are tracked in. One of '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[].taxMode string no Tax mode. One of 'TaxInclusive', 'TaxExclusive' (PascalCase members).
items[].enforceListPrice boolean no When true, sales transactions on this line cannot override the list price.
items[].hasUsage boolean no True when this Prepaid line has a paired Usage line.
items[].hasBeenUsed boolean no True once the line has been sold on at least one sales order. Computed; never settable.
items[].commitInvoicing string no Invoice timing of a commit line. One of 'advance', 'arrears'. Absent on other line types.
items[].prepaidBalanceOverConsumptionBehavior string no What happens when usage exceeds the prepaid balance. One of 'allowNegative', 'overage'. Prepaid lines only.
items[].prepaidBalanceRolloverAtRenewal boolean no Whether the remaining prepaid balance rolls over at renewal. Prepaid lines only.
items[].parentProductLineId string no Id of the parent Prepaid product line (a UUID) when this is its paired Usage line.
items[].crmProductId string no CRM system's own identifier for this product line, when integrated from one.
items[].dataSource string no Upstream system or import job that produced this line, e.g. 'Everest', 'Salesforce'. Tenant-configurable, not exhaustively enumerable.
items[].createdDate string (date-time) no Instant the record was created, as ISO 8601 UTC (YYYY-MM-DDTHH:mm:ss.sssZ), when recorded.
items[].lastModifiedDate string (date-time) yes Instant the record last changed, as ISO 8601 UTC (YYYY-MM-DDTHH:mm:ss.sssZ). Poll on this to sync incrementally.
items[].productLineTaxes array of object no Tax records attached to this line. Absent when it has none.
items[].productLineTaxes[].id string yes Id of the tax record (a UUID).
items[].productLineTaxes[].taxCode string yes Tax code as defined by the configured tax provider.
items[].productLineTaxes[].engine string yes Tax engine. One of 'avalara', 'anrok', 'everestTaxEngine', 'manualTax', 'none'.
items[].productLineTaxes[].country string no ISO 3166-1 country code the record applies in.
items[].productLineTaxes[].entityId string no Id of the legal entity the record applies under (a UUID).
items[].pricingHeaders array of object no Pricing headers of this line, each with its price-book entries. Absent when the line has no pricing. Amounts are in the header's currency.
items[].pricingHeaders[].id string yes Id of the pricing header (a UUID) — the :pricingId of the pricing routes.
items[].pricingHeaders[].headerNumber string no System-generated header number.
items[].pricingHeaders[].priceBookId string no Id of the price book this header belongs to (a UUID).
items[].pricingHeaders[].priceBookName string no Name of that price book.
items[].pricingHeaders[].currency string yes ISO 4217 currency code governing every amount in this header.
items[].pricingHeaders[].validFrom string (date) yes First date the header's prices are effective (YYYY-MM-DD, inclusive).
items[].pricingHeaders[].validTo string (date) no Last effective date (YYYY-MM-DD, inclusive). Absent when open-ended.
items[].pricingHeaders[].priceBookEntries array of object yes Price-book entries of the header: one for flat pricing, one per tier for tiered models, one per rate card for rate-card pricing.
items[].pricingHeaders[].priceBookEntries[].id string yes Id of the entry (a UUID).
items[].pricingHeaders[].priceBookEntries[].priceBookEntryNumber string no System-generated entry number.
items[].pricingHeaders[].priceBookEntries[].listPrice string (decimal) no List price, or the rate for a rate-card entry, as a decimal in the header currency (see currency).
items[].pricingHeaders[].priceBookEntries[].fromQuantity string (decimal) no Inclusive lower bound of this tier's quantity range. Tiered models only.
items[].pricingHeaders[].priceBookEntries[].toQuantity string (decimal) no Inclusive upper bound of this tier's quantity range. Absent on the open-ended top tier.
items[].pricingHeaders[].priceBookEntries[].priceModel string no How this tier prices quantity. One of 'flat', 'perUnit'. Tiered models only.
items[].pricingHeaders[].priceBookEntries[].rateCardEntry object no Rate card priced by this entry. Rate-card pricing only.
items[].pricingHeaders[].priceBookEntries[].rateCardEntry.id string yes Id of the rate-card entry (a UUID).
items[].pricingHeaders[].priceBookEntries[].rateCardEntry.billableComponentId string no Id of the billable component this rate prices (a UUID).
items[].pricingHeaders[].priceBookEntries[].rateCardEntry.unitOfMeasure string yes Unit of measure of the rate card.
items[].pricingHeaders[].priceBookEntries[].rateCardEntry.description string no Rate-card description.
items[].pricingHeaders[].priceBookEntries[].rateCardEntry.usageType string no Usage type the rate applies to.
items[].pricingHeaders[].priceBookEntries[].rateCardEntry.billableUnitOfMeasure string no Unit of measure the usage is billed in, when it differs from unitOfMeasure.
items[].pricingHeaders[].priceBookEntries[].rateCardEntry.conversion string (decimal) no Conversion factor from unitOfMeasure to billableUnitOfMeasure. A quantity, not an amount.
items[].pricingHeaders[].priceBookEntries[].rateCardEntry.invoiceFrequency string no Invoice frequency of the rate card, when it differs from the line.
items[].pricingHeaders[].priceBookEntries[].rateCardEntry.priceModel string no Price model of the rate card, when it differs from the line.
items[].externalIdentifiers array of object no External identifiers owned by other systems. At most one entry per fieldName. Absent when the line has none.
items[].externalIdentifiers[].fieldName string yes Configured key of the external identifier — a stable camelCase slug, not the human-readable label.
items[].externalIdentifiers[].value string yes The identifier as the source system holds it.
items[].externalIdentifiers[].externalUrl string no Absolute http(s) link to the object in the originating system, when one is stored.
pagination object yes Pagination cursor for this page.
pagination.nextCursor string no Opaque cursor to pass as page.cursor for the next page; absent on the last page.
pagination.hasMore boolean yes True when more matches remain beyond this page.

Errors

Code Status
INVALID_TIMESTAMP 400
UNKNOWN_EXTERNAL_IDENTIFIER 400

Statuses