CRM API | Price books - HubSpot docs

Supported products

Required Scopes

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/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/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 APIwhen 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.

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/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 endpointsin 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.

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

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

Business API property mapping

The price books CRM object API (/crm/objects/) and price books business API(/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.

CRM API
Business API

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

{
  "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)
`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.

CRM API
Business API

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

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

​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

​Business API property mapping

​Price book properties

​Price book item properties

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

Business API property mapping

Price book properties

Price book item properties