;
};
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
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
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/latest/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/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/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/latest/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/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](/docs/api-reference/latest/crm/associations/associate-records/guide#retrieve-associations).
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/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/price_book_items/{objectId}`.
The record ID matches the `id` returned by the [price book items endpoints](/docs/api-reference/latest/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/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/price_books/search` (or `/crm/objects/2026-09/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.
## Business API property mapping
The price books CRM object API (`/crm/objects/`) and [price books business API](/docs/api-reference/latest/revenue/price-books/guide)(`/commerce/price-books/`) expose the same underlying data, with the following differences in how fields are returned:
* **Nesting:** business API fields are returned at the top level of the response. CRM API fields are returned inside a `properties` object, alongside a few standard top-level envelope fields (`id`, `createdAt`, `updatedAt`, `archived`).
* **Naming:** field names follow different conventions. CRM fields use HubSpot's `hs_`-prefixed property naming pattern.
* **Shape:** some values are returned in a different format, such as `supportedCurrencies` (array in the business API, semicolon-delimited string in the CRM API) and `pricing` for price book items.
* **Casing:** string enum values use different cases. Business API returns uppercase (e.g., `"VOLUME"`, `"NON_INVENTORY"`). CRM returns lowercase (e.g., `"volume"`, `"non_inventory"`).
* **Types:** numeric values are returned as numbers by the business API and as strings by the CRM API (e.g., `countOfIncludedProducts: 6` vs `"hs_count_of_included_products": "6"`).
The tables below list each set of corresponding fields and note where there are behavioral differences.
### Price book properties
| CRM property | Business API field | Notes |
| ------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `hs_object_id` | `id` | |
| `hs_name` | `name` | |
| `hs_description` | `description` | |
| `hs_supported_currencies` | `supportedCurrencies` | CRM returns a semicolon-delimited string (e.g., `"USD;EUR"`). Business API returns an array (e.g., `["USD", "EUR"]`) |
| `hs_status` | `status` | |
| `hs_count_of_included_products` | `countOfIncludedProducts` | Business API returns a number. CRM returns a string |
| `hs_is_auto_assigned_enabled` | `autoAssignmentEnabled` | |
| `hs_createdate` | `createdAt` | |
| `hs_lastmodifieddate` | `updatedAt` | |
| `archived` | `archived` | Top-level field in the CRM response, not a property |
| Custom property names | `customProperties` | Same property names on both APIs |
The following example shows a `GET` response for the same price book from each API.
```json theme={null}
{
"id": "418966139535",
"properties": {
"hs_count_of_included_products": "6",
"hs_createdate": "2026-06-10T20:06:04.685Z",
"hs_description": "An updated description",
"hs_is_auto_assigned_enabled": "false",
"hs_lastmodifieddate": "2026-06-11T22:36:53.653Z",
"hs_name": "Multi-currency Launchbook",
"hs_object_id": "418966139535",
"hs_status": "inactive",
"hs_supported_currencies": "USD;CAD"
},
"createdAt": "2026-06-10T20:06:04.685Z",
"updatedAt": "2026-06-11T22:36:53.653Z",
"archived": false
}
```
```json theme={null}
{
"id": "418966139535",
"createdAt": "2026-06-10T20:06:04.685Z",
"updatedAt": "2026-06-11T22:36:53.653Z",
"name": "Multi-currency Launchbook",
"description": "An updated description",
"supportedCurrencies": [
"USD",
"CAD"
],
"status": "inactive",
"countOfIncludedProducts": 6,
"autoAssignmentEnabled": false
}
```
### Price book item properties
| CRM property | Business API field | Notes |
| --------------------------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hs_object_id` | `id` | |
| `hs_name` | `name` | Read-only, inherited from the source product |
| `hs_description` | `description` | Read-only, inherited from the source product |
| `hs_sku` | `sku` | Read-only, inherited from the source product |
| `hs_status` | `status` | |
| `hs_associated_product_id` | `productId` | |
| `hs_pricing_model` | `pricing.pricingModel` | Read-only, inherited from the source product. Value casing differs (see [above](#business-api-property-mapping)) |
| `hs_price` (single-currency) / `hs_price_{currency}` (multi-currency) | `pricing.prices[].price` | CRM uses flat properties. Business API nests prices in a `pricing.prices` array. For tiered and volume pricing, these CRM properties return `null`; use `hs_tier_ranges` and `hs_tier_prices` instead |
| `hs_tier_ranges` | `pricing.prices[].tierRanges` | Serialized as a JSON string in CRM |
| `hs_tier_prices` | `pricing.prices[].tierPrices` | Serialized as a JSON string in CRM |
| `hs_billing_frequency` | `billingFrequency` | |
| `hs_billing_period` | `billingPeriod` | ISO-8601 period string (e.g., `P1M`) |
| `hs_recurring_billing_terms` | `recurringBillingTerms` | |
| `hs_cost_of_goods_sold` | `costOfGoodsSold` | |
| `hs_product_type` | `productType` | Value casing differs (see above) |
| `hs_product_classification` | `productClassification` | Value casing differs (see above) |
| `hs_tax_category` | `taxCategory` | |
| `hs_createdate` | `createdAt` | |
| `hs_lastmodifieddate` | `updatedAt` | |
| Custom property names | `customProperties` | Same property names on both APIs |
The following example shows a `GET` response for the same price book item from each API.
```json theme={null}
{
"id": "418081052480",
"properties": {
"hs_associated_product_id": "15322890037",
"hs_billing_frequency": "quarterly",
"hs_billing_period": null,
"hs_cost_of_goods_sold": null,
"hs_createdate": "2026-05-20T10:06:45.273Z",
"hs_lastmodifieddate": "2026-07-31T05:17:36.912Z",
"hs_name": "Coffee machine servicing",
"hs_object_id": "418081052480",
"hs_price_usd": "100.00",
"hs_pricing_model": "flat",
"hs_product_classification": "standalone",
"hs_product_type": "service",
"hs_recurring_billing_terms": "AUTOMATICALLY_RENEW",
"hs_sku": "SVC-COFFEE-001",
"hs_status": "active",
"hs_tax_category": "2147488345"
},
"createdAt": "2026-05-20T10:06:45.273Z",
"updatedAt": "2026-07-31T05:17:36.912Z",
"archived": false
}
```
```json theme={null}
{
"id": "418081052480",
"createdAt": "2026-05-20T10:06:45.273Z",
"updatedAt": "2026-07-31T05:17:36.912Z",
"name": "Coffee machine servicing",
"status": "active",
"sku": "SVC-COFFEE-001",
"pricing": {
"pricingModel": "FLAT",
"prices": [
{
"currencyCode": "USD",
"price": "100.00"
}
]
},
"billingFrequency": "quarterly",
"productId": "15322890037",
"priceBookId": "418082214954",
"productClassification": "STANDALONE",
"productType": "SERVICE",
"recurringBillingTerms": "AUTOMATICALLY_RENEW",
"taxCategory": "2147488345"
}
```
{product.name} -
{product.level}
)}