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

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:

{
  "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