# Search Accounting Pricing

`POST /accounting/pricing/search`

Group: Accounting › Products › Product Lines · Operation ID: `searchAccountingPricing`

Search pricing headers by free text (price book name, product line name, header 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 entries, rate cards and entry 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](https://docs.api.lensing.ai/?op=searchAccountingPricing)

## 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`: searchAccountingPricingInput.

| 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 pricing headers. |
| `filters.term` | string | no | Case-insensitive SUBSTRING match against the price book name, the product line name and the header number. |
| `filters.headerNumber` | string | no | Exact match on the system-generated header number. |
| `filters.productLineId` | string | no | Restrict to headers of this product line (a UUID). An id that matches nothing yields an empty page, not an error. |
| `filters.productId` | string | no | Restrict to headers of any line of this product (a UUID). An id that matches nothing yields an empty page. |
| `filters.priceBookId` | string | no | Restrict to headers in this price book (a UUID). An id that matches nothing yields an empty page. |
| `filters.currency` | string | no | Exact match on the ISO 4217 currency code. |
| `filters.dataSource` | string | no | Exact match on the upstream system or import job that produced the header, e.g. 'Salesforce'. |
| `filters.hasBeenUsed` | boolean | no | Restrict to headers that have (or have not) priced a sales order line. |
| `filters.validFrom` | object | no | Filter by effective start date. Bounds are inclusive. |
| `filters.validFrom.start` | string | no | Inclusive lower bound (YYYY-MM-DD). |
| `filters.validFrom.end` | string | no | Inclusive upper bound (YYYY-MM-DD). |
| `filters.validTo` | object | no | Filter by effective end date. Bounds are inclusive; an open-ended header has no end date and never matches this filter. |
| `filters.validTo.start` | string | no | Inclusive lower bound (YYYY-MM-DD). |
| `filters.validTo.end` | string | no | Inclusive upper bound (YYYY-MM-DD). |
| `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 headers owning a price-book entry that carries this identifier from another system. Both members are required. Not unique across entries, 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 PriceBookEntryExternalIdentifierConfiguration 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 pricing headers to return. Defaults to 50, capped at 200; the server may return fewer, but never more. |

Example:

```json
{
  "filters": {
    "term": "<term>",
    "headerNumber": "<headerNumber>",
    "productLineId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "priceBookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "currency": "<currency>",
    "dataSource": "<dataSource>",
    "hasBeenUsed": true,
    "validFrom": {
      "start": "<start>",
      "end": "<end>"
    },
    "validTo": {
      "start": "<start>",
      "end": "<end>"
    },
    "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` (searchAccountingPricingOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | Matching pricing headers for this page. Empty when nothing matches. |
| `items[].id` | string | yes | Id of the pricing header (a UUID) — the public identifier of this record. |
| `items[].headerNumber` | string | no | System-generated pricing header number. Absent until one has been assigned. |
| `items[].productLineId` | string | yes | Id of the product line this header prices (a UUID) — GET accounting/product-lines/:id. |
| `items[].productLineName` | string | no | Display name of that product line. |
| `items[].productLineNumber` | string | no | System-generated number of that product line. |
| `items[].productId` | string | no | Id of the product the line belongs to (a UUID) — GET accounting/products/:id. |
| `items[].productName` | string | no | Display name of that product. |
| `items[].priceBookId` | string | yes | Id of the price book this header belongs to (a UUID) — GET accounting/price-books/:id. |
| `items[].priceBookName` | string | no | Name of that price book. |
| `items[].currency` | string | yes | ISO 4217 currency code governing every amount in this header. |
| `items[].validFrom` | string (date) | yes | First date the header's prices are effective (YYYY-MM-DD, inclusive). |
| `items[].validTo` | string (date) | no | Last effective date (YYYY-MM-DD, inclusive). Absent when open-ended. |
| `items[].dataSource` | string | no | Upstream system or import job that produced this header, e.g. 'Everest', 'Salesforce'. Tenant-configurable, not exhaustively enumerable. |
| `items[].hasBeenUsed` | boolean | no | True once the header has priced at least one sales order line. Computed; never settable. |
| `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[].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. Empty when the header has none. |
| `items[].priceBookEntries[].id` | string | yes | Id of the entry (a UUID). |
| `items[].priceBookEntries[].priceBookEntryNumber` | string | no | System-generated entry number. |
| `items[].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[].priceBookEntries[].fromQuantity` | string (decimal) | no | Inclusive lower bound of this tier's quantity range. Tiered models only. |
| `items[].priceBookEntries[].toQuantity` | string (decimal) | no | Inclusive upper bound of this tier's quantity range. Absent on the open-ended top tier. |
| `items[].priceBookEntries[].priceModel` | string | no | How this tier prices quantity. One of 'flat', 'perUnit', 'tiered', 'volume', 'stairstep', 'rateCard', 'thresholdBased'. Tiered and rate-card models only. |
| `items[].priceBookEntries[].rateCardEntry` | object | no | Rate card priced by this entry. Rate-card pricing only. |
| `items[].priceBookEntries[].rateCardEntry.id` | string | yes | Id of the rate-card entry (a UUID). |
| `items[].priceBookEntries[].rateCardEntry.billableComponentId` | string | no | Id of the billable component this rate prices (a UUID). |
| `items[].priceBookEntries[].rateCardEntry.unitOfMeasure` | string | yes | Unit of measure of the rate card. 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[].priceBookEntries[].rateCardEntry.description` | string | no | Rate-card description. |
| `items[].priceBookEntries[].rateCardEntry.usageType` | string | no | Usage type the rate applies to. One of 'consumption', 'overage', 'thresholdCounter', 'payg'. |
| `items[].priceBookEntries[].rateCardEntry.billableUnitOfMeasure` | string | no | Unit of measure the usage is billed in, when it differs from unitOfMeasure. |
| `items[].priceBookEntries[].rateCardEntry.conversion` | string (decimal) | no | Conversion factor from unitOfMeasure to billableUnitOfMeasure. A quantity, not an amount. |
| `items[].priceBookEntries[].rateCardEntry.invoiceFrequency` | string | no | Invoice frequency of the rate card, when it differs from the line. One of 'monthly', 'biMonthly', 'quarterly', 'semiAnnually', 'annually', 'once', 'custom', 'template', 'milestone', 'allAtOnce', 'termEnd'. |
| `items[].priceBookEntries[].rateCardEntry.priceModel` | string | no | Price model of the rate card, when it differs from the line. One of 'flat', 'perUnit', 'tiered', 'volume', 'stairstep', 'rateCard', 'thresholdBased'. |
| `items[].priceBookEntries[].externalIdentifiers` | array of object | no | External identifiers owned by other systems for this entry. At most one entry per fieldName. Absent when it has none. |
| `items[].priceBookEntries[].externalIdentifiers[].fieldName` | string | yes | Configured key of the external identifier — a stable camelCase slug, not the human-readable label. |
| `items[].priceBookEntries[].externalIdentifiers[].value` | string | yes | The identifier as the source system holds it. |
| `items[].priceBookEntries[].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_DATE` | 400 |
| `INVALID_TIMESTAMP` | 400 |
| `UNKNOWN_EXTERNAL_IDENTIFIER` | 400 |

## Statuses

- `400` — Invalid request or business failure. Codes: INVALID_DATE, INVALID_TIMESTAMP, UNKNOWN_EXTERNAL_IDENTIFIER
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests
- `500` — Internal server error