CRM API | Price books - HubSpot docs

Supported products

Scope requirements

Use the CRM price books API to retrieve price book and price book item records using standard CRM object patterns, including list, individual read, batch read, and search. This API is read-only. To create, update, activate, or delete price books and their items, use the price books API.

Retrieve price books

You can retrieve price book records individually, as a list, or in batches. Use the following optional query parameters in list and individual read requests:

Parameter	Description
`properties`	A comma-separated list of property names to include in the response. Properties not present on the object will be ignored.
`propertiesWithHistory`	A comma-separated list of properties to return along with their historical values.
`associations`	A comma-separated list of object types to retrieve associated IDs for. Non-existent associations will be ignored.
`archived`	Set to `true` to return only archived records. Defaults to `false`.

Retrieve all price books

To retrieve a list of all price books, make a GET request to /crm/objects/2026-09-beta/price_books. By default, the endpoint returns up to 10 records per page. Use the limit query parameter to adjust the page size, and the after parameter (from the previous response’s paging.next.after field) to retrieve the next page.

{
  "results": [
    {
      "id": "418966139535",
      "properties": {
        "hs_createdate": "2026-06-10T20:06:04.685Z",
        "hs_lastmodifieddate": "2026-06-10T20:22:31.600Z",
        "hs_object_id": "418966139535"
      },
      "createdAt": "2026-06-10T20:06:04.685Z",
      "updatedAt": "2026-06-10T20:22:31.600Z",
      "archived": false
    }
  ],
  "paging": {
    "next": {
      "after": "418966139536"
    }
  }
}

To retrieve specific properties, include a properties query parameter in the request URL with a comma-separated list of property names. To view all available price book properties, use the properties API.

Retrieve an individual price book

To retrieve a single price book by its record ID, make a GET request to /crm/objects/2026-09-beta/price_books/{objectId}.

{
  "id": "418966139535",
  "properties": {
    "hs_createdate": "2026-06-10T20:06:04.685Z",
    "hs_lastmodifieddate": "2026-06-10T20:22:31.600Z",
    "hs_object_id": "418966139535"
  },
  "createdAt": "2026-06-10T20:06:04.685Z",
  "updatedAt": "2026-06-10T20:22:31.600Z",
  "archived": false
}

The record ID (id) returned here matches the id returned by the price books API when creating or retrieving price books via the commerce endpoints.

Retrieve a batch of price books

To retrieve multiple price books in a single request, make a POST request to /crm/objects/2026-09-beta/price_books/batch/read.

Please note: the batch read endpoint cannot retrieve associations. To retrieve associations for a specific set of price books, first retrieve their id values, then use the associations API.

In the request body, include an inputs array of record IDs and a properties array specifying which properties to return:

{
  "properties": ["hs_createdate", "hs_lastmodifieddate"],
  "inputs": [
    { "id": "418966139535" },
    { "id": "418966139536" }
  ]
}

Parameter	Description
`inputs`	An array of objects, each containing an `id` field with the record ID of the price book to retrieve.
`properties`	An array of property names to return for each record.
`propertiesWithHistory`	An array of property names to return along with their historical values.
`idProperty`	The name of a unique identifier property to use instead of the default record ID.

Retrieve price book items

Price book items (the products configured within a price book) are also accessible as CRM objects. You can retrieve them using the same list, individual read, batch read, and search patterns, substituting price_book_items as the objectType.

Retrieve all price book items

To retrieve a list of all price book items, make a GET request to /crm/objects/2026-09-beta/price_book_items.

Retrieve an individual price book item

To retrieve a single price book item by its record ID, make a GET request to /crm/objects/2026-09-beta/price_book_items/{objectId}. The record ID matches the id returned by the price book items endpoints in the commerce API.

Retrieve a batch of price book items

To retrieve multiple price book items in a single request, make a POST request to /crm/objects/2026-09-beta/price_book_items/batch/read.

{
  "properties": ["hs_createdate", "hs_lastmodifieddate"],
  "inputs": [
    { "id": "418968256821" },
    { "id": "418968256822" }
  ]
}

Search price books and items

Use the search endpoint to retrieve price books or price book items that match a set of filter criteria. Make a POST request to /crm/objects/2026-09-beta/price_books/search (or /crm/objects/2026-09-beta/price_book_items/search for items). In the request body, include a filterGroups array to define your search criteria, a properties array to specify which fields to return, and optional sorts and limit parameters. For example, to search for price books modified after a specific date:

{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "hs_lastmodifieddate",
          "operator": "GT",
          "value": "2026-01-01T00:00:00.000Z"
        }
      ]
    }
  ],
  "properties": ["hs_createdate", "hs_lastmodifieddate"],
  "limit": 10
}

Parameter	Description
`filterGroups`	An array of filter groups. Filters within a group are combined with AND logic; multiple groups are combined with OR logic.
`properties`	An array of property names to return in the response.
`sorts`	An array of property names to sort by. Prefix with `-` for descending order.
`limit`	The maximum number of results to return per page.
`after`	A cursor token from a previous response to retrieve the next page of results.

Learn more about searching the CRM including available filter operators.

​Retrieve price books

​Retrieve all price books

​Retrieve an individual price book

​Retrieve a batch of price books

​Retrieve price book items

​Retrieve all price book items

​Retrieve an individual price book item

​Retrieve a batch of price book items

​Search price books and items

Retrieve price books

Retrieve all price books

Retrieve an individual price book

Retrieve a batch of price books

Retrieve price book items

Retrieve all price book items

Retrieve an individual price book item

Retrieve a batch of price book items

Search price books and items