Search pricing headers

Operation ID: searchAccountingPricing

Group: Accounting › Products › Product Lines

Open in the interactive reference

POST /accounting/pricing/search

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Searches pricing headers.

Parameters

Name In Type Required Description
Api-Version header string · 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 The filters to apply. A pricing header must match every filter you send. Omit to return all pricing headers.
filters.term string no Limits results to pricing headers whose price book name, product line name, or header number contains this text. The match is case-insensitive.
filters.headerNumber string no Limits results to the pricing header with this header number. The match is exact.
filters.productLineId string no Limits results to pricing headers of this product line. See id on GET accounting/product-lines/:id.
filters.productId string no Limits results to pricing headers of any product line of this product. See id on GET accounting/products/:id.
filters.priceBookId string no Limits results to pricing headers in this price book. See id on GET accounting/price-books/:id.
filters.currency string no Limits results to pricing headers in this currency. Format ISO 4217, for example 'USD'. The match is exact.
filters.dataSource string no Limits results to pricing headers from this source system or import job. The match is exact. Example: 'Salesforce'.
filters.hasBeenUsed boolean no Limits results to pricing headers that at least one sales order line uses (true) or that no sales order line uses (false).
filters.validFrom object no Limits results by the first date the header's prices are effective. Bounds are inclusive.
filters.validFrom.start string no The inclusive lower bound. Use format YYYY-MM-DD.
filters.validFrom.end string no The inclusive upper bound. Use format YYYY-MM-DD.
filters.validTo object no Limits results by the last date the header's prices are effective. Bounds are inclusive. A header with no end date never matches.
filters.validTo.start string no The inclusive lower bound. Use format YYYY-MM-DD.
filters.validTo.end string no The inclusive upper bound. Use format YYYY-MM-DD.
filters.createdDate object no Limits results by the date and time the pricing header was created. Bounds are inclusive.
filters.createdDate.start string no The inclusive lower bound, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
filters.createdDate.end string no The inclusive upper bound, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
filters.lastModifiedDate object no Limits results by the date and time the pricing header last changed. Bounds are inclusive.
filters.lastModifiedDate.start string no The inclusive lower bound, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
filters.lastModifiedDate.end string no The inclusive upper bound, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
filters.externalIdentifier object no Limits results to pricing headers with a price book entry that has this external identifier. Send both fieldName and value.
filters.externalIdentifier.fieldName string yes The configured field name of the external identifier, not its display label. A name that is not configured for price book entries fails with UNKNOWN_EXTERNAL_IDENTIFIER.
filters.externalIdentifier.value string yes The identifier's value in the source system. The match is exact and case-sensitive.
page object no The 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 pricing headers per page. Defaults to 50. A value above 200 is treated as 200, not rejected. 
{
  "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<object> yes The pricing headers on this page. An empty array when nothing matches.
items[].id string yes The unique identifier for the pricing header.
items[].headerNumber string no The pricing header number, assigned by the system and unique within the tenant. Absent while none has been assigned.
items[].productLineId string yes The product line this pricing header prices. See id on GET accounting/product-lines/:id.
items[].productLineName string no The name of the product line. See name on GET accounting/product-lines/:id.
items[].productLineNumber string no The product line number. See productLineNumber on GET accounting/product-lines/:id.
items[].productId string no The product the product line belongs to. See id on GET accounting/products/:id.
items[].productName string no The display name of the product. See productName on GET accounting/products/:id.
items[].priceBookId string yes The price book this header belongs to. See id on GET accounting/price-books/:id.
items[].priceBookName string no The display name of the price book. See priceBookName on GET accounting/price-books/:id.
items[].currency string yes The currency the header's prices are in. Format ISO 4217, for example 'USD'.
items[].validFrom date yes The first date the header's prices are effective, inclusive. Format YYYY-MM-DD.
items[].validTo date no The last date the header's prices are effective, inclusive. Format YYYY-MM-DD. Absent for a header with no end date.
items[].dataSource string no The source system or import job that produced the pricing header. Examples: 'Salesforce', 'NetSuite', 'Stripe'.
items[].hasBeenUsed boolean no Whether at least one sales order line uses this pricing header.
items[].createdDate date-time no The date and time the pricing header was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].lastModifiedDate date-time yes The date and time the pricing header last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].priceBookEntries array<object> yes The price book entries of the pricing header. For a product line priced 'tiered', 'volume', 'stairstep', or 'thresholdBased', each entry is one tier: a quantity range with its own price. A 'flat' or 'perUnit' line has one entry, and a 'rateCard' line has one entry per rate-card entry. An empty array when the header has none.
items[].priceBookEntries[].id string yes The unique identifier for the price book entry.
items[].priceBookEntries[].priceBookEntryNumber string no The price book entry number, assigned by the system.
items[].priceBookEntries[].listPrice decimal no The list price, in the header currency. On a rate-card entry, the list price is the rate.
items[].priceBookEntries[].fromQuantity decimal no The lowest quantity in the tier, inclusive. Used only when the product line is priced 'tiered', 'volume', 'stairstep', or 'thresholdBased'.
items[].priceBookEntries[].toQuantity decimal no The highest quantity in the tier, inclusive. Absent on the top tier, which has no upper limit.
items[].priceBookEntries[].priceModel string no How the tier prices its quantity. Possible values: 'flat', 'perUnit', 'tiered', 'volume', 'stairstep', 'rateCard', 'thresholdBased'.
items[].priceBookEntries[].rateCardEntry object no The rate-card entry attached to this price book entry. Absent when the entry is not rate-card priced.
items[].priceBookEntries[].rateCardEntry.id string yes The unique identifier for the rate-card entry.
items[].priceBookEntries[].rateCardEntry.billableComponentId string no The unique identifier of the billable component this rate-card entry prices. No endpoint returns billable components.
items[].priceBookEntries[].rateCardEntry.unitOfMeasure string yes The unit the rate is quoted 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[].priceBookEntries[].rateCardEntry.description string no A description of the rate-card entry. The description distinguishes the entry from other rate-card entries on the same billable component.
items[].priceBookEntries[].rateCardEntry.usageType string no How usage is measured against this entry. Possible values: 'consumption', 'overage', 'thresholdCounter', 'payg'.
items[].priceBookEntries[].rateCardEntry.billableUnitOfMeasure string no The unit used when billing this entry. 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[].priceBookEntries[].rateCardEntry.conversion decimal no The multiplier that converts unitOfMeasure quantities into billableUnitOfMeasure quantities.
items[].priceBookEntries[].rateCardEntry.invoiceFrequency string no How often usage on this entry is invoiced. Possible values: 'monthly', 'biMonthly', 'quarterly', 'semiAnnually', 'annually', 'once', 'custom', 'template', 'milestone', 'allAtOnce', 'termEnd'.
items[].priceBookEntries[].rateCardEntry.priceModel string no How the rate-card entry's price is calculated. Possible values: 'flat', 'perUnit', 'tiered', 'volume', 'stairstep', 'rateCard', 'thresholdBased'. Absent when no price model was set on the rate-card entry.
items[].priceBookEntries[].externalIdentifiers array<object> no External identifiers owned by other systems, at most one per fieldName. Absent when the price book entry has none.
items[].priceBookEntries[].externalIdentifiers[].fieldName string yes The configured field name of the external identifier, not its display label.
items[].priceBookEntries[].externalIdentifiers[].value string yes The identifier's value in the source system.
items[].priceBookEntries[].externalIdentifiers[].externalUrl string no An absolute http or https link to the object in the source system. Absent when none is set.
pagination object yes The pagination information 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 pricing headers remain beyond this page. 
{
  "data": {
    "items": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "headerNumber": "<headerNumber>",
        "productLineId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "productLineName": "<productLineName>",
        "productLineNumber": "<productLineNumber>",
        "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "productName": "<productName>",
        "priceBookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "priceBookName": "<priceBookName>",
        "currency": "<currency>",
        "validFrom": "2026-01-15",
        "validTo": "2026-01-15",
        "dataSource": "<dataSource>",
        "hasBeenUsed": true,
        "createdDate": "2026-01-15T09:30:00.000Z",
        "lastModifiedDate": "2026-01-15T09:30:00.000Z",
        "priceBookEntries": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "priceBookEntryNumber": "<priceBookEntryNumber>",
            "listPrice": "19.99",
            "fromQuantity": "19.99",
            "toQuantity": "19.99",
            "priceModel": "<priceModel>",
            "rateCardEntry": {
              "id": null,
              "billableComponentId": null,
              "unitOfMeasure": null,
              "description": null,
              "usageType": null,
              "billableUnitOfMeasure": null,
              "conversion": null,
              "invoiceFrequency": null,
              "priceModel": null
            },
            "externalIdentifiers": [
              null
            ]
          }
        ]
      }
    ],
    "pagination": {
      "nextCursor": "<nextCursor>",
      "hasMore": true
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Errors

Code Status
INVALID_DATE 400
INVALID_TIMESTAMP 400
UNKNOWN_EXTERNAL_IDENTIFIER 400

Statuses