> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---
id: edf6d982-19bc-4ea3-94ae-d5b74aa53be2
---

# CRM API | Price books

> Retrieve price book and price book item records as CRM objects.

export const BetaDisclaimerBanner = () => <Warning>
        This functionality is currently in beta. By participating in this beta, you agree to HubSpot's <a href="https://legal.hubspot.com/developer-terms">Developer Terms</a> and <a href="https://legal.hubspot.com/developerbetaterms">Developer Beta Terms</a>. Note that the functionality is still under active development and is subject to change based on testing and feedback.
    </Warning>;

export const SupportedProducts = ({marketing, sales, service, cms, data, commerce, crm, marketingLevel, salesLevel, serviceLevel, cmsLevel, dataLevel, commerceLevel, crmLevel}) => {
  const translations = {
    description: "Requires one of the following products or higher.",
    productNames: {
      marketing: "Marketing Hub",
      sales: "Sales Hub",
      service: "Service Hub",
      cms: "Content Hub",
      data: "Data Hub",
      commerce: "Revenue Hub",
      crm: "Smart CRM"
    },
    tiers: {
      free: "Free",
      starter: "Starter",
      professional: "Professional",
      enterprise: "Enterprise"
    }
  };
  const translateTier = tier => {
    if (!tier) return '';
    const lowerTier = tier.toLowerCase();
    return translations.tiers[lowerTier] || tier;
  };
  const products = [{
    name: marketing ? translations.productNames.marketing : '',
    level: translateTier(marketingLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/marketing-bolt.svg",
    alt: "Marketing Hub"
  }, {
    name: sales ? translations.productNames.sales : '',
    level: translateTier(salesLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/sales-star.svg",
    alt: "Sales Hub"
  }, {
    name: service ? translations.productNames.service : '',
    level: translateTier(serviceLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/service-heart.svg",
    alt: "Service Hub"
  }, {
    name: cms ? translations.productNames.cms : '',
    level: translateTier(cmsLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/content-play.svg",
    alt: "Content Hub"
  }, {
    name: data ? translations.productNames.data : '',
    level: translateTier(dataLevel),
    icon: "https://developers.hubspot.com/hubfs/Knowledge_Base_2023-24-25/subscription_key_icons/operations_icon.svg",
    alt: "Data Hub"
  }, {
    name: commerce ? translations.productNames.commerce : '',
    level: translateTier(commerceLevel),
    icon: "https://developers.hubspot.com/hubfs/Knowledge_Base/subscription_key_icons/commerce_icon.svg",
    alt: "Revenue Hub"
  }, {
    name: crm ? translations.productNames.crm : '',
    level: translateTier(crmLevel),
    icon: "https://developer.hubspot.com/hubfs/Knowledge_Base_2023-24-25/developer/icons/SmartCRM.svg",
    alt: "Smart CRM"
  }].filter(product => product.name && product.level);
  if (products.length === 0) return null;
  return <div>
      <div className="text-sm mb-2">{translations.description}</div>
      <div className={`grid ${products.length === 1 ? 'grid-cols-1' : 'grid-cols-2'} gap-1.5`}>
        {products.map((product, index) => <div key={index} style={{
    display: 'flex',
    alignItems: 'center'
  }}>
            <img src={product.icon} alt={product.alt} className="w-3.5 h-3.5 mr-1.5 mt-2.5 mb-2.5 flex-shrink-0 align-middle" />
            <span className="font-medium mr-1 text-sm">{product.name} -</span>
            <span className="text-sm">{product.level}</span>
          </div>)}
      </div>
    </div>;
};

export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
  if (!scopes || scopes.length === 0) {
    return null;
  }
  const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
  return <div>
      <div className="text-sm mb-2">{description}</div>
      <div>
        {sortedScopes.map((scope, index) => <div key={index}>
            <code>
              <span className="text-xs">{scope}</span>
            </code>
          </div>)}
      </div>
    </div>;
};

<Accordion title="Supported products" defaultOpen="true" icon="cubes">
  <SupportedProducts commerce={true} commerceLevel="PROFESSIONAL" />
</Accordion>

<Accordion title="Scope requirements">
  <ScopesList
    scopes={[
  'cpq.price_books.read'
]}
  />
</Accordion>

<BetaDisclaimerBanner />

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](/docs/api-reference/2026-09-beta/revenue/price-books/guide).

## 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.

```json theme={null}
{
  "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](/docs/api-reference/latest/crm/properties/guide).

### 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}`.

```json theme={null}
{
  "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](/docs/api-reference/2026-09-beta/revenue/price-books/guide#retrieve-price-books) 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`.

<Warning>**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](/docs/api-reference/latest/crm/associations/associate-records/guide#retrieve-associations).</Warning>

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

```json theme={null}
{
  "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](/docs/api-reference/2026-09-beta/revenue/price-books/guide#add-a-product-to-a-price-book) 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`.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/docs/api-reference/latest/crm/search-the-crm#make-a-search-request) including available filter operators.