{ "openapi" : "3.0.1", "info" : { "title" : "Commerce Price Books", "description" : "Basepom for all HubSpot Projects", "version" : "2026-09-beta", "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-beta/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-beta/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", "example" : null } }, { "name" : "archived", "in" : "query", "description" : "Whether to return only results that have been archived.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "boolean", "example" : null } }, { "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", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CollectionResponsePriceBookResponseForwardPaging" }, "example" : null } } }, "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-beta/price-books", "parameters" : [ ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PriceBookCreateRequest" }, "example" : null } }, "required" : true }, "responses" : { "201" : { "description" : "successful operation", "headers" : { "Location" : { "description" : "URL of the newly created resource", "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PriceBookResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "price-book-write" ] } ] } }, "/commerce/price-books/2026-09-beta/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-beta/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", "example" : null } }, { "name" : "archived", "in" : "query", "description" : "Whether to return only results that have been archived.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "boolean", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PriceBookResponse" }, "example" : null } } }, "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-beta/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", "example" : null } } ], "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-beta/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", "example" : null } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PriceBookUpdateRequest" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PriceBookResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "price-book-write" ] } ] } }, "/commerce/price-books/2026-09-beta/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-beta/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", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PriceBookResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "price-book-write" ] } ] } }, "/commerce/price-books/2026-09-beta/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-beta/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", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PriceBookResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "price-book-write" ] } ] } }, "/commerce/price-books/2026-09-beta/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-beta/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", "example" : null } }, { "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", "example" : null } }, { "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", "example" : null } }, { "name" : "properties", "in" : "query", "description" : "A list of property names to include in the response.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CollectionResponsePriceBookItemResponseForwardPaging" }, "example" : null } } }, "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-beta/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", "example" : null } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PriceBookAddProductRequest" }, "example" : null } }, "required" : true }, "responses" : { "201" : { "description" : "successful operation", "headers" : { "Location" : { "description" : "URL of the newly created resource", "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PriceBookItemResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "inbounddb-product-library-read", "price-book-write" ] } ] } }, "/commerce/price-books/2026-09-beta/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-beta/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", "example" : null } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BatchInputSimplePublicObjectId" }, "example" : null } }, "required" : true }, "responses" : { "204" : { "description" : "No content", "content" : { } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "price-book-write" ] } ] } }, "/commerce/price-books/2026-09-beta/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-beta/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", "example" : null } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BatchInputPriceBookAddProductRequest" }, "example" : null } }, "required" : true }, "responses" : { "201" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BatchResponsePriceBookItemResponse" }, "example" : null } } }, "207" : { "description" : "multiple statuses", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BatchResponsePriceBookItemResponseWithErrors" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "inbounddb-product-library-read", "price-book-write" ] } ] } }, "/commerce/price-books/2026-09-beta/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-beta/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", "example" : null } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BatchInputPriceBookItemBatchUpdateInput" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BatchResponsePriceBookItemResponse" }, "example" : null } } }, "207" : { "description" : "multiple statuses", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BatchResponsePriceBookItemResponseWithErrors" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "price-book-write" ] } ] } }, "/commerce/price-books/2026-09-beta/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-beta/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", "example" : null } }, { "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", "example" : null } }, { "name" : "archived", "in" : "query", "description" : "Whether to return only results that have been archived.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "boolean", "example" : null } }, { "name" : "properties", "in" : "query", "description" : "A list of property names to include in the response.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PriceBookItemResponse" }, "example" : null } } }, "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-beta/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", "example" : null } }, { "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", "example" : null } } ], "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-beta/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", "example" : null } }, { "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", "example" : null } }, { "name" : "archived", "in" : "query", "description" : "Whether to return only results that have been archived.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "boolean", "example" : null } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PriceBookItemUpdateRequest" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PriceBookItemResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "inbounddb-product-library-read", "price-book-write" ] } ] } }, "/commerce/price-books/2026-09-beta/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-beta/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", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PriceBookValidateResponse" }, "example" : null } } }, "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.", "example" : null, "items" : { "$ref" : "#/components/schemas/PriceBookAddProductRequest" } } }, "example" : null }, "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.", "example" : null, "items" : { "$ref" : "#/components/schemas/PriceBookItemBatchUpdateInput" } } }, "example" : null }, "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.", "example" : null, "items" : { "$ref" : "#/components/schemas/SimplePublicObjectId" } } }, "example" : null }, "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", "example" : null }, "links" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "description" : "A map of link names to associated URIs providing additional information or actions related to the batch operation.", "example" : null }, "requestedAt" : { "type" : "string", "description" : "The date and time when the batch operation was requested, in ISO 8601 format.", "format" : "date-time", "example" : null }, "results" : { "type" : "array", "description" : "An array of PriceBookItemResponse objects representing the individual results of the batch operation.", "example" : null, "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", "example" : null }, "status" : { "type" : "string", "description" : "The current status of the batch operation. Valid values include 'PENDING', 'PROCESSING', 'CANCELED', and 'COMPLETE'.", "example" : null, "enum" : [ "CANCELED", "COMPLETE", "PENDING", "PROCESSING" ] } }, "example" : null }, "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", "example" : null }, "errors" : { "type" : "array", "description" : "An array of errors encountered during the batch operation, each represented as a StandardError object.", "example" : null, "items" : { "$ref" : "#/components/schemas/StandardError" } }, "links" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "description" : "A map of link names to associated URIs, providing additional context or actions related to the batch operation.", "example" : null }, "numErrors" : { "type" : "integer", "description" : "The number of errors encountered during the batch operation.", "format" : "int32", "example" : null }, "requestedAt" : { "type" : "string", "description" : "The date and time when the batch operation was requested, in ISO 8601 format.", "format" : "date-time", "example" : null }, "results" : { "type" : "array", "description" : "An array of results from the batch operation, each represented as a PriceBookItemResponse object.", "example" : null, "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", "example" : null }, "status" : { "type" : "string", "description" : "The current status of the batch operation. Valid values include 'PENDING', 'PROCESSING', 'CANCELED', and 'COMPLETE'.", "example" : null, "enum" : [ "CANCELED", "COMPLETE", "PENDING", "PROCESSING" ] } }, "example" : null }, "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.", "example" : null, "items" : { "$ref" : "#/components/schemas/PriceBookItemResponse" } } }, "example" : null }, "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.", "example" : null, "items" : { "$ref" : "#/components/schemas/PriceBookResponse" } } }, "example" : null }, "Error" : { "required" : [ "category", "correlationId", "message" ], "type" : "object", "properties" : { "category" : { "type" : "string", "description" : "The error category, represented as a string.", "example" : null }, "context" : { "type" : "object", "additionalProperties" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } }, "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.", "example" : null, "items" : { "$ref" : "#/components/schemas/ErrorDetail" } }, "links" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "description" : "An object that maps link names to associated URIs containing documentation about the error or recommended remediation steps. Each property is a string.", "example" : null }, "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.", "example" : null } }, "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.", "example" : null }, "context" : { "type" : "object", "additionalProperties" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } }, "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.", "example" : null }, "message" : { "type" : "string", "description" : "A human readable message describing the error along with remediation steps where appropriate. This is a required property.", "example" : null }, "subCategory" : { "type" : "string", "description" : "A specific category that contains more specific detail about the error.", "example" : null } }, "example" : null }, "ForwardPaging" : { "type" : "object", "properties" : { "next" : { "$ref" : "#/components/schemas/NextPage" } }, "example" : null }, "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.", "example" : null }, "link" : { "type" : "string", "description" : "A string URL that provides a direct link to the next page of results.", "example" : null } }, "description" : "Specifies the paging information needed to retrieve the next set of results in a paginated API response", "example" : null }, "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.", "example" : null } }, "example" : null }, "PriceBookCreateRequest" : { "required" : [ "customProperties", "name", "supportedCurrencies" ], "type" : "object", "properties" : { "customProperties" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "description" : "An object containing custom properties for the price book. Each property is a key-value pair where the key is a string and the value is also a string. This is a required property.", "example" : null }, "description" : { "type" : "string", "description" : "A description of the price book. This is an optional string property.", "example" : null }, "name" : { "type" : "string", "description" : "The name of the price book. It is a required string property.", "example" : null }, "supportedCurrencies" : { "type" : "array", "description" : "An array of strings representing the currencies supported by the price book. This is a required property.", "example" : null, "items" : { "type" : "string", "example" : null } } }, "example" : null }, "PriceBookItemBatchUpdateInput" : { "required" : [ "id", "properties" ], "type" : "object", "properties" : { "id" : { "type" : "string", "description" : "The unique identifier for the price book item to be updated. It is a string.", "example" : null }, "properties" : { "$ref" : "#/components/schemas/PriceBookItemUpdateRequest" } }, "example" : null }, "PriceBookItemResponse" : { "required" : [ "customProperties", "id", "productId" ], "type" : "object", "properties" : { "archived" : { "type" : "boolean", "description" : "A boolean indicating whether the price book item is archived.", "example" : null }, "archivedAt" : { "type" : "string", "description" : "The date and time when the price book item was archived, in ISO 8601 format.", "format" : "date-time", "example" : null }, "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'.", "example" : null, "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.", "example" : null }, "costOfGoodsSold" : { "type" : "string", "description" : "The cost of goods sold for the price book item.", "example" : null }, "createdAt" : { "type" : "string", "description" : "The date and time when the price book item was created, in ISO 8601 format.", "format" : "date-time", "example" : null }, "customProperties" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "description" : "A map of custom property names to their values for the price book item.", "example" : null }, "description" : { "type" : "string", "description" : "A description of the price book item.", "example" : null }, "id" : { "type" : "string", "description" : "The unique identifier for the price book item.", "example" : null }, "images" : { "type" : "string", "description" : "A string representing images associated with the price book item.", "example" : null }, "name" : { "type" : "string", "description" : "The name of the price book item.", "example" : null }, "priceBookId" : { "type" : "string", "description" : "The unique identifier for the price book containing this item.", "example" : null }, "pricing" : { "$ref" : "#/components/schemas/Pricing" }, "productClassification" : { "type" : "string", "description" : "The classification of the product. Valid values include 'BUNDLE', 'STANDALONE', and 'VARIANT'.", "example" : null, "enum" : [ "BUNDLE", "STANDALONE", "VARIANT" ] }, "productId" : { "type" : "string", "description" : "The unique identifier for the product associated with the price book item.", "example" : null }, "productType" : { "type" : "string", "description" : "The type of product. Valid values include 'INVENTORY', 'NON_INVENTORY', and 'SERVICE'.", "example" : null, "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'.", "example" : null, "enum" : [ "AUTOMATICALLY_RENEW", "FIXED" ] }, "sku" : { "type" : "string", "description" : "The stock keeping unit (SKU) of the price book item.", "example" : null }, "status" : { "type" : "string", "description" : "The current status of the price book item. Valid values include 'active' and 'inactive'.", "example" : null, "enum" : [ "active", "inactive" ] }, "taxCategory" : { "type" : "string", "description" : "The tax category of the price book item.", "example" : null }, "updatedAt" : { "type" : "string", "description" : "The date and time when the price book item was last updated, in ISO 8601 format.", "format" : "date-time", "example" : null }, "url" : { "type" : "string", "description" : "A URL associated with the price book item.", "example" : null } }, "example" : null }, "PriceBookItemUpdateRequest" : { "required" : [ "billingFrequency", "billingPeriod", "customProperties", "status" ], "type" : "object", "properties" : { "archived" : { "type" : "boolean", "description" : "A boolean indicating whether the price book item is archived.", "example" : null }, "billingFrequency" : { "type" : "object", "properties" : { }, "description" : "An object specifying the frequency at which billing occurs for the price book item.", "example" : null }, "billingPeriod" : { "type" : "object", "properties" : { }, "description" : "An object specifying the period over which billing occurs for the price book item.", "example" : null }, "customProperties" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "description" : "A map of custom property names to their values, allowing for additional customization of the price book item.", "example" : null }, "pricing" : { "$ref" : "#/components/schemas/PricingUpdateRequest" }, "status" : { "type" : "object", "properties" : { }, "description" : "An object indicating the current status of the price book item.", "example" : null } }, "example" : null }, "PriceBookResponse" : { "required" : [ "autoAssignmentEnabled", "countOfIncludedProducts", "customProperties", "id", "status", "supportedCurrencies" ], "type" : "object", "properties" : { "archived" : { "type" : "boolean", "description" : "A boolean indicating whether this price book is archived.", "example" : null }, "archivedAt" : { "type" : "string", "description" : "The date and time when this price book was archived.", "format" : "date-time", "example" : null }, "autoAssignmentEnabled" : { "type" : "boolean", "description" : "Indicates whether auto-assignment is enabled for the price book. A boolean value.", "example" : null }, "countOfIncludedProducts" : { "type" : "integer", "description" : "The number of products included in this price book.", "format" : "int32", "example" : null }, "createdAt" : { "type" : "string", "description" : "The date and time when this price book was created.", "format" : "date-time", "example" : null }, "customProperties" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "description" : "A map of custom property names to their values for this price book.", "example" : null }, "description" : { "type" : "string", "description" : "A description of the price book.", "example" : null }, "id" : { "type" : "string", "description" : "The unique identifier for this price book.", "example" : null }, "name" : { "type" : "string", "description" : "The name of the price book.", "example" : null }, "status" : { "type" : "string", "description" : "The current status of the price book. Valid values include 'ACTIVE' and 'INACTIVE'.", "example" : null, "enum" : [ "ACTIVE", "INACTIVE" ] }, "supportedCurrencies" : { "type" : "array", "description" : "An array of currency codes that this price book supports.", "example" : null, "items" : { "type" : "string", "example" : null } }, "updatedAt" : { "type" : "string", "description" : "The date and time when this price book was last updated.", "format" : "date-time", "example" : null } }, "example" : null }, "PriceBookUpdateRequest" : { "required" : [ "customProperties", "description", "name" ], "type" : "object", "properties" : { "customProperties" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "description" : "An object containing custom properties for the price book, where each key is a property name and the value is a string.", "example" : null }, "description" : { "type" : "object", "properties" : { }, "description" : "An object representing the description of the price book to be updated.", "example" : null }, "name" : { "type" : "object", "properties" : { }, "description" : "An object representing the name of the price book to be updated.", "example" : null }, "supportedCurrencies" : { "type" : "array", "description" : "An array of strings representing the currencies supported by the price book.", "example" : null, "items" : { "type" : "string", "example" : null } } }, "example" : null }, "PriceBookValidateResponse" : { "required" : [ "errors", "isValid" ], "type" : "object", "properties" : { "errors" : { "type" : "array", "description" : "An array of ErrorDetail objects providing information about any errors encountered during validation.", "example" : null, "items" : { "$ref" : "#/components/schemas/ErrorDetail" } }, "isValid" : { "type" : "boolean", "description" : "A boolean indicating whether the price book is valid.", "example" : null } }, "example" : null }, "PriceEntry" : { "required" : [ "currencyCode", "price" ], "type" : "object", "properties" : { "currencyCode" : { "type" : "string", "description" : "A string representing the currency in which the price is denominated.", "example" : null }, "maxQuantity" : { "type" : "integer", "description" : "A string specifying the maximum quantity for which this pricing entry is applicable.", "format" : "int32", "example" : null }, "price" : { "type" : "number", "description" : "A number indicating the price of the product or service.", "example" : null } }, "example" : null }, "PriceUpdateEntry" : { "required" : [ "currencyCode", "price" ], "type" : "object", "properties" : { "currencyCode" : { "type" : "string", "description" : "The currency code for the price, represented as a string.", "example" : null }, "maxQuantity" : { "type" : "integer", "description" : "The maximum quantity applicable for this price, represented as a string.", "format" : "int32", "example" : null }, "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.", "example" : null } }, "example" : null }, "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.", "example" : null, "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'.", "example" : null, "enum" : [ "FLAT", "GRADUATED", "STAIRSTEP", "VOLUME" ] } }, "example" : null }, "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.", "example" : null, "items" : { "$ref" : "#/components/schemas/PriceUpdateEntry" } } }, "example" : null }, "SimplePublicObjectId" : { "required" : [ "id" ], "type" : "object", "properties" : { "id" : { "type" : "string", "description" : "The unique identifier for this object, represented as a string.", "example" : "430001" } }, "description" : "Contains the Id of a Public Object", "example" : null }, "StandardError" : { "required" : [ "category", "context", "errors", "links", "message", "status" ], "type" : "object", "properties" : { "category" : { "type" : "string", "description" : "A string specifying the category of the error.", "example" : null }, "context" : { "type" : "object", "additionalProperties" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } }, "description" : "An object containing additional context about the error, with each key mapping to an array of strings.", "example" : null }, "errors" : { "type" : "array", "description" : "An array of ErrorDetail objects providing further information about the error.", "example" : null, "items" : { "$ref" : "#/components/schemas/ErrorDetail" } }, "id" : { "type" : "string", "description" : "A string representing the unique identifier of the error.", "example" : null }, "links" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "description" : "An object mapping link names to URIs that provide documentation or remediation steps related to the error.", "example" : null }, "message" : { "type" : "string", "description" : "A string containing a human-readable message that describes the error.", "example" : null }, "status" : { "type" : "string", "description" : "A string indicating the status of the error.", "example" : null }, "subCategory" : { "type" : "object", "properties" : { }, "description" : "An object providing more specific details about the error category.", "example" : null } }, "description" : "Ye olde error", "example" : null } }, "responses" : { "Error" : { "description" : "An error occurred.", "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/Error" }, "example" : null } } } }, "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" } }