> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
---
id: 5c05f0db-2f41-41a5-a86d-b2672261fed8
---
# Create Change
> Create a new change for a specific contract in your HubSpot account. This endpoint allows you to propose modifications to an existing contract, such as adding, updating, or removing line items. The changes can be specified in the request body and are associated with the contract identified by the contractId path parameter.
export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
;
};
## OpenAPI
````yaml specs/2026-09-beta/commerce-contracts-v2026-09-beta.json POST /commerce/contracts/2026-09-beta/contracts/{contractId}/changes
openapi: 3.0.1
info:
title: Commerce Contracts
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
security: []
tags:
- name: Basic
- name: Changes
paths:
/commerce/contracts/2026-09-beta/contracts/{contractId}/changes:
post:
tags:
- Changes
summary: Create Change
description: >-
Create a new change for a specific contract in your HubSpot account.
This endpoint allows you to propose modifications to an existing
contract, such as adding, updating, or removing line items. The changes
can be specified in the request body and are associated with the
contract identified by the contractId path parameter.
operationId: post-/commerce/contracts/2026-09-beta/contracts/{contractId}/changes
parameters:
- name: contractId
in: path
description: >-
The unique identifier of the contract for which the change is being
created.
required: true
style: simple
explode: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContractChangeCreateRequest'
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/ContractChangeResponse'
default:
$ref: '#/components/responses/Error'
description: ''
security:
- oauth2:
- revenue-contracts-public-api-write
components:
schemas:
ContractChangeCreateRequest:
properties: {}
oneOf:
- $ref: '#/components/schemas/DirectContractChangeCreateRequest'
- $ref: '#/components/schemas/QuoteContractChangeCreateRequest'
ContractChangeResponse:
required:
- contractId
- id
- lineItemChanges
- prorating
- status
- type
type: object
properties:
contractId:
type: string
description: The unique identifier of the contract associated with this change.
createdAt:
type: string
description: >-
The date and time when this contract change was created, in ISO 8601
format.
format: date-time
effectiveDate:
type: string
description: >-
The date when the contract change becomes effective, in ISO 8601
date format.
format: date
id:
type: string
description: The unique identifier for this contract change.
lineItemChanges:
type: array
description: An array of line item changes associated with this contract change.
items:
$ref: '#/components/schemas/LineItemChangeResponse'
name:
type: string
description: The name of the contract change.
prorating:
type: boolean
description: A boolean indicating whether the contract change involves prorating.
quoteId:
type: string
description: >-
The unique identifier of the quote associated with this contract
change, if applicable.
status:
type: string
description: >-
The current status of the contract change. Valid values include
'DRAFT', 'PROPOSED', 'ACCEPTED', 'CANCELED', 'FAILED', and
'EXPIRED'.
enum:
- ACCEPTED
- CANCELED
- DRAFT
- EXPIRED
- FAILED
- PROPOSED
type:
type: string
description: >-
The type of contract change, which can be either 'DIRECT' or
'QUOTE'.
enum:
- DIRECT
- QUOTE
updatedAt:
type: string
description: >-
The date and time when this contract change was last updated, in ISO
8601 format.
format: date-time
DirectContractChangeCreateRequest:
required:
- autoAccept
- lineItemChanges
- prorating
- type
type: object
properties:
autoAccept:
type: boolean
description: >-
A boolean indicating whether the contract change should be
automatically accepted.
effectiveDate:
type: string
description: >-
The date when the contract change becomes effective, formatted as a
date string.
format: date
lineItemChanges:
type: array
description: >-
An array of line item changes to be applied to the contract. Each
item in the array is a reference to a LineItemChangeRequest.
items:
$ref: '#/components/schemas/LineItemChangeRequest'
name:
type: string
description: A string representing the name of the contract change.
prorating:
type: boolean
description: A boolean indicating whether the contract change should be prorated.
type:
type: string
description: >-
A string representing the type of contract change. The default and
only valid value is 'DIRECT'.
default: DIRECT
enum:
- DIRECT
x-hubspot-sub-type-impl: true
QuoteContractChangeCreateRequest:
required:
- prorating
- quoteTemplateId
- type
type: object
properties:
dealId:
type: string
description: >-
A string representing the ID of the deal associated with the
contract change.
dealPipeline:
type: string
description: >-
A string representing the pipeline of the deal associated with the
contract change.
dealStage:
type: string
description: >-
A string representing the stage of the deal associated with the
contract change.
effectiveDate:
type: string
description: >-
A string representing the date when the contract change becomes
effective, in 'date' format.
format: date
name:
type: string
description: A string representing the name of the contract change.
prorating:
type: boolean
description: A boolean indicating whether the contract change should be prorated.
quoteTemplateId:
type: string
description: >-
A string that identifies the quote template associated with the
contract change.
type:
type: string
description: >-
A string that specifies the type of contract change. The default
value is 'QUOTE'.
default: QUOTE
enum:
- QUOTE
x-hubspot-sub-type-impl: true
LineItemChangeResponse:
required:
- action
- rampKey
type: object
properties:
action:
type: string
description: >-
The type of action performed on the line item. Valid values include
'ADD', 'UPDATE', and 'REMOVE'.
enum:
- ADD
- REMOVE
- UPDATE
lineItemUpdate:
$ref: '#/components/schemas/LineItemChangeUpdate'
rampKey:
type: string
description: >-
A unique identifier for the ramp associated with the line item
change, formatted as a UUID.
format: uuid
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: >-
Context about the error condition, represented as an object with
additional properties that are arrays of strings.
example: >-
{invalidPropertyName=[propertyValue], missingScopes=[scope1,
scope2]}
correlationId:
type: string
description: >-
A unique identifier for the request. Include this value with any
error reports or support tickets. It is a string in UUID format.
format: uuid
example: aeb5f871-7f07-4993-9211-075dc63e7cbf
errors:
type: array
description: >-
Further information about the error, provided as an array of
ErrorDetail objects.
items:
$ref: '#/components/schemas/ErrorDetail'
links:
type: object
additionalProperties:
type: string
description: >-
A map of link names to associated URIs containing documentation
about the error or recommended remediation steps, represented as an
object with additional properties that are strings.
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:
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
LineItemChangeRequest:
required:
- action
type: object
properties:
action:
type: string
description: >-
The action to be performed on the line item. Valid values include
'ADD', 'UPDATE', and 'REMOVE'.
enum:
- ADD
- REMOVE
- UPDATE
lineItemAdd:
description: >-
An object representing the details of the line item to be added.
This can be one of several types, such as a custom line item, a line
item from a product, or a cloned line item.
oneOf:
- $ref: '#/components/schemas/LineItemCustomCreateRequest'
- $ref: '#/components/schemas/LineItemFromProductCreateRequest'
- $ref: '#/components/schemas/LineItemCloneCreateRequest'
lineItemUpdate:
$ref: '#/components/schemas/LineItemChangeUpdate'
rampKey:
type: string
description: >-
A unique identifier for the ramp associated with the line item,
formatted as a UUID.
format: uuid
LineItemChangeUpdate:
required:
- allowBuyerSelectedQuantity
- billingCycleAnchorDate
- billingStartDelayDays
- billingStartDelayMonths
- buyerSelectedQuantityMax
- buyerSelectedQuantityMin
- description
- discount
- discountPercentage
- externalId
- images
- isEditablePrice
- isOptional
- lineItemCurrencyCode
- name
- positionOnQuote
- priceBookId
- pricing
- productType
- quantity
- recurringBillingEndDate
- recurringBillingFrequency
- recurringBillingPeriod
- recurringBillingStartDate
- richTextDescription
- sku
- variantId
type: object
properties:
allowBuyerSelectedQuantity:
type: object
properties: {}
description: >-
An object indicating whether the buyer can select the quantity of
the line item.
billingCycleAnchorDate:
type: object
properties: {}
description: >-
An object representing the anchor date for the billing cycle of the
line item.
billingStartDelayDays:
type: object
properties: {}
description: >-
An object representing the number of days to delay the start of
billing for the line item.
billingStartDelayMonths:
type: object
properties: {}
description: >-
An object representing the number of months to delay the start of
billing for the line item.
buyerSelectedQuantityMax:
type: object
properties: {}
description: >-
An object representing the maximum quantity the buyer can select for
the line item.
buyerSelectedQuantityMin:
type: object
properties: {}
description: >-
An object representing the minimum quantity the buyer can select for
the line item.
description:
type: object
properties: {}
description: An object representing the description of the line item.
discount:
type: object
properties: {}
description: An object representing the discount applied to the line item.
discountPercentage:
type: object
properties: {}
description: >-
An object representing the discount percentage applied to the line
item.
externalId:
type: object
properties: {}
description: An object representing an external identifier for the line item.
images:
type: object
properties: {}
description: An object representing the images associated with the line item.
isEditablePrice:
type: object
properties: {}
description: An object indicating whether the price of the line item is editable.
isOptional:
type: object
properties: {}
description: An object indicating whether the line item is optional.
lineItemCurrencyCode:
type: object
properties: {}
description: An object representing the currency code for the line item.
name:
type: object
properties: {}
description: An object representing the name of the line item.
positionOnQuote:
type: object
properties: {}
description: An object representing the position of the line item on the quote.
priceBookId:
type: object
properties: {}
description: >-
An object representing the price book ID associated with the line
item.
pricing:
type: object
properties: {}
description: An object representing the pricing details of the line item.
productType:
type: object
properties: {}
description: An object representing the type of product for the line item.
quantity:
type: object
properties: {}
description: An object representing the quantity of the line item.
recurringBillingEndDate:
type: object
properties: {}
description: >-
An object representing the end date for recurring billing of the
line item.
recurringBillingFrequency:
type: object
properties: {}
description: >-
An object representing the frequency of recurring billing for the
line item.
recurringBillingPeriod:
type: object
properties: {}
description: >-
An object representing the period of recurring billing for the line
item.
recurringBillingStartDate:
type: object
properties: {}
description: >-
An object representing the start date for recurring billing of the
line item.
richTextDescription:
type: object
properties: {}
description: An object representing the rich text description of the line item.
sku:
type: object
properties: {}
description: >-
An object representing the stock keeping unit (SKU) of the line
item.
variantId:
type: object
properties: {}
description: An object representing the variant ID of the line item.
ErrorDetail:
required:
- message
type: object
properties:
code:
type: string
description: >-
The status code associated with the error detail. This is a string
property.
context:
type: object
additionalProperties:
type: array
items:
type: string
description: >-
Context about the error condition, represented as an object. It can
include additional properties, each being an array of strings,
providing further context such as missing scopes.
example: '{missingScopes=[scope1, scope2]}'
in:
type: string
description: >-
The name of the field or parameter in which the error was found.
This is a string property.
message:
type: string
description: >-
A human readable message describing the error along with remediation
steps where appropriate. It is a required string property.
subCategory:
type: string
description: >-
A specific category that contains more specific detail about the
error. This is a string property.
LineItemCustomCreateRequest:
title: CUSTOM
required:
- mode
- name
- pricing
- quantity
type: object
properties:
allowBuyerSelectedQuantity:
type: boolean
description: >-
A boolean specifying if the buyer can select the quantity of the
line item.
billingCycleAnchorDate:
type: string
description: >-
A string in date format representing the anchor date for the billing
cycle.
format: date
billingStartDelayDays:
type: integer
description: >-
An integer indicating the number of days to delay the start of
billing.
format: int32
billingStartDelayMonths:
type: integer
description: >-
An integer specifying the number of months to delay the start of
billing.
format: int32
buyerSelectedQuantityMax:
type: number
description: A number representing the maximum quantity the buyer can select.
buyerSelectedQuantityMin:
type: number
description: A number representing the minimum quantity the buyer can select.
description:
type: string
description: A string providing a description of the line item.
discount:
type: number
description: A number representing the discount applied to the line item.
discountPercentage:
type: number
description: >-
A number indicating the percentage discount applied to the line
item.
externalId:
type: string
description: A string containing an external identifier for the line item.
images:
type: string
description: >-
A string containing URLs or references to images associated with the
line item.
isEditablePrice:
type: boolean
description: A boolean indicating if the price of the line item is editable.
isOptional:
type: boolean
description: A boolean indicating whether the line item is optional.
lineItemCurrencyCode:
type: string
description: A string representing the currency code for the line item.
mode:
type: string
description: >-
A string indicating the mode of the line item, with a default value
of 'CUSTOM'.
default: CUSTOM
enum:
- CUSTOM
name:
type: string
description: A string representing the name of the line item.
positionOnQuote:
type: integer
description: An integer indicating the position of the line item on a quote.
format: int32
priceBookId:
type: string
description: >-
A string representing the ID of the price book associated with the
line item.
pricing:
$ref: '#/components/schemas/PricingFullUpdateRequest'
productId:
type: string
description: A string identifying the product associated with the line item.
productType:
type: string
description: A string indicating the type of product for the line item.
quantity:
type: number
description: A number specifying the quantity of the line item.
recurringBillingEndDate:
type: string
description: >-
A string in date format indicating the end date of recurring
billing.
format: date
recurringBillingFrequency:
type: string
description: >-
A string specifying the frequency of recurring billing for the line
item, with valid values including 'ANNUALLY', 'BIWEEKLY', 'MONTHLY',
'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
recurringBillingPeriod:
type: string
description: A string specifying the period of recurring billing.
recurringBillingStartDate:
type: string
description: >-
A string in date format representing the start date of recurring
billing.
format: date
richTextDescription:
type: string
description: A string containing a rich text description of the line item.
sku:
type: string
description: A string representing the stock keeping unit (SKU) of the line item.
variantId:
type: string
description: A string identifying the variant of the product for the line item.
x-hubspot-sub-type-impl: true
LineItemFromProductCreateRequest:
title: FROM_PRODUCT
required:
- allowBuyerSelectedQuantity
- billingCycleAnchorDate
- billingStartDelayDays
- billingStartDelayMonths
- buyerSelectedQuantityMax
- buyerSelectedQuantityMin
- description
- discount
- discountPercentage
- externalId
- images
- isEditablePrice
- isOptional
- lineItemCurrencyCode
- mode
- name
- positionOnQuote
- priceBookId
- pricing
- productId
- productType
- quantity
- recurringBillingEndDate
- recurringBillingFrequency
- recurringBillingPeriod
- recurringBillingStartDate
- richTextDescription
- sku
- variantId
type: object
properties:
allowBuyerSelectedQuantity:
type: object
properties: {}
description: >-
An object indicating whether the buyer can select the quantity of
the line item.
billingCycleAnchorDate:
type: object
properties: {}
description: An object representing the anchor date for the billing cycle.
billingStartDelayDays:
type: object
properties: {}
description: >-
An object representing the number of days to delay the start of
billing.
billingStartDelayMonths:
type: object
properties: {}
description: >-
An object representing the number of months to delay the start of
billing.
buyerSelectedQuantityMax:
type: object
properties: {}
description: An object representing the maximum quantity the buyer can select.
buyerSelectedQuantityMin:
type: object
properties: {}
description: An object representing the minimum quantity the buyer can select.
description:
type: object
properties: {}
description: An object representing the description of the line item.
discount:
type: object
properties: {}
description: An object representing the discount applied to the line item.
discountPercentage:
type: object
properties: {}
description: >-
An object representing the percentage discount applied to the line
item.
externalId:
type: object
properties: {}
description: An object representing an external identifier for the line item.
images:
type: object
properties: {}
description: An object representing the images associated with the line item.
isEditablePrice:
type: object
properties: {}
description: An object indicating whether the price of the line item is editable.
isOptional:
type: object
properties: {}
description: An object indicating whether the line item is optional.
lineItemCurrencyCode:
type: object
properties: {}
description: An object representing the currency code for the line item.
mode:
type: string
description: >-
A string indicating the mode of the line item creation, defaulting
to 'FROM_PRODUCT'.
default: FROM_PRODUCT
enum:
- FROM_PRODUCT
name:
type: object
properties: {}
description: An object representing the name of the line item.
positionOnQuote:
type: object
properties: {}
description: An object representing the position of the line item on the quote.
priceBookId:
type: object
properties: {}
description: >-
An object representing the ID of the price book associated with the
line item.
pricing:
type: object
properties: {}
description: An object representing the pricing details of the line item.
productId:
type: string
description: >-
A string representing the ID of the product associated with the line
item.
productType:
type: object
properties: {}
description: An object representing the type of product for the line item.
quantity:
type: object
properties: {}
description: An object representing the quantity of the product in the line item.
recurringBillingEndDate:
type: object
properties: {}
description: An object representing the end date for recurring billing.
recurringBillingFrequency:
type: object
properties: {}
description: >-
An object representing the frequency of recurring billing for the
line item.
recurringBillingPeriod:
type: object
properties: {}
description: An object representing the period of recurring billing.
recurringBillingStartDate:
type: object
properties: {}
description: An object representing the start date for recurring billing.
richTextDescription:
type: object
properties: {}
description: An object representing the rich text description of the line item.
sku:
type: object
properties: {}
description: An object representing the stock keeping unit (SKU) of the product.
variantId:
type: object
properties: {}
description: An object representing the variant ID of the product.
x-hubspot-sub-type-impl: true
LineItemCloneCreateRequest:
title: CLONE
required:
- allowBuyerSelectedQuantity
- billingCycleAnchorDate
- billingStartDelayDays
- billingStartDelayMonths
- buyerSelectedQuantityMax
- buyerSelectedQuantityMin
- description
- discount
- discountPercentage
- externalId
- images
- isEditablePrice
- isOptional
- lineItemCurrencyCode
- mode
- name
- positionOnQuote
- priceBookId
- pricing
- productType
- quantity
- recurringBillingEndDate
- recurringBillingFrequency
- recurringBillingPeriod
- recurringBillingStartDate
- richTextDescription
- sku
- sourceLineItemId
- variantId
type: object
properties:
allowBuyerSelectedQuantity:
type: object
properties: {}
description: >-
An object indicating whether the buyer can select the quantity of
the line item.
billingCycleAnchorDate:
type: object
properties: {}
description: >-
An object representing the anchor date for the billing cycle of the
line item.
billingStartDelayDays:
type: object
properties: {}
description: >-
An object representing the number of days to delay the start of
billing for the line item.
billingStartDelayMonths:
type: object
properties: {}
description: >-
An object representing the number of months to delay the start of
billing for the line item.
buyerSelectedQuantityMax:
type: object
properties: {}
description: >-
An object representing the maximum quantity that the buyer can
select for the line item.
buyerSelectedQuantityMin:
type: object
properties: {}
description: >-
An object representing the minimum quantity that the buyer can
select for the line item.
description:
type: object
properties: {}
description: An object representing the description of the line item.
discount:
type: object
properties: {}
description: An object representing the discount applied to the line item.
discountPercentage:
type: object
properties: {}
description: >-
An object representing the percentage discount applied to the line
item.
externalId:
type: object
properties: {}
description: An object representing an external identifier for the line item.
images:
type: object
properties: {}
description: An object representing the images associated with the line item.
isEditablePrice:
type: object
properties: {}
description: An object indicating whether the price of the line item is editable.
isOptional:
type: object
properties: {}
description: An object indicating whether the line item is optional.
lineItemCurrencyCode:
type: object
properties: {}
description: An object representing the currency code for the line item.
mode:
type: string
description: >-
A string indicating the mode of the line item creation, which is
'CLONE' by default.
default: CLONE
enum:
- CLONE
name:
type: object
properties: {}
description: An object representing the name of the line item.
positionOnQuote:
type: object
properties: {}
description: An object representing the position of the line item on the quote.
priceBookId:
type: object
properties: {}
description: >-
An object representing the ID of the price book associated with the
line item.
pricing:
type: object
properties: {}
description: An object representing the pricing details of the line item.
productType:
type: object
properties: {}
description: An object representing the type of product for the line item.
quantity:
type: object
properties: {}
description: An object representing the quantity of the line item.
recurringBillingEndDate:
type: object
properties: {}
description: >-
An object representing the end date for recurring billing of the
line item.
recurringBillingFrequency:
type: object
properties: {}
description: >-
An object representing the frequency of recurring billing for the
line item.
recurringBillingPeriod:
type: object
properties: {}
description: >-
An object representing the billing period for recurring billing of
the line item.
recurringBillingStartDate:
type: object
properties: {}
description: >-
An object representing the start date for recurring billing of the
line item.
richTextDescription:
type: object
properties: {}
description: An object representing the rich text description of the line item.
sku:
type: object
properties: {}
description: >-
An object representing the stock keeping unit (SKU) of the line
item.
sourceLineItemId:
type: string
description: A string representing the ID of the source line item being cloned.
variantId:
type: object
properties: {}
description: An object representing the variant ID of the line item.
x-hubspot-sub-type-impl: true
PricingFullUpdateRequest:
required:
- prices
- pricingModel
type: object
properties:
prices:
type: array
description: >-
An array of PriceUpdateEntry objects, each representing a price
entry with details such as currency code and price.
items:
$ref: '#/components/schemas/PriceUpdateEntry'
pricingModel:
type: string
description: >-
A string representing the pricing model used. Valid values include
'FLAT', 'GRADUATED', 'STAIRSTEP', and 'VOLUME'.
enum:
- FLAT
- GRADUATED
- STAIRSTEP
- VOLUME
PriceUpdateEntry:
required:
- currencyCode
- price
type: object
properties:
currencyCode:
type: string
description: >-
The currency code in which the price is denominated, represented as
a string.
maxQuantity:
type: string
description: >-
The maximum quantity for which this price is applicable, represented
as a string.
price:
type: object
properties: {}
description: >-
The price value associated with the currency code, represented as an
object.
responses:
Error:
description: An error occurred.
content:
'*/*':
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://app.hubspot.com/oauth/authorize
tokenUrl: https://api.hubapi.com/oauth/v1/token
scopes:
contracts-read: ''
revenue-contracts-public-api-write: ''
````
{product.name} -
{product.level}
)}