> ## 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.
# 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 its properties and associated line items. Ensure that the contract ID is valid and corresponds to an existing contract.
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/2027-03-beta/commerce-contracts-v2027-03-beta.json PATCH /commerce/contracts/2027-03-beta/contracts/{contractId}
openapi: 3.0.1
info:
title: Commerce Contracts
description: Basepom for all HubSpot Projects
version: 2027-03-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: Advanced
- name: Basic
- name: Changes
paths:
/commerce/contracts/2027-03-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 its properties and associated line items. Ensure that the
contract ID is valid and corresponds to an existing contract.
operationId: patch-/commerce/contracts/2027-03-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 of strings indicating the types of addresses to collect,
such as 'BILLING_ADDRESS' or 'SHIPPING_ADDRESS'.
items:
type: string
enum:
- BILLING_ADDRESS
- SHIPPING_ADDRESS
allowedPaymentMethods:
type: array
description: >-
An array of strings specifying the allowed payment methods, which
can include 'CREDIT_OR_DEBIT_CARD', 'ACH', 'SEPA', 'BACS', 'PADS',
'AFFIRM', and 'KLARNA'.
items:
type: string
enum:
- CREDIT_OR_DEBIT_CARD
- ACH
- SEPA
- BACS
- PADS
- AFFIRM
- KLARNA
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 the override for the billing start date.
customProperties:
type: object
additionalProperties:
type: string
description: >-
An object containing a map of custom property names to their values,
represented as strings.
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 the 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 of the fee applied to all transactions.
allowedPaymentMethods:
type: array
description: >-
An array of allowed payment methods. Valid values include
'CREDIT_OR_DEBIT_CARD', 'ACH', 'SEPA', 'BACS', 'PADS', 'AFFIRM', and
'KLARNA'.
items:
type: string
enum:
- CREDIT_OR_DEBIT_CARD
- ACH
- SEPA
- BACS
- PADS
- AFFIRM
- KLARNA
annualContractValue:
type: number
description: The annual value of the contract.
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 of the billing company associated with the
contract.
billingContactId:
type: string
description: >-
The unique identifier of the billing contact associated with the
contract.
billingStartDateOverride:
type: string
description: The date to override the billing start date, in ISO 8601 format.
format: date
businessUnitId:
type: string
description: >-
The unique identifier of the business unit associated with the
contract.
cardFeeName:
type: string
description: The name of the fee applied to card transactions.
cardFeePercentage:
type: number
description: The percentage of the 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 date when the contract becomes effective, in ISO 8601 format.
format: date
contractSourceId:
type: string
description: The unique identifier of 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 associated with the contract, represented as a
string.
currentAnnualRecurringRevenue:
type: number
description: The current annual recurring revenue for the contract.
currentMonthlyRecurringRevenue:
type: number
description: The current monthly recurring revenue for the contract.
customProperties:
type: object
additionalProperties:
type: string
description: A map of custom property names to their values.
dealId:
type: string
description: The unique identifier of 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 of the 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 ISO 8601 format.
format: date
externalPaymentMethodReferenceId:
type: string
description: The external reference ID for the payment method.
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 associated with 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 associated with 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.
renewalContractId:
type: string
description: The unique identifier of the renewal contract.
renewalDate:
type: string
description: The date when the contract is set to renew, in ISO 8601 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 ISO 8601 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 date when the contract is terminated, in ISO 8601 format.
format: date
totalBilledAmount:
type: number
description: The total amount billed under the contract.
totalBilledAmountPreTax:
type: number
description: The total amount billed under the contract before tax.
totalCollectedFees:
type: number
description: The total amount of fees collected under the contract.
totalCollectedTaxes:
type: number
description: The total amount of taxes collected under the contract.
totalContractValue:
type: number
description: The total value of the contract.
totalPaidAmount:
type: number
description: The total amount paid under the contract.
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 detail.
address2:
type: string
description: >-
An additional street address line. This is a string used for
supplementary location details.
city:
type: string
description: >-
The city where the address is located. It is represented as a
string.
country:
type: string
description: >-
The country of the address. This is a string indicating the nation
associated with the address.
countryCode:
type: string
description: >-
The code representing the country of the address. It is a string,
typically following international country code standards.
state:
type: string
description: >-
The state or region of the address. This is a string that specifies
the subdivision within the country.
zip:
type: string
description: >-
The postal code for the address. It is a string used for mail
delivery purposes.
LineItem:
required:
- id
- name
- pricing
- quantity
type: object
properties:
acv:
type: number
description: The annual contract value for this line item. A number.
allowBuyerSelectedQuantity:
type: boolean
description: >-
Indicates whether the buyer can select the quantity of this line
item. A boolean value.
amount:
type: number
description: >-
The total amount for this line item, calculated as price multiplied
by quantity. A number.
archived:
type: boolean
description: Indicates whether this line item is archived. A boolean value.
archivedAt:
type: string
description: >-
The date and time when this line item was archived, in ISO 8601
format.
format: date-time
arr:
type: number
description: The annual recurring revenue for this line item. A number.
billingCycleAnchorDate:
type: string
description: The anchor date for the billing cycle, in ISO 8601 date format.
format: date
billingPeriodEndDate:
type: string
description: The end date of the billing period, in ISO 8601 date format.
format: date
billingPeriodStartDate:
type: string
description: The start date of the billing period, in ISO 8601 date format.
format: date
billingStartDelayDays:
type: integer
description: The delay in days before billing starts. An integer.
format: int32
billingStartDelayMonths:
type: integer
description: The delay in months before billing starts. An integer.
format: int32
billingStartDelayType:
type: string
description: >-
The type of delay before billing starts. 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 the buyer can select for this line item. A
number.
buyerSelectedQuantityMin:
type: number
description: >-
The minimum quantity the buyer can select for this line item. A
number.
createdAt:
type: string
description: >-
The date and time when this 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 this line item. A number.
discountPercentage:
type: number
description: The discount percentage applied to this line item. A number.
effectiveUnitPrice:
type: number
description: The effective price per unit after discounts. A number.
externalId:
type: string
description: An external identifier for this line item.
id:
type: string
description: The unique identifier for this line item.
images:
type: string
description: A URL or reference to images associated with this line item.
isEditablePrice:
type: boolean
description: >-
Indicates whether the price of this line item is editable. A boolean
value.
isOptional:
type: boolean
description: Indicates whether this line item is optional. A boolean value.
isParent:
type: boolean
description: Indicates whether this line item is a parent item. A boolean value.
lineItemCurrencyCode:
type: string
description: The currency code for this line item, following ISO 4217 format.
mrr:
type: number
description: The monthly recurring revenue for this line item. A number.
name:
type: string
description: The name of the line item.
parentLineItemId:
type: string
description: The unique identifier for the parent line item, if applicable.
positionOnQuote:
type: integer
description: The position of this line item on a quote. An integer.
format: int32
postTaxAmount:
type: number
description: The total amount after tax is applied. A number.
preDiscountAmount:
type: number
description: The amount before any discounts are applied. A number.
price:
type: number
description: The price of a single unit of the line item. A number.
priceBookId:
type: string
description: >-
The unique identifier for the price book associated with this line
item.
pricing:
$ref: '#/components/schemas/Pricing'
pricingModel:
type: string
description: >-
The pricing model used for this 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 this line
item.
productType:
type: string
description: The type of product for this line item.
quantity:
type: number
description: The quantity of the line item. A number.
rampKey:
type: string
description: A unique identifier for the ramp associated with this line item.
recurringBillingDayOfMonth:
type: integer
description: The day of the month on which recurring billing occurs. An integer.
format: int32
recurringBillingEndDate:
type: string
description: The end date for recurring billing, in ISO 8601 date format.
format: date
recurringBillingFrequency:
type: string
description: >-
The frequency of recurring billing for this 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 for recurring billing. 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 date 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 (SKU) for this line item.
tax:
type: number
description: The tax rate applied to this line item. A number.
taxAmount:
type: number
description: The total tax amount for this line item. A number.
taxCategory:
type: string
description: The tax category for this line item.
taxRateGroupId:
type: string
description: >-
The unique identifier for the tax rate group associated with this
line item.
tcv:
type: number
description: The total contract value for this line item. A number.
termInMonths:
type: integer
description: The term length in months for this line item. An integer.
format: int32
tierAmount:
type: number
description: The amount for the current pricing tier. A number.
totalDiscount:
type: number
description: The total discount amount for this line item. A number.
updatedAt:
type: string
description: >-
The date and time when this 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 this
line item.
Error:
required:
- category
- correlationId
- message
type: object
properties:
category:
type: string
description: The error category.
context:
type: object
additionalProperties:
type: array
items:
type: string
description: >-
Context about the error condition, provided 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 formatted as a UUID.
format: uuid
example: aeb5f871-7f07-4993-9211-075dc63e7cbf
errors:
type: array
description: >-
Further information about the error, represented 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.
message:
type: string
description: >-
A human readable message describing the error along with remediation
steps where appropriate.
example: An error occurred
subCategory:
type: string
description: >-
A specific category that contains more specific detail about the
error.
description: >-
Represents an error response returned by the API when an operation
fails. This component is used in various endpoints to provide detailed
information about the error encountered.
example:
message: Invalid input (details will vary based on the error)
correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
category: VALIDATION_ERROR
links:
knowledge-base: https://www.hubspot.com/products/service/knowledge-base
Pricing:
required:
- prices
- pricingModel
type: object
properties:
prices:
type: array
description: >-
An array of price entries, each specifying a currency code and the
corresponding price for the line item.
items:
$ref: '#/components/schemas/PriceEntry'
pricingModel:
type: string
description: >-
The pricing model applied to the 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, represented as a
string.
context:
type: object
additionalProperties:
type: array
items:
type: string
description: >-
Context about the error condition, represented as an object where
each key is a string and each value is an array of strings. This
provides additional information about the error.
example: '{missingScopes=[scope1, scope2]}'
in:
type: string
description: >-
The name of the field or parameter in which the error was found.
This is an optional string field.
message:
type: string
description: >-
A human readable message describing the error along with remediation
steps where appropriate. This is a required field and is of type
string.
subCategory:
type: string
description: >-
A specific category that contains more specific detail about the
error, provided as a string.
description: >-
Represents detailed information about an error that occurred in the API.
This component is used to provide additional context and specifics about
errors, typically as part of an error response.
PriceEntry:
required:
- currencyCode
- price
type: object
properties:
currencyCode:
type: string
description: >-
The currency in which the price is denominated, represented as a
string.
maxQuantity:
type: integer
description: >-
The maximum quantity for which this price is applicable, represented
as an integer.
format: int32
price:
type: number
description: >-
The cost of the product or service in the specified currency,
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}
)}