HubSpot Commerce Price Books API

openapi: 3.0.1
info:
  title: HubSpot Commerce Price Books
  description: Basepom for all HubSpot Projects
  version: 2026-09
  x-hubspot-product-tier-requirements:
    marketing: FREE
    sales: FREE
    service: FREE
    cms: FREE
    commerce: FREE
    crmHub: FREE
    dataHub: FREE
servers:
- url: https://api.hubapi.com
tags:
- name: Advanced
- name: Basic
- name: Batch
- name: Items
paths:
  /commerce/price-books/2026-09/price-books:
    get:
      tags:
      - Advanced
      summary: Retrieve price books
      description: Retrieve a list of price books available in your HubSpot account. This endpoint supports
        pagination and can return archived price books if specified. It is useful for accessing and managing
        pricing information across different products and services.
      operationId: get-/commerce/price-books/2026-09/price-books_/commerce/price-books/2026-09-beta/price-books
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponsePriceBookResponseForwardPaging'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - price-book-read
    post:
      tags:
      - Basic
      summary: Create price book
      description: Create a new price book in your HubSpot account. This endpoint allows you to define
        custom properties, a name, and supported currencies for the price book. A successful request will
        return the URL of the newly created resource.
      operationId: post-/commerce/price-books/2026-09/price-books
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceBookCreateRequest'
        required: true
      responses:
        '201':
          description: successful operation
          headers:
            Location:
              description: URL of the newly created resource
              style: simple
              explode: false
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceBookResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - price-book-write
  /commerce/price-books/2026-09/price-books/{priceBookId}:
    get:
      tags:
      - Basic
      summary: Retrieve price book
      description: Retrieve a specific price book by its unique identifier in your HubSpot account. This
        endpoint allows you to access detailed information about a price book, including its status and
        supported currencies. It can be useful for managing and reviewing pricing strategies within your
        commerce system.
      operationId: get-/commerce/price-books/2026-09/price-books/{priceBookId}
      parameters:
      - name: priceBookId
        in: path
        description: The unique identifier of the price book to retrieve.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceBookResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - price-book-read
    delete:
      tags:
      - Basic
      summary: Delete price book
      description: Delete a specific price book from your HubSpot account using its unique identifier.
        This operation will permanently remove the price book and its associated data, making it unavailable
        for future use.
      operationId: delete-/commerce/price-books/2026-09/price-books/{priceBookId}
      parameters:
      - name: priceBookId
        in: path
        description: The unique identifier of the price book to delete.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - price-book-write
    patch:
      tags:
      - Basic
      summary: Update price book
      description: Update an existing price book in your HubSpot account. This operation allows you to
        modify details such as the name, description, supported currencies, and custom properties of a
        price book. It is useful for keeping your price book information up to date with the latest changes.
      operationId: patch-/commerce/price-books/2026-09/price-books/{priceBookId}
      parameters:
      - name: priceBookId
        in: path
        description: The unique identifier of the price book to update.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceBookUpdateRequest'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceBookResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - price-book-write
  /commerce/price-books/2026-09/price-books/{priceBookId}/activate:
    post:
      tags:
      - Basic
      summary: Activate price book
      description: Activate a specific price book in your HubSpot account. This operation changes the
        status of the price book to active, allowing it to be used in transactions and other operations.
        Ensure that the price book ID is correct before activation.
      operationId: post-/commerce/price-books/2026-09/price-books/{priceBookId}/activate
      parameters:
      - name: priceBookId
        in: path
        description: The unique identifier of the price book to activate.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceBookResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - price-book-write
  /commerce/price-books/2026-09/price-books/{priceBookId}/deactivate:
    post:
      tags:
      - Basic
      summary: Deactivate price book
      description: Deactivate a specific price book in your HubSpot account. This action changes the status
        of the price book to inactive, making it unavailable for use in transactions. Use this endpoint
        when you need to temporarily or permanently disable a price book without deleting it.
      operationId: post-/commerce/price-books/2026-09/price-books/{priceBookId}/deactivate
      parameters:
      - name: priceBookId
        in: path
        description: The unique identifier of the price book to deactivate.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceBookResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - price-book-write
  /commerce/price-books/2026-09/price-books/{priceBookId}/items:
    get:
      tags:
      - Items
      summary: List price book items
      description: Retrieve a list of items associated with a specific price book in your HubSpot account.
        This endpoint allows you to paginate through the items and specify which properties to include
        in the response. It is useful for managing and viewing the details of products linked to a particular
        price book.
      operationId: get-/commerce/price-books/2026-09/price-books/{priceBookId}/items_/commerce/price-books/2026-09-beta/price-books/{priceBookId}/items
      parameters:
      - name: priceBookId
        in: path
        description: The unique identifier of the price book to retrieve items for.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: properties
        in: query
        description: A list of property names to include in the response.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponsePriceBookItemResponseForwardPaging'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - price-book-read
    post:
      tags:
      - Items
      summary: Add price book items
      description: Add new items to a specified price book in your HubSpot account. This endpoint allows
        you to associate products with a price book by providing the necessary product details. It is
        useful for managing and updating the contents of your price books efficiently.
      operationId: post-/commerce/price-books/2026-09/price-books/{priceBookId}/items_/commerce/price-books/2026-09-beta/price-books/{priceBookId}/items
      parameters:
      - name: priceBookId
        in: path
        description: The unique identifier of the price book to which items will be added.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceBookAddProductRequest'
        required: true
      responses:
        '201':
          description: successful operation
          headers:
            Location:
              description: URL of the newly created resource
              style: simple
              explode: false
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceBookItemResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - inbounddb-product-library-read
        - price-book-write
  /commerce/price-books/2026-09/price-books/{priceBookId}/items/batch/archive:
    post:
      tags:
      - Batch
      summary: Batch archive price book items
      description: Archive multiple items within a specified price book in a single batch operation. This
        endpoint is useful for managing large sets of price book items that need to be archived simultaneously,
        streamlining the process and reducing the number of individual requests.
      operationId: post-/commerce/price-books/2026-09/price-books/{priceBookId}/items/batch/archive_/commerce/price-books/2026-09-beta/price-books/{priceBookId}/items/batch/archive
      parameters:
      - name: priceBookId
        in: path
        description: The unique identifier of the price book containing the items to be archived.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchInputSimplePublicObjectId'
        required: true
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - price-book-write
  /commerce/price-books/2026-09/price-books/{priceBookId}/items/batch/create:
    post:
      tags:
      - Batch
      summary: Batch create price book items
      description: Create multiple items in a specified price book in a single batch operation. This endpoint
        is useful for efficiently adding a large number of items to a price book, reducing the need for
        multiple individual requests. The operation returns a batch response indicating the success or
        failure of each item creation.
      operationId: post-/commerce/price-books/2026-09/price-books/{priceBookId}/items/batch/create_/commerce/price-books/2026-09-beta/price-books/{priceBookId}/items/batch/create
      parameters:
      - name: priceBookId
        in: path
        description: The unique identifier of the price book to which the items will be added.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchInputPriceBookAddProductRequest'
        required: true
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponsePriceBookItemResponse'
        '207':
          description: multiple statuses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponsePriceBookItemResponseWithErrors'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - inbounddb-product-library-read
        - price-book-write
  /commerce/price-books/2026-09/price-books/{priceBookId}/items/batch/update:
    post:
      tags:
      - Batch
      summary: Batch update price book items
      description: Update multiple items in a specified price book in a single batch operation. This endpoint
        allows for efficient updates of price book items, making it useful for managing large sets of
        data within a price book. The operation returns a batch response indicating the success or failure
        of each item update.
      operationId: post-/commerce/price-books/2026-09/price-books/{priceBookId}/items/batch/update_/commerce/price-books/2026-09-beta/price-books/{priceBookId}/items/batch/update
      parameters:
      - name: priceBookId
        in: path
        description: The unique identifier of the price book containing the items to update.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchInputPriceBookItemBatchUpdateInput'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponsePriceBookItemResponse'
        '207':
          description: multiple statuses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponsePriceBookItemResponseWithErrors'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - price-book-write
  /commerce/price-books/2026-09/price-books/{priceBookId}/items/{priceBookItemId}:
    get:
      tags:
      - Items
      summary: Retrieve price book item
      description: Retrieve a specific item from a price book using its unique identifiers. This endpoint
        allows you to access detailed information about a particular item within a specified price book,
        including its properties and archived status if applicable.
      operationId: get-/commerce/price-books/2026-09/price-books/{priceBookId}/items/{priceBookItemId}_/commerce/price-books/2026-09-beta/price-books/{priceBookId}/items/{priceBookItemId}
      parameters:
      - name: priceBookId
        in: path
        description: The unique identifier of the price book containing the item.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - name: priceBookItemId
        in: path
        description: The unique identifier of the item within the price book.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: properties
        in: query
        description: A list of property names to include in the response.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceBookItemResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - price-book-read
    delete:
      tags:
      - Items
      summary: Delete price book item
      description: Remove a specific item from a price book in your HubSpot account. This operation is
        irreversible and will permanently delete the item identified by the given priceBookItemId from
        the price book specified by priceBookId.
      operationId: delete-/commerce/price-books/2026-09/price-books/{priceBookId}/items/{priceBookItemId}
      parameters:
      - name: priceBookId
        in: path
        description: The unique identifier of the price book from which the item will be deleted.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - name: priceBookItemId
        in: path
        description: The unique identifier of the item to be deleted from the price book.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - price-book-write
    patch:
      tags:
      - Items
      summary: Update price book item
      description: Update a specific item within a price book in your HubSpot account. This operation
        allows you to modify details such as pricing, billing frequency, and custom properties for the
        specified item. Ensure that the item is identified correctly by its unique priceBookId and priceBookItemId.
      operationId: patch-/commerce/price-books/2026-09/price-books/{priceBookId}/items/{priceBookItemId}
      parameters:
      - name: priceBookId
        in: path
        description: The unique identifier of the price book containing the item to update.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - name: priceBookItemId
        in: path
        description: The unique identifier of the item within the price book to update.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceBookItemUpdateRequest'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceBookItemResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - inbounddb-product-library-read
        - price-book-write
  /commerce/price-books/2026-09/price-books/{priceBookId}/validate:
    post:
      tags:
      - Basic
      summary: Validate price book
      description: Validate a specific price book in your HubSpot account. This endpoint checks the integrity
        and correctness of the price book identified by the given priceBookId. Use this to ensure that
        the price book meets all necessary criteria before proceeding with further operations.
      operationId: post-/commerce/price-books/2026-09/price-books/{priceBookId}/validate
      parameters:
      - name: priceBookId
        in: path
        description: The unique identifier of the price book to validate.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceBookValidateResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - price-book-read
components:
  schemas:
    BatchInputPriceBookAddProductRequest:
      required:
      - inputs
      type: object
      properties:
        inputs:
          type: array
          description: An array of PriceBookAddProductRequest objects, each representing a product to
            be added to the price book. This property is required.
          items:
            $ref: '#/components/schemas/PriceBookAddProductRequest'
    BatchInputPriceBookItemBatchUpdateInput:
      required:
      - inputs
      type: object
      properties:
        inputs:
          type: array
          description: An array of objects, each representing a price book item to be updated. Each object
            must conform to the PriceBookItemBatchUpdateInput schema.
          items:
            $ref: '#/components/schemas/PriceBookItemBatchUpdateInput'
    BatchInputSimplePublicObjectId:
      required:
      - inputs
      type: object
      properties:
        inputs:
          type: array
          description: An array of SimplePublicObjectId objects, each representing a unique identifier
            for a public object. This property is required and is used to specify the objects involved
            in the batch operation.
          items:
            $ref: '#/components/schemas/SimplePublicObjectId'
    BatchResponsePriceBookItemResponse:
      required:
      - completedAt
      - results
      - startedAt
      - status
      type: object
      properties:
        completedAt:
          type: string
          description: The date and time when the batch operation was completed, in ISO 8601 format.
          format: date-time
        links:
          type: object
          additionalProperties:
            type: string
          description: A map of link names to associated URIs providing additional information or actions
            related to the batch operation.
        requestedAt:
          type: string
          description: The date and time when the batch operation was requested, in ISO 8601 format.
          format: date-time
        results:
          type: array
          description: An array of PriceBookItemResponse objects representing the individual results of
            the batch operation.
          items:
            $ref: '#/components/schemas/PriceBookItemResponse'
        startedAt:
          type: string
          description: The date and time when the batch operation started, in ISO 8601 format.
          format: date-time
        status:
          type: string
          description: The current status of the batch operation. Valid values include 'PENDING', 'PROCESSING',
            'CANCELED', and 'COMPLETE'.
          enum:
          - CANCELED
          - COMPLETE
          - PENDING
          - PROCESSING
    BatchResponsePriceBookItemResponseWithErrors:
      required:
      - completedAt
      - results
      - startedAt
      - status
      type: object
      properties:
        completedAt:
          type: string
          description: The date and time when the batch operation was completed, in ISO 8601 format.
          format: date-time
        errors:
          type: array
          description: An array of errors encountered during the batch operation, each represented as
            a StandardError object.
          items:
            $ref: '#/components/schemas/StandardError'
        links:
          type: object
          additionalProperties:
            type: string
          description: A map of link names to associated URIs, providing additional context or actions
            related to the batch operation.
        numErrors:
          type: integer
          description: The number of errors encountered during the batch operation.
          format: int32
        requestedAt:
          type: string
          description: The date and time when the batch operation was requested, in ISO 8601 format.
          format: date-time
        results:
          type: array
          description: An array of results from the batch operation, each represented as a PriceBookItemResponse
            object.
          items:
            $ref: '#/components/schemas/PriceBookItemResponse'
        startedAt:
          type: string
          description: The date and time when the batch operation started, in ISO 8601 format.
          format: date-time
        status:
          type: string
          description: The current status of the batch operation. Valid values include 'PENDING', 'PROCESSING',
            'CANCELED', and 'COMPLETE'.
          enum:
          - CANCELED
          - COMPLETE
          - PENDING
          - PROCESSING
    CollectionResponsePriceBookItemResponseForwardPaging:
      required:
      - results
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/ForwardPaging'
        results:
          type: array
          description: An array of price book items, each represented by a PriceBookItemResponse object.
          items:
            $ref: '#/components/schemas/PriceBookItemResponse'
    CollectionResponsePriceBookResponseForwardPaging:
      required:
      - results
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/ForwardPaging'
        results:
          type: array
          description: An array of price book objects, each represented by the PriceBookResponse schema.
          items:
            $ref: '#/components/schemas/PriceBookResponse'
    Error:
      required:
      - category
      - correlationId
      - message
      type: object
      properties:
        category:
          type: string
          description: The error category, represented as a string.
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: An object providing context about the error condition. It contains additional properties,
            each being an array of strings.
          example: '{invalidPropertyName=[propertyValue], missingScopes=[scope1, scope2]}'
        correlationId:
          type: string
          description: A unique identifier for the request, represented as a UUID string. Include this
            value with any error reports or support tickets.
          format: uuid
          example: aeb5f871-7f07-4993-9211-075dc63e7cbf
        errors:
          type: array
          description: An array providing further information about the error, with each item being an
            ErrorDetail object.
          items:
            $ref: '#/components/schemas/ErrorDetail'
        links:
          type: object
          additionalProperties:
            type: string
          description: An object that maps link names to associated URIs containing documentation about
            the error or recommended remediation steps. Each property is a string.
        message:
          type: string
          description: A human readable message describing the error along with remediation steps where
            appropriate. It is a string.
          example: An error occurred
        subCategory:
          type: string
          description: A specific category that contains more specific detail about the error, represented
            as a string.
      description: Represents an error response returned by the API when an operation fails. This component
        is used in various endpoints to provide detailed information about the error encountered.
      example:
        message: Invalid input (details will vary based on the error)
        correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
        category: VALIDATION_ERROR
        links:
          knowledge-base: https://www.hubspot.com/products/service/knowledge-base
    ErrorDetail:
      required:
      - message
      type: object
      properties:
        code:
          type: string
          description: The status code associated with the error detail.
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Context about the error condition, which may include additional information such
            as missing scopes or invalid property names.
          example: '{missingScopes=[scope1, scope2]}'
        in:
          type: string
          description: The name of the field or parameter in which the error was found.
        message:
          type: string
          description: A human readable message describing the error along with remediation steps where
            appropriate. This is a required property.
        subCategory:
          type: string
          description: 

# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hubspot/refs/heads/main/openapi/hubspot-commerce-price-books-api-openapi.yml