> ## 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: 67f7d2e6-d3c5-4e13-be26-be6e7005aaf0
---
# Retrieve change
> Retrieve details of a specific contract change using its unique identifier. This endpoint is useful for obtaining information about the status and type of a contract change, as well as any associated line item changes. It requires the 'contracts-read' scope for access.
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 GET /commerce/contracts/2026-09-beta/changes/{changeId}
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/changes/{changeId}:
get:
tags:
- Changes
summary: Retrieve change
description: >-
Retrieve details of a specific contract change using its unique
identifier. This endpoint is useful for obtaining information about the
status and type of a contract change, as well as any associated line
item changes. It requires the 'contracts-read' scope for access.
operationId: get-/commerce/contracts/2026-09-beta/changes/{changeId}
parameters:
- name: changeId
in: path
description: The unique identifier of the contract change to retrieve.
required: true
style: simple
explode: false
schema:
type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ContractChangeResponse'
default:
$ref: '#/components/responses/Error'
description: ''
security:
- oauth2:
- contracts-read
components:
schemas:
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
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
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.
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}
)}