Price books API - HubSpot docs

Supported products

Scope requirements

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:

Create a price book. New price books are always created as inactive.
Update the name, description, and supported currencies as needed.
Add products from your product library to the price book. Each added product becomes a price book item.
Configure pricing on each price book item as needed.
Validate the price book to surface any errors before activating.
Activate the price book to make it available for use with deals, quotes, and contracts.
If you need to 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:

Use the associations API to associate the price book with a deal.
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. In the request body, include the name and supportedCurrencies fields at a minimum.

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

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

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

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

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

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

{
  "isValid": true,
  "errors": []
}

Invalid response:

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

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.

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

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

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

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

You can retrieve product IDs via the Products API 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.

{ "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 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. The tabs below show example responses for adding a product with flat rate pricing and a product with tiered pricing.

Basic product response
Tiered product response

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

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

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

200 OK
207 Multi-Status

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

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

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

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

Flat price book item
Tiered price book item

{
  "pricing": {
    "prices": [
      {
        "currencyCode": "USD",
        "price": "600"
      }
    ]
  }
}

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

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.

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

200 OK
207 Multi-Status

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

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

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

PATCH /commerce/price-books/2026-09-beta/price-books/{priceBookId}/items/{priceBookItemId}?archived=true

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

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

204 No Content
207 Multi-Status

HTTP/1.1 204 No Content

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

​Overview

​Price books

​Create a price book

​Retrieve price books

​Retrieve all price books

​Retrieve an individual price book

​Update a price book

​Validate a price book

​Manage price book state

​Activate a price book

​Deactivate a price book

​Delete a price book

​Price book items

​Add a product to a price book

​Batch add products to a price book

​Retrieve price book items

​Retrieve all items in a price book

​Retrieve an individual price book item

​Update item pricing

​Batch update item pricing

​Archive and restore a price book item

​Batch archive price book items

Overview

Price books

Create a price book

Retrieve price books

Retrieve all price books

Retrieve an individual price book

Update a price book

Validate a price book

Manage price book state

Activate a price book

Deactivate a price book

Delete a price book

Price book items

Add a product to a price book

Batch add products to a price book

Retrieve price book items

Retrieve all items in a price book

Retrieve an individual price book item

Update item pricing

Batch update item pricing

Archive and restore a price book item

Batch archive price book items