HubSpot Items API

openapi: 3.2.0
info:
  title: Commerce Price Books Items API
  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: Items
paths:
  /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/{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
components:
  schemas:
    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'
    PricingUpdateRequest:
      required:
      - prices
      type: object
      properties:
        prices:
          type: array
          description: An array of PriceUpdateEntry objects, each representing the pricing details for a product, including the currency code and amount.
          items:
            $ref: '#/components/schemas/PriceUpdateEntry'
    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: A specific category that contains more specific detail about the error.
      description: Represents detailed information about an error that occurred in the API. This component is used to provide additional context and specifics about errors, typically as part of an error response.
    ForwardPaging:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/NextPage'
      description: Paging information for forward-only pagination. Contains the next page reference when more results are available; omitted or empty on the last page.
    Pricing:
      required:
      - prices
      - pricingModel
      type: object
      properties:
        prices:
          type: array
          description: An array of price entries, each detailing the amount and currency for a specific pricing tier.
          items:
            $ref: '#/components/schemas/PriceEntry'
        pricingModel:
          type: string
          description: 'The type of pricing model applied, which can be one of the following: ''FLAT'', ''GRADUATED'', ''STAIRSTEP'', or ''VOLUME''.'
          enum:
          - FLAT
          - GRADUATED
          - STAIRSTEP
          - VOLUME
    PriceBookItemUpdateRequest:
      required:
      - billingFrequency
      - billingPeriod
      - customProperties
      - status
      type: object
      properties:
        archived:
          type: boolean
          description: A boolean indicating whether the price book item is archived.
        billingFrequency:
          type: object
          properties: {}
          description: An object specifying the frequency at which billing occurs for the price book item.
        billingPeriod:
          type: object
          properties: {}
          description: An object specifying the period over which billing occurs for the price book item.
        customProperties:
          type: object
          additionalProperties:
            type: string
          description: A map of custom property names to their values, allowing for additional customization of the price book item.
        pricing:
          $ref: '#/components/schemas/PricingUpdateRequest'
        status:
          type: object
          properties: {}
          description: An object indicating the current status of the price book item.
    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
    PriceBookAddProductRequest:
      required:
      - productId
      type: object
      properties:
        productId:
          type: string
          description: The unique identifier of the product to be added to the price book. It is a string and is required.
    NextPage:
      required:
      - after
      type: object
      properties:
        after:
          type: string
          description: A string token used as a cursor for pagination to retrieve the next set of results.
        link:
          type: string
          description: A string URL that provides a direct link to the next page of results.
      description: Specifies the paging information needed to retrieve the next set of results in a paginated API response
    PriceEntry:
      required:
      - currencyCode
      - price
      type: object
      properties:
        currencyCode:
          type: string
          description: A string representing the currency in which the price is denominated.
        maxQuantity:
          type: integer
          description: A string specifying the maximum quantity for which this pricing entry is applicable.
          format: int32
        price:
          type: number
          description: A number indicating the price of the product or service.
    PriceUpdateEntry:
      required:
      - currencyCode
      - price
      type: object
      properties:
        currencyCode:
          type: string
          description: The currency code for the price, represented as a string.
        maxQuantity:
          type: integer
          description: The maximum quantity applicable for this price, represented as a string.
          format: int32
        price:
          type: object
          properties: {}
          description: An object representing the price details for the entry. The specific structure of this object is not detailed in the specification.
    PriceBookItemResponse:
      required:
      - customProperties
      - id
      - productId
      type: object
      properties:
        archived:
          type: boolean
          description: A boolean indicating whether the price book item is archived.
        archivedAt:
          type: string
          description: The date and time when the price book item was archived, in ISO 8601 format.
          format: date-time
        billingFrequency:
          type: string
          description: The frequency at which billing occurs for the price book item. Valid values include 'annually', 'biweekly', 'monthly', 'one_time', 'per_five_years', 'per_four_years', 'per_six_months', 'per_three_years', 'per_two_years', 'quarterly', and 'weekly'.
          enum:
          - ANNUALLY
          - BIWEEKLY
          - MONTHLY
          - PER_FIVE_YEARS
          - PER_FOUR_YEARS
          - PER_SIX_MONTHS
          - PER_THREE_YEARS
          - PER_TWO_YEARS
          - QUARTERLY
          - WEEKLY
        billingPeriod:
          type: string
          description: The billing period for the price book item.
        costOfGoodsSold:
          type: string
          description: The cost of goods sold for the price book item.
        createdAt:
          type: string
          description: The date and time when the price book item was created, in ISO 8601 format.
          format: date-time
        customProperties:
          type: object
          additionalProperties:
            type: string
          description: A map of custom property names to their values for the price book item.
        description:
          type: string
          description: A description of the price book item.
        id:
          type: string
          description: The unique identifier for the price book item.
        images:
          type: string
          description: A string representing images associated with the price book item.
        name:
          type: string
          description: The name of the price book item.
        priceBookId:
          type: string
          description: The unique identifier for the price book containing this item.
        pricing:
          $ref: '#/components/schemas/Pricing'
        productClassification:
          type: string
          description: The classification of the product. Valid values include 'BUNDLE', 'STANDALONE', and 'VARIANT'.
          enum:
          - BUNDLE
          - STANDALONE
          - VARIANT
        productId:
          type: string
          description: The unique identifier for the product associated with the price book item.
        productType:
          type: string
          description: The type of product. Valid values include 'INVENTORY', 'NON_INVENTORY', and 'SERVICE'.
          enum:
          - INVENTORY
          - NON_INVENTORY
          - SERVICE
        recurringBillingTerms:
          type: string
          description: The terms of recurring billing for the price book item. Valid values include 'AUTOMATICALLY_RENEW' and 'FIXED'.
          enum:
          - AUTOMATICALLY_RENEW
          - FIXED
        sku:
          type: string
          description: The stock keeping unit (SKU) of the price book item.
        status:
          type: string
          description: The current status of the price book item. Valid values include 'active' and 'inactive'.
          enum:
          - active
          - inactive
        taxCategory:
          type: string
          description: The tax category of the price book item.
        updatedAt:
          type: string
          description: The date and time when the price book item was last updated, in ISO 8601 format.
          format: date-time
        url:
          type: string
          description: A URL associated with the price book item.
  responses:
    Error:
      description: An error occurred.
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    developer_hapikey:
      type: apiKey
      name: hapikey
      in: query
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          tokenUrl: https://api.hubapi.com/oauth/v1/token
          scopes:
            crm.objects.products.read: ''
            price-book-read: ''
            price-book-write: ''
    private_apps:
      type: apiKey
      name: private-app
      in: header
    private_apps_legacy:
      type: apiKey
      name: private-app-legacy
      in: header
x-hubspot-product-tier-requirements:
  marketing: FREE
  sales: FREE
  service: FREE
  cms: FREE
  commerce: FREE
  crmHub: FREE
  dataHub: FREE