> ## 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: fc57cf13-fe60-4ea2-8ad7-258a14956f7a
---
# Price books API
> Create and manage price books and product pricing programmatically.
export const BetaDisclaimerBanner = () =>
This functionality is currently in beta. By participating in this beta, you agree to HubSpot's Developer Terms and Developer Beta Terms. Note that the functionality is still under active development and is subject to change based on testing and feedback.
;
export const RequiredIndicator = () => {
return
required
;
};
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
;
};
Price books are collections of product pricing that let you define tailored prices across regions, customer segments, and channels. Use this API to create price books, configure product pricing within them, and manage their lifecycle programmatically.
## Overview
At a high-level, you'll typically follow the workflow below for creating and activating a price book:
1. [Create a price book](#create-a-price-book). New price books are always created as inactive.
2. [Update](#update-a-price-book) the name, description, and supported currencies as needed.
3. [Add products](#add-a-product-to-a-price-book) from your product library to the price book. Each added product becomes a price book item.
4. [Configure pricing](#update-item-pricing) on each price book item as needed.
5. [Validate the price book](#validate-a-price-book) to surface any errors before activating.
6. [Activate the price book](#activate-a-price-book) to make it available for use with deals, quotes, and contracts.
7. If you need to [delete a price book](#delete-a-price-book), you'll first need to deactivate it, because active price books cannot be deleted.
Then, you'll typically follow the workflow below to use price books with deals:
1. Use the [associations API](/docs/api-reference/latest/crm/associations/associate-records/guide) to associate the price book with a deal.
2. From there, line item creation from price book items must happen in HubSpot. This applies to deals, quotes, and contracts.
The system automatically copies the price book association from the deal to the quote, and from an approved quote to the contract.
## Price books
### Create a price book
To create a price book, make a `POST` request to `/commerce/price-books/2026-09-beta/price-books`. New price books are always created with an inactive status, which you can later update via the [activate endpoint](#activate-a-price-book).
In the request body, include the `name` and `supportedCurrencies` fields at a minimum.
```json theme={null}
{
"name": "My price book",
"supportedCurrencies": [
"USD"
],
"description": "An example price book"
}
```
| Property | Type | Description |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | String | The name of the price book as it will display in HubSpot. |
| `supportedCurrencies` | Array | An array of currency code strings (e.g., `"USD", "CAD"`). Can only contain currencies that have been configured for the account. You can retrieve all available currency codes via the [currencies API](/docs/api-reference/latest/account/settings/multicurrency/get-currency-codes). |
| `description` | String | The price book's description. |
The response will include the properties you provided, along with a few other details such as the price book's status and current count of products.
```json theme={null}
{
"id": "418966139535",
"createdAt": "2026-06-10T20:08:35.644Z",
"updatedAt": "2026-06-10T20:08:35.644Z",
"name": "My price book",
"description": "An example price book",
"supportedCurrencies": [
"USD",
"CAD"
],
"status": "inactive",
"countOfIncludedProducts": 0
}
```
### Retrieve price books
#### Retrieve all price books
To retrieve all price books in your account, make a `GET` request to `/commerce/price-books/2026-09-beta/price-books`. The endpoint returns a paginated list of price book records.
You can use the following optional query parameters:
| Parameter | Type | Description |
| --------- | ------- | ------------------------------------------------------------------------------------ |
| `limit` | Integer | The number of records to return per page. Defaults to 20, maximum 100. |
| `after` | String | A cursor token returned in a previous response to retrieve the next page of results. |
```json theme={null}
{
"results": [
{
"id": "418966139535",
"createdAt": "2026-06-10T20:06:04.685Z",
"updatedAt": "2026-06-10T20:22:31.600Z",
"name": "My price book",
"description": "An example price book",
"supportedCurrencies": [
"USD",
"CAD"
],
"status": "inactive",
"countOfIncludedProducts": 1
}
],
"paging": {
"next": {
"after": "1245663251"
}
}
}
```
When there are no further records, the `paging` field is omitted from the response.
#### Retrieve an individual price book
To retrieve an individual price book, make a `GET` request to `/commerce/price-books/2026-09-beta/price-books/{priceBookId}`.
The response will include the full set of price book properties.
```json theme={null}
{
"id": "418966139535",
"createdAt": "2026-06-10T20:06:04.685Z",
"updatedAt": "2026-06-10T20:22:31.600Z",
"name": "My price book",
"description": "An example price book",
"supportedCurrencies": [
"USD",
"CAD"
],
"status": "inactive",
"countOfIncludedProducts": 1
}
```
### Update a price book
To update a price book, make a `PATCH` request to `/commerce/price-books/2026-09-beta/price-books/{priceBookId}`. Only the properties included in the request body will be modified.
* The active/inactive state `status` cannot be changed via this endpoint. Use `/activate` and `/deactivate` instead.
* Only inactive price books can be updated.
For example, the request body below would set new values for the `name` and `supportedCurrencies` properties.
```json theme={null}
{
"name": "EMEA Enterprise — 2026 Q2",
"supportedCurrencies": [
"EUR",
"GBP",
"CHF"
]
}
```
The response will include the full set of price book properties, including the ones you updated.
```json theme={null}
{
"id": "418966139535",
"createdAt": "2026-06-10T20:08:35.644Z",
"updatedAt": "2026-06-10T20:08:35.644Z",
"name": "EMEA Enterprise — 2026 Q2",
"description": "An example price book",
"supportedCurrencies": [
"EUR",
"GBP",
"CHF"
],
"status": "inactive",
"countOfIncludedProducts": 0
}
```
### Validate a price book
To validate a price book without changing its `status`, make a `POST` request to `/commerce/price-books/2026-09-beta/price-books/{priceBookId}/validate`. The endpoint runs the same validation as `/activate`.
Validation checks for the following:
* The price book contains at least one product.
* Every product has a price defined for its pricing model.
* Every product has a price for each of the book's supported currencies.
If validation passes, the price book is ready to be activated. If validation fails, you'll need to address the returned issues before you can activate it. Requests to this endpoint always return `200`, with an `isValid` field and `errors` array to show whether the book can be activated.
**Valid response:**
```json theme={null}
{
"isValid": true,
"errors": []
}
```
**Invalid response:**
```json theme={null}
{
"isValid": false,
"errors": [
{
"message": "Price book must have exactly one supported currency.",
"code": "PRICE_BOOK_INVALID_CURRENCY_COUNT"
}
]
}
```
### Manage price book state
A price book has two states, which can be managed using endpoints in this API:
* **Inactive:** the default state on creation. While inactive, products can be added and modified along with the price book's currencies, and the price book cannot be used on deals, quotes, and contracts.
* **Active:** an active price book is available for use on deals, quotes, and contracts, allows users to populate line items using items defined in the price book. Products cannot be added or modified while the price book is active.
When activating a price book, a validator is run against all items in the price book. To check for issues before activating, you can use the [validation endpoint](#validate-a-price-book).
#### Activate a price book
To activate a price book, make a `POST` request to `/commerce/price-books/2026-09-beta/price-books/{priceBookId}/activate`. When hitting this endpoint, validation will be run against the price book items to ensure there are no issues.
Activating a price book sets its `status` to `active` and enables it for use in HubSpot. Activating an already-active book is a no-op that returns `200` with the current state.
```json highlight={11} theme={null}
{
"id": "418966139535",
"createdAt": "2026-06-10T20:06:04.685Z",
"updatedAt": "2026-06-10T22:40:54.866Z",
"name": "2026 H2 catalog",
"description": "An example price book",
"supportedCurrencies": [
"USD",
"CAD"
],
"status": "active",
"countOfIncludedProducts": 3
}
```
#### Deactivate a price book
To deactivate a price book, make a `POST` request to `/commerce/price-books/2026-09-beta/price-books/{priceBookId}/deactivate`.
Existing deals and quotes that reference this price book continue to resolve it by ID for historical accuracy.
Deactivating a price book sets its `status` to `inactive` and enables editing while preventing it from being used in HubSpot. Deactivating an already-inactive book is a no-op that returns `200` with the current state.
```json highlight={11} theme={null}
{
"id": "418966139535",
"createdAt": "2026-06-10T20:06:04.685Z",
"updatedAt": "2026-06-10T22:40:54.866Z",
"name": "2026 H2 catalog",
"description": "An example price book",
"supportedCurrencies": [
"USD",
"CAD"
],
"status": "inactive",
"countOfIncludedProducts": 3
}
```
### Delete a price book
**Please note:**
* Once a price book has been deleted, it cannot be restored.
* A price book can only be deleted when its `status` is `inactive`. To delete an active price book, you'll first need to [deactivate it](#deactivate-a-price-book).
To delete a price book, make a `PATCH` request to `/commerce/price-books/2026-09-beta/price-books/{priceBookId}`. In the request body, include `{ "archived": true }`.
```json theme={null}
{ "archived": true }
```
## Price book items
### Add a product to a price book
To add a product from your product library to a price book, make a `POST` request to `/commerce/price-books/2026-09-beta/price-books/{priceBookId}/items`. In the request body, include a `productId` field with the ID of the product you want to copy to the price book.
If you haven't created any products yet, you can do so via the [products API](/docs/api-reference/latest/crm/objects/products/guide).
You can retrieve product IDs via the [Products API](/docs/api-reference/latest/crm/objects/products/get-products) or by viewing the product's *Record ID* property in HubSpot. Only one instance of each product can appear in a price book at a time.
```json theme={null}
{ "productId": "15683005185" }
```
After making the request, a price book item will be created based on the product's properties, including the name, SKU, pricing information (in all currencies if applicable), billing period, and billing frequency. The source product is never modified by price book operations, similar to line items created from products.
[Tiered pricing](https://knowledge.hubspot.com/products/create-and-manage-products) is supported for price book items. The pricing model and tier configuration are carried over from the source product and cannot be modified after creation, with the only exception being the `price` fields. Learn more about [configuring tiered pricing via the products API](/docs/api-reference/latest/crm/objects/products/guide#tiered-pricing).
The tabs below show example responses for adding a product with flat rate pricing and a product with tiered pricing.
```json theme={null}
{
"id": "418968256821",
"createdAt": "2026-06-10T20:44:11.881Z",
"updatedAt": "2026-06-10T20:44:11.881Z",
"name": "Launchbook item",
"status": "active",
"pricing": {
"pricingModel": "flat",
"prices": [
{
"currencyCode": "CAD",
"price": "92.00"
},
{
"currencyCode": "USD",
"price": "100.00"
}
]
},
"billingFrequency": "monthly",
"billingPeriod": "P12M",
"productId": "15683005185",
"priceBookId": "418966139535"
}
```
```json theme={null}
{
"id": "418968226449",
"createdAt": "2026-06-10T20:49:13.769Z",
"updatedAt": "2026-06-10T20:49:13.769Z",
"name": "Graduated product",
"status": "active",
"pricing": {
"pricingModel": "graduated",
"prices": [
{
"currencyCode": "CAD",
"price": "154",
"maxQuantity": 99
},
{
"currencyCode": "CAD",
"price": "139",
"maxQuantity": 199
},
{
"currencyCode": "CAD",
"price": "124",
"maxQuantity": "inf"
},
{
"currencyCode": "USD",
"price": "115",
"maxQuantity": 99
},
{
"currencyCode": "USD",
"price": "100",
"maxQuantity": 199
},
{
"currencyCode": "USD",
"price": "85",
"maxQuantity": "inf"
}
]
},
"billingFrequency": "monthly",
"billingPeriod": "P12M",
"productId": "15686968916",
"priceBookId": "418966139535"
}
```
The `id` in the response is the price book item ID (`priceBookItemId`), which you can use in subsequent `/{priceBookId}/items/{priceBookItemId}` requests to read, update, archive, or restore the item.
### Batch add products to a price book
To add multiple products to a price book in a single request, make a `POST` request to `/commerce/price-books/2026-09-beta/price-books/{priceBookId}/items/batch/create`. The price book must be [inactive](#deactivate-a-price-book) before adding products.
In the request body, include an `inputs` array with up to 100 entries. Each entry must include a `productId` field with the ID of the product to add.
For snapshot semantics and field behavior, refer to [Add a product to a price book](#add-a-product-to-a-price-book).
```json theme={null}
{
"inputs": [
{ "productId": "420281979905" },
{ "productId": "1234567890" }
]
}
```
* If the same `productId` appears more than once in a request, duplicates are deduped and only one item is added, with no error.
* If some inputs fail, the remaining inputs are still processed.
On full success, the endpoint returns `200 OK` with a `results[]` array containing the full updated price book item for each input. If any inputs fail, the endpoint returns `207 Multi-Status` with successes in `results[]` and per-input failures in `errors[]`.
```json theme={null}
{
"completedAt": "2026-07-16T18:12:08.846Z",
"status": "COMPLETE",
"startedAt": "2026-07-16T18:12:08.160Z",
"results": [
{
"id": "420281409373",
"createdAt": "2026-07-16T18:12:08.341Z",
"updatedAt": "2026-07-16T18:12:08.341Z",
"name": "Morning Fix Coffee clothing bundle",
"status": "active",
"pricing": {
"pricingModel": "flat",
"prices": [
{
"currencyCode": "USD",
"price": "200"
}
]
},
"productId": "15522155790",
"priceBookId": "418082214954"
},
{
"id": "420281409372",
"createdAt": "2026-07-16T18:12:08.341Z",
"updatedAt": "2026-07-16T18:12:08.341Z",
"name": "Coffee self-pace course videos",
"status": "active",
"pricing": {
"pricingModel": "flat",
"prices": [
{
"currencyCode": "USD",
"price": "100"
}
]
},
"productId": "15522149473",
"priceBookId": "418082214954"
}
]
}
```
```json theme={null}
{
"completedAt": "2026-07-16T18:09:52.168Z",
"status": "COMPLETE",
"startedAt": "2026-07-16T18:09:51.557Z",
"results": [
{
"id": "420281979905",
"createdAt": "2026-07-16T18:09:51.714Z",
"updatedAt": "2026-07-16T18:09:51.714Z",
"name": "Coffee masterclass",
"status": "active",
"pricing": {
"pricingModel": "flat",
"prices": [
{
"currencyCode": "USD",
"price": "150"
}
]
},
"productId": "15493657257",
"priceBookId": "418082214954"
}
],
"errors": [
{
"status": "error",
"category": "OBJECT_NOT_FOUND",
"subCategory": "PriceBookError.PRODUCTS_NOT_FOUND",
"message": "Product not found.",
"errors": [
{
"message": "Product not found.",
"code": "PRODUCTS_NOT_FOUND",
"context": {
"missingProductIds": [
"1234567890"
]
}
}
]
}
],
"numErrors": 1
}
```
### Retrieve price book items
#### Retrieve all items in a price book
To retrieve all items in a price book, make a `GET` request to `/commerce/price-books/2026-09-beta/price-books/{priceBookId}/items`. The endpoint returns a paginated list of price book item records scoped to the given price book.
You can use the following optional query parameters:
| Parameter | Type | Description |
| ---------- | ------- | ------------------------------------------------------------------------------------ |
| `limit` | Integer | The number of records to return per page. Defaults to 20, maximum 100. |
| `after` | String | A cursor token returned in a previous response to retrieve the next page of results. |
| `archived` | Boolean | Set to `true` to return only archived items. Defaults to `false`. |
```json theme={null}
{
"results": [
{
"id": "418971488132",
"createdAt": "2026-06-10T22:10:31.764Z",
"updatedAt": "2026-06-10T22:10:31.764Z",
"name": "Flat-priced product",
"status": "active",
"sku": "123456",
"pricing": {
"pricingModel": "flat",
"prices": [
{
"currencyCode": "USD",
"price": "100"
}
]
},
"billingFrequency": "monthly",
"billingPeriod": "P12M",
"productId": "15686917193",
"priceBookId": "418969457771"
}
],
"paging": {
"next": {
"after": "1245663251"
}
}
}
```
When there are no further records, the `paging` field is omitted from the response.
#### Retrieve an individual price book item
To retrieve a price book item, make a `GET` request to `/commerce/price-books/2026-09-beta/price-books/{priceBookId}/items/{priceBookItemId}`.
You can include the `?archived=true` query parameter to return an archived price book item.
```json theme={null}
{
"id": "418971488132",
"createdAt": "2026-06-10T22:10:31.764Z",
"updatedAt": "2026-06-10T22:10:31.764Z",
"name": "Flat-priced product",
"status": "active",
"sku": "123456",
"pricing": {
"pricingModel": "flat",
"prices": [
{
"currencyCode": "USD",
"price": "100"
}
]
},
"billingFrequency": "monthly",
"billingPeriod": "P12M",
"productId": "15686917193",
"priceBookId": "418969457771"
}
```
### Update item pricing
To update item pricing, make a `PATCH` request to `/commerce/price-books/2026-09-beta/price-books/{priceBookId}/items/{priceBookItemId}`. The price book must be [inactive](#deactivate-a-price-book) before updating item pricing.
In the request body, you can specify new values for `price` fields as needed. Other properties, such as `pricingModel`, `currencyCode`, and `maxQuantity` are set at the time of creating the price book item, and cannot be changed. To change a price book item's pricing tier configuration, you'll need to archive the item, update the original product that the item was based on, then add it to the price book.
Partial price updates are supported, meaning you can pass in prices for a subset of the price book's supported currencies, and the prices for the remaining currencies will remain unchanged.
The tabs below show example request bodies for flat and tiered price book items.
```json theme={null}
{
"pricing": {
"prices": [
{
"currencyCode": "USD",
"price": "600"
}
]
}
}
```
```json theme={null}
{
"pricing": {
"prices": [
{
"currencyCode": "CAD",
"price": "0.34",
"maxQuantity": 99
},
{
"currencyCode": "CAD",
"price": "0.31",
"maxQuantity": 199
},
{
"currencyCode": "CAD",
"price": "0.28",
"maxQuantity": "inf"
},
{
"currencyCode": "USD",
"price": "0.1",
"maxQuantity": 99
},
{
"currencyCode": "USD",
"price": "0.08",
"maxQuantity": 199
},
{
"currencyCode": "USD",
"price": "0.05",
"maxQuantity": "inf"
}
]
}
}
```
### Batch update item pricing
To update pricing for multiple items in a single request, make a `POST` request to `/commerce/price-books/2026-09-beta/price-books/{priceBookId}/items/batch/update`. The price book must be [inactive](#deactivate-a-price-book) before updating item pricing.
**Please note:** not all pricing fields can be updated via this API, and are instead set when initially creating the item. Learn more about [updating product pricing](#update-item-pricing).
In the request body, include an `inputs` array with up to 100 entries. Each entry must include an `id` field with the price book item ID, along with a `properties` object containing the details that you want to update.
```json theme={null}
{
"inputs": [
{
"id": "15687804044",
"properties": {
"pricing": {
"pricingModel": "flat",
"prices": [
{
"currencyCode": "CAD",
"price": "92.00"
},
{
"currencyCode": "USD",
"price": "100.00"
}
]
}
}
}
]
}
```
| Property | Type | Description |
| ---------------------------------- | ------ | ---------------------------------------------------------------------------------------- |
| `id` | String | The price book item ID, returned in the `id` field of the add or read response. |
| `properties` | Object | The details to update for each item, such as `pricing`, `billingFrequency`, or `status`. |
* If the same `id` appears more than once in a request, the inputs are processed in array order and the last write wins.
* If some inputs fail, the remaining inputs are still processed.
On full success, the endpoint returns `200 OK` with a `results[]` array containing the full updated price book item for each input. If any inputs fail, the endpoint returns `207 Multi-Status` with successes in `results[]` and per-input failures in `errors[]`.
```json theme={null}
{
"completedAt": "2026-07-16T17:42:15.416Z",
"status": "COMPLETE",
"startedAt": "2026-07-16T17:42:15.126Z",
"results": [
{
"id": "15687804044",
"createdAt": "2026-05-20T10:06:45.273Z",
"updatedAt": "2026-07-16T17:42:15.187Z",
"name": "Coffee machine servicing",
"status": "active",
"properties": {
"pricing": {
"pricingModel": "flat",
"prices": [
{
"currencyCode": "CAD",
"price": "92.00"
},
{
"currencyCode": "USD",
"price": "100.00"
}
]
}
}
}
]
}
```
```json theme={null}
{
"completedAt": "2026-07-16T18:15:58.299Z",
"status": "COMPLETE",
"startedAt": "2026-07-16T18:15:57.996Z",
"results": [
{
"id": "420281409372",
"createdAt": "2026-07-16T18:12:08.341Z",
"updatedAt": "2026-07-16T18:15:58.094Z",
"name": "Coffee self-pace course videos",
"status": "active",
"pricing": {
"pricingModel": "flat",
"prices": [
{
"currencyCode": "USD",
"price": "100.00"
}
]
},
"productId": "15522149473",
"priceBookId": "418082214954"
}
],
"errors": [
{
"status": "error",
"category": "VALIDATION_ERROR",
"subCategory": "PriceBookError.PRICE_BOOK_UNSUPPORTED_CURRENCY",
"message": "The following currencies are not supported by this price book: CAD",
"errors": [
{
"message": "The following currencies are not supported by this price book: CAD",
"code": "PRICE_BOOK_UNSUPPORTED_CURRENCY",
"context": {
"priceBookId": [
"418082214954"
],
"priceBookItemId": [
"420281409373"
]
}
}
]
}
],
"numErrors": 1
}
```
### Archive and restore a price book item
Both archiving and restoring a price book item use `PATCH` requests to `/commerce/price-books/2026-09-beta/price-books/{priceBookId}/items/{priceBookItemId}`.
To archive an item, include `{ "archived": true }` in the request body. Archived items are moved to the CRM recycling bin and auto-purged after 90 days. Archiving an already-archived item is a no-op that returns `204`.
```json theme={null}
{ "archived": true }
```
To restore an archived item, include the `?archived=true` query parameter in the request URL, and include `{ "archived": false }` in the request body.
```shell wrap theme={null}
PATCH /commerce/price-books/2026-09-beta/price-books/{priceBookId}/items/{priceBookItemId}?archived=true
```
```json theme={null}
{ "archived": false }
```
The item will be restored to active state once the request succeeds.
**Please note:** archive and restore request bodies must contain only `{ "archived": true }` or `{ "archived": false }`. Including any other fields will return an error. To update the pricing of an archived item, you'll first need to restore the item, then make a separate `PATCH` request after restoration.
### Batch archive price book items
To archive multiple price book items in a single request, make a `POST` request to `/commerce/price-books/2026-09-beta/price-books/{priceBookId}/items/batch/archive`.
Archived items are moved to the CRM recycling bin and auto-purged after 90 days. You can restore individual archived items using the [restore endpoint](#archive-and-restore-a-price-book-item).
In the request body, include an `inputs` array with up to 100 entries. Each entry must include an `id` field with the price book item ID.
```json theme={null}
{
"inputs": [
{ "id": "418968256821" },
{ "id": "418968256822" }
]
}
```
On full success, the endpoint returns `204 No Content` with no response body. If any inputs fail, the endpoint returns `207 Multi-Status` with error details.
```
HTTP/1.1 204 No Content
```
```json theme={null}
{
"completedAt": "2026-07-16T17:25:09.046Z",
"status": "COMPLETE",
"startedAt": "2026-07-16T17:25:08.922Z",
"results": [
{
"id": "418081052479"
}
],
"errors": [
{
"status": "error",
"category": "VALIDATION_ERROR",
"subCategory": "PriceBookError.PRICE_BOOK_ITEM_NOT_FOUND_IN_PRICE_BOOK",
"message": "Price book item does not belong to this price book.",
"errors": [
{
"message": "Price book item does not belong to this price book.",
"code": "PRICE_BOOK_ITEM_NOT_FOUND_IN_PRICE_BOOK",
"context": {
"priceBookId": [
"418082214954"
],
"priceBookItemId": [
"12345125215"
]
}
}
]
}
],
"numErrors": 1
}
```
{product.name} -
{product.level}
)}