> ## 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: e5eed599-7c26-4dcd-acac-ecc2d6f86f45
---
# Update contract
> Update an existing contract in your HubSpot account using the specified contract ID. This operation allows you to modify details of a contract, such as billing information, payment terms, and other properties. Ensure that the contract ID is valid and that all required fields in the request body are provided.
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 PATCH /commerce/contracts/2026-09-beta/contracts/{contractId}
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}:
patch:
tags:
- Basic
summary: Update contract
description: >-
Update an existing contract in your HubSpot account using the specified
contract ID. This operation allows you to modify details of a contract,
such as billing information, payment terms, and other properties. Ensure
that the contract ID is valid and that all required fields in the
request body are provided.
operationId: patch-/commerce/contracts/2026-09-beta/contracts/{contractId}
parameters:
- name: contractId
in: path
description: The unique identifier of the contract to update.
required: true
style: simple
explode: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContractEditRequest'
required: true
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ContractResponse'
default:
$ref: '#/components/responses/Error'
description: ''
security:
- oauth2:
- revenue-contracts-public-api-write
components:
schemas:
ContractEditRequest:
required:
- automatedTaxesEnabled
- billingAddress
- billingCompanyId
- billingContactId
- billingStartDateOverride
- dealId
- externalPaymentMethodReferenceId
- locale
- name
- netPaymentTerms
- ownerId
- poNumber
- sellerCompanyAddress
- sellerCompanyDomain
- sellerCompanyName
- sellerEmail
- sellerFirstName
- sellerLastName
- sellerPhone
type: object
properties:
addressTypesToCollect:
type: array
description: >-
An array specifying the types of addresses to collect, with valid
values including 'BILLING_ADDRESS' and 'SHIPPING_ADDRESS'.
items:
type: string
enum:
- BILLING_ADDRESS
- SHIPPING_ADDRESS
allowedPaymentMethods:
type: array
description: >-
An array specifying the allowed payment methods, with valid values
including 'CREDIT_OR_DEBIT_CARD', 'ACH', 'SEPA', 'BACS', and 'PADS'.
items:
type: string
enum:
- CREDIT_OR_DEBIT_CARD
- ACH
- SEPA
- BACS
- PADS
automatedTaxesEnabled:
type: object
properties: {}
description: >-
An object indicating whether automated taxes are enabled for the
contract.
billingAddress:
type: object
properties: {}
description: An object representing the billing address for the contract.
billingCompanyId:
type: object
properties: {}
description: >-
An object representing the ID of the billing company associated with
the contract.
billingContactId:
type: object
properties: {}
description: >-
An object representing the ID of the billing contact associated with
the contract.
billingStartDateOverride:
type: object
properties: {}
description: An object representing an override for the billing start date.
customProperties:
type: object
additionalProperties:
type: string
description: >-
An object containing custom properties, represented as a map of
property names to their values.
dealId:
type: object
properties: {}
description: >-
An object representing the ID of the deal associated with the
contract.
externalPaymentMethodReferenceId:
type: object
properties: {}
description: >-
An object representing an external reference ID for the payment
method.
locale:
type: object
properties: {}
description: An object representing the locale settings for the contract.
name:
type: object
properties: {}
description: An object representing the name of the contract.
netPaymentTerms:
type: object
properties: {}
description: An object representing the net payment terms for the contract.
ownerId:
type: object
properties: {}
description: An object representing the ID of the owner of the contract.
poNumber:
type: object
properties: {}
description: An object representing the purchase order number for the contract.
sellerCompanyAddress:
type: object
properties: {}
description: An object representing the address of the seller's company.
sellerCompanyDomain:
type: object
properties: {}
description: An object representing the domain of the seller's company.
sellerCompanyName:
type: object
properties: {}
description: An object representing the name of the seller's company.
sellerEmail:
type: object
properties: {}
description: An object representing the email address of the seller.
sellerFirstName:
type: object
properties: {}
description: An object representing the first name of the seller.
sellerLastName:
type: object
properties: {}
description: An object representing the last name of the seller.
sellerPhone:
type: object
properties: {}
description: An object representing the phone number of the seller.
ContractResponse:
required:
- addressTypesToCollect
- allowedPaymentMethods
- automatedTaxesEnabled
- customProperties
- hubspotBillingEnabled
- id
- lineItems
- paymentEnabled
- status
- storePaymentMethodAtCheckout
type: object
properties:
addressTypesToCollect:
type: array
description: >-
An array indicating the types of addresses to collect. Valid values
include 'BILLING_ADDRESS' and 'SHIPPING_ADDRESS'.
items:
type: string
enum:
- BILLING_ADDRESS
- SHIPPING_ADDRESS
allTransactionsFeeName:
type: string
description: The name of the fee applied to all transactions.
allTransactionsFeePercentage:
type: number
description: The percentage fee applied to all transactions.
allowedPaymentMethods:
type: array
description: >-
An array of allowed payment methods for the contract. Valid values
include 'CREDIT_OR_DEBIT_CARD', 'ACH', 'SEPA', 'BACS', and 'PADS'.
items:
type: string
enum:
- CREDIT_OR_DEBIT_CARD
- ACH
- SEPA
- BACS
- PADS
annualContractValue:
type: number
description: The annual value of the contract, represented as a number.
automatedTaxesEnabled:
type: boolean
description: Indicates whether automated taxes are enabled for the contract.
billingAddress:
$ref: '#/components/schemas/Address'
billingCompanyId:
type: string
description: >-
The unique identifier for the billing company associated with the
contract.
billingContactId:
type: string
description: >-
The unique identifier for the billing contact associated with the
contract.
billingStartDateOverride:
type: string
description: An override for the billing start date, in YYYY-MM-DD format.
format: date
cardFeeName:
type: string
description: The name of the fee applied to card transactions.
cardFeePercentage:
type: number
description: The percentage fee applied to card transactions.
collectionProcess:
type: string
description: >-
The process for collecting payments. Valid values include
'MANUAL_PAYMENTS' and 'AUTOMATIC_PAYMENTS'.
enum:
- AUTOMATIC_PAYMENTS
- MANUAL_PAYMENTS
contractEffectiveDate:
type: string
description: The effective date of the contract, in YYYY-MM-DD format.
format: date
contractSourceId:
type: string
description: The unique identifier for the source of the contract.
createdAt:
type: string
description: The date and time when the contract was created, in ISO 8601 format.
format: date-time
currencyCode:
type: string
description: The currency code used for the contract, represented as a string.
currentAnnualRecurringRevenue:
type: number
description: >-
The current annual recurring revenue for the contract, represented
as a number.
currentMonthlyRecurringRevenue:
type: number
description: >-
The current monthly recurring revenue for the contract, represented
as a number.
customProperties:
type: object
additionalProperties:
type: string
description: A map of custom property names to their values for the contract.
dealId:
type: string
description: The unique identifier for the deal associated with the contract.
directDebitFeeName:
type: string
description: The name of the fee applied to direct debit transactions.
directDebitFeePercentage:
type: number
description: The percentage fee applied to direct debit transactions.
discountCode:
type: string
description: The discount code applied to the contract.
endDate:
type: string
description: The end date of the contract, in YYYY-MM-DD format.
format: date
externalPaymentMethodReferenceId:
type: string
description: >-
The external reference ID for the payment method used in the
contract.
hubspotBillingEnabled:
type: boolean
description: Indicates whether HubSpot billing is enabled for the contract.
id:
type: string
description: The unique identifier for the contract.
language:
type: string
description: The language used for the contract.
lineItems:
type: array
description: An array of line items included in the contract.
items:
$ref: '#/components/schemas/LineItem'
locale:
type: string
description: The locale setting for the contract.
name:
type: string
description: The name of the contract.
netPaymentTerms:
type: integer
description: The net payment terms for the contract, represented as an integer.
format: int32
paymentEnabled:
type: boolean
description: Indicates whether payment is enabled for the contract.
paymentMethod:
type: string
description: The payment method used for the contract.
poNumber:
type: string
description: The purchase order number associated with the contract.
preTerminationContractValue:
type: number
description: >-
The value of the contract before termination, represented as a
number.
renewalContractId:
type: string
description: The unique identifier for the renewal contract.
renewalDate:
type: string
description: The renewal date of the contract, in YYYY-MM-DD format.
format: date
sellerCompanyAddress:
$ref: '#/components/schemas/Address'
sellerCompanyName:
type: string
description: The name of the seller's company.
sellerEmail:
type: string
description: The email address of the seller.
sellerFirstName:
type: string
description: The first name of the seller.
sellerLastName:
type: string
description: The last name of the seller.
sellerPhoneNumber:
type: string
description: The phone number of the seller.
startDate:
type: string
description: The start date of the contract, in YYYY-MM-DD format.
format: date
status:
type: string
description: >-
The current status of the contract. Valid values include 'DRAFT',
'ACTIVE', 'PAUSED', 'COMPLETED', and 'TERMINATED'.
enum:
- ACTIVE
- COMPLETED
- DRAFT
- PAUSED
- TERMINATED
storePaymentMethodAtCheckout:
type: boolean
description: Indicates whether the payment method should be stored at checkout.
terminationDate:
type: string
description: The termination date of the contract, in YYYY-MM-DD format.
format: date
totalBilledAmount:
type: number
description: The total amount billed under the contract, represented as a number.
totalBilledAmountPreTax:
type: number
description: >-
The total amount billed under the contract before tax, represented
as a number.
totalCollectedFees:
type: number
description: >-
The total fees collected under the contract, represented as a
number.
totalCollectedTaxes:
type: number
description: >-
The total taxes collected under the contract, represented as a
number.
totalContractValue:
type: number
description: The total value of the contract, represented as a number.
totalPaidAmount:
type: number
description: The total amount paid under the contract, represented as a number.
updatedAt:
type: string
description: >-
The date and time when the contract was last updated, in ISO 8601
format.
format: date-time
Address:
type: object
properties:
address:
type: string
description: >-
The primary street address. It is a string representing the main
location information.
address2:
type: string
description: >-
An additional field for the street address, often used for apartment
numbers or secondary address information. It is a string.
city:
type: string
description: The city where the address is located. It is a string.
country:
type: string
description: The country where the address is located. It is a string.
countryCode:
type: string
description: >-
The code representing the country, typically in ISO format. It is a
string.
state:
type: string
description: The state or region where the address is located. It is a string.
zip:
type: string
description: The postal code for the address. It is a string.
LineItem:
required:
- id
- name
- pricing
- quantity
type: object
properties:
acv:
type: number
description: The annual contract value for the line item. A numeric value.
allowBuyerSelectedQuantity:
type: boolean
description: >-
Indicates whether the buyer can select the quantity of the line
item. A boolean value.
amount:
type: number
description: >-
The total amount for the line item, calculated as price multiplied
by quantity. A numeric value.
archived:
type: boolean
description: Indicates whether the line item is archived. A boolean value.
archivedAt:
type: string
description: >-
The date and time when the line item was archived, in ISO 8601
format.
format: date-time
arr:
type: number
description: The annual recurring revenue for the line item. A numeric value.
billingCycleAnchorDate:
type: string
description: The anchor date for the billing cycle, in ISO 8601 format.
format: date
billingPeriodEndDate:
type: string
description: The end date of the billing period, in ISO 8601 format.
format: date
billingPeriodStartDate:
type: string
description: The start date of the billing period, in ISO 8601 format.
format: date
billingStartDelayDays:
type: integer
description: >-
The number of days to delay the start of billing, represented as an
integer.
format: int32
billingStartDelayMonths:
type: integer
description: >-
The number of months to delay the start of billing, represented as
an integer.
format: int32
billingStartDelayType:
type: string
description: >-
The type of delay for the start of billing. Valid values include
'HS_BILLING_START_DELAY_DAYS', 'HS_BILLING_START_DELAY_MONTHS', and
'HS_RECURRING_BILLING_START_DATE'.
enum:
- HS_BILLING_START_DELAY_DAYS
- HS_BILLING_START_DELAY_MONTHS
- HS_RECURRING_BILLING_START_DATE
buyerSelectedQuantityMax:
type: number
description: >-
The maximum quantity that a buyer can select for the line item. A
numeric value.
buyerSelectedQuantityMin:
type: number
description: >-
The minimum quantity that a buyer can select for the line item. A
numeric value.
createdAt:
type: string
description: >-
The date and time when the line item was created, in ISO 8601
format.
format: date-time
description:
type: string
description: A text description of the line item.
discount:
type: number
description: The discount applied to the line item. A numeric value.
discountPercentage:
type: number
description: The percentage discount applied to the line item. A numeric value.
effectiveUnitPrice:
type: number
description: The effective price per unit after discounts. A numeric value.
externalId:
type: string
description: >-
An external identifier for the line item, used for integration
purposes.
id:
type: string
description: The unique identifier for the line item.
images:
type: string
description: A URL or reference to images associated with the line item.
isEditablePrice:
type: boolean
description: >-
Indicates whether the price of the line item is editable. A boolean
value.
isOptional:
type: boolean
description: Indicates whether the line item is optional. A boolean value.
lineItemCurrencyCode:
type: string
description: The currency code for the line item, following ISO 4217 format.
mrr:
type: number
description: The monthly recurring revenue for the line item. A numeric value.
name:
type: string
description: The name of the line item.
positionOnQuote:
type: integer
description: The position of the line item on a quote, represented as an integer.
format: int32
postTaxAmount:
type: number
description: The total amount after taxes are applied. A numeric value.
preDiscountAmount:
type: number
description: The amount before any discounts are applied. A numeric value.
price:
type: number
description: The price of a single unit of the line item. A numeric value.
priceBookId:
type: string
description: >-
The unique identifier for the price book associated with the line
item.
pricing:
$ref: '#/components/schemas/Pricing'
pricingModel:
type: string
description: >-
The pricing model used for the line item. Valid values include
'FLAT', 'GRADUATED', 'STAIRSTEP', and 'VOLUME'.
enum:
- FLAT
- GRADUATED
- STAIRSTEP
- VOLUME
productId:
type: string
description: The unique identifier for the product associated with the line item.
productType:
type: string
description: The type of product associated with the line item.
quantity:
type: number
description: The quantity of the line item. A numeric value.
rampKey:
type: string
description: A unique identifier for the ramp associated with the line item.
recurringBillingDayOfMonth:
type: integer
description: >-
The day of the month on which recurring billing occurs, represented
as an integer.
format: int32
recurringBillingEndDate:
type: string
description: The end date for recurring billing, in ISO 8601 format.
format: date
recurringBillingFrequency:
type: string
description: >-
The frequency of recurring billing for the line item. Valid values
include '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
recurringBillingNumberOfPayments:
type: integer
description: >-
The number of payments in the recurring billing cycle, represented
as an integer.
format: int32
recurringBillingPeriod:
type: string
description: The period for recurring billing.
recurringBillingStartDate:
type: string
description: The start date for recurring billing, in ISO 8601 format.
format: date
recurringBillingTerms:
type: string
description: >-
The terms for recurring billing. Valid values include
'AUTOMATICALLY_RENEW' and 'FIXED'.
enum:
- AUTOMATICALLY_RENEW
- FIXED
richTextDescription:
type: string
description: A rich text description of the line item.
sku:
type: string
description: The stock keeping unit identifier for the line item.
tax:
type: number
description: The tax applied to the line item. A numeric value.
tcv:
type: number
description: The total contract value for the line item. A numeric value.
termInMonths:
type: integer
description: The term of the line item in months, represented as an integer.
format: int32
tierAmount:
type: number
description: The amount associated with a specific pricing tier. A numeric value.
totalDiscount:
type: number
description: The total discount amount applied to the line item. A numeric value.
updatedAt:
type: string
description: >-
The date and time when the line item was last updated, in ISO 8601
format.
format: date-time
variantId:
type: string
description: >-
The unique identifier for the product variant associated with the
line 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: >-
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
Pricing:
required:
- prices
- pricingModel
type: object
properties:
prices:
type: array
description: >-
An array of price entries, each detailing the currency and price for
the contract or line item.
items:
$ref: '#/components/schemas/PriceEntry'
pricingModel:
type: string
description: >-
The pricing model applied to the contract or line item. Valid values
include 'FLAT', 'GRADUATED', 'STAIRSTEP', and 'VOLUME'.
enum:
- FLAT
- GRADUATED
- STAIRSTEP
- VOLUME
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.
PriceEntry:
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 applicable for this price entry, represented as
a string.
price:
type: number
description: >-
The monetary value of the product or service, represented as a
number.
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}
)}