Skip to main content

Supported products

A contract is HubSpot’s centralized source of truth for committed revenue, including terms, pricing, duration, and purchased line items. Contracts are typically created from an accepted quote and managed throughout the customer lifecycle via billing, invoicing, and mid-contract adjustments. Learn more about how contracts work on HubSpot’s Knowledge Base.
The Contracts API documented on this page supports creating and managing contracts programmatically. For retrieving individual contract CRM records, use the Contracts object API.

Prerequisites

To use this API, you’ll need to enroll your account into the beta.

Contracts

Create a contract

To create a contract, make a POST request to /commerce/contracts/2026-09-beta/contracts. The request body must include name, billingContactId, currencyCode, contractEffectiveDate, and at least one entry in lineItems.
Please note: the following properties cannot be changed after a contract is created: currencyCode, contractEffectiveDate, collectionProcess, hubspotBillingEnabled, paymentEnabled.

Retrieve a contract

To retrieve a contract, make a GET request to /commerce/contracts/2026-09-beta/contracts/{contractId}.
To batch retrieve or retrieve all contract records, use the Contracts object API.
The response returns the full contract object, including all line items and their current billing configuration.

Update a contract

To update a contract’s properties, make a PATCH request to /commerce/contracts/2026-09-beta/contracts/{contractId}. In the request body, include the properties to update. Properties not included will remain unchanged.
Line item modifications are not supported via this endpoint. To add, update, or remove line items on an active contract, use the contract changes process instead.
The following contract properties can be updated: The response returns the full updated contract object.

Terminate a contract

To terminate an active contract, make a POST request to /commerce/contracts/2026-09-beta/contracts/{contractId}/terminate. In the request body, you can include a terminationDate to set a future termination date. This will schedule the termination and update the contract’s total contract value (TCV) to reflect the shortened term. If omitted, the contract terminates as of the current date.
The response returns the contract object with the terminationDate property set to reflect the date of termination.

Contract changes

A contract change lets you propose updates to a contract’s line items. Rather than editing line items directly, you describe what should change. You can use contract changes to add or remove services, adjust pricing mid-contract, or update quantities. There are two workflows for contract changes based on the type field: Changes move through the following statuses:

Create a change

To create a contract change, make a POST request to /commerce/contracts/2026-09-beta/contracts/{contractId}/changes. The type field is required and determines the change workflow. Use "DIRECT" to specify line item modifications in the request, or "QUOTE" to initiate a quote-backed approval flow.
The response returns the change:

Line item changes

For DIRECT changes, each entry in lineItemChanges represents a modification to a single line item:

Retrieve changes for a contract

To retrieve all changes for a contract, make a GET request to /commerce/contracts/2026-09-beta/contracts/{contractId}/changes. The response returns a changes array containing all changes associated with the contract.

Retrieve a change

To retrieve an individual change by ID, make a GET request to /commerce/contracts/2026-09-beta/changes/{changeId}. The response returns the full change object.

Update a change

To update a change, make a PATCH request to /commerce/contracts/2026-09-beta/changes/{changeId}.
A change can only be updated while it has DRAFT status.
In the request body, include the fields you want to modify.
The response returns the updated change.

Accept a change

To accept a DIRECT change, make a POST request to /commerce/contracts/2026-09-beta/changes/{changeId}/accept. No request body is required. Accepting a change applies the line item modifications to the contract and transitions the change to ACCEPTED status.
This endpoint only works for DIRECT changes. QUOTE changes are accepted when the buyer signs the associated quote.
The response returns the updated change.

Cancel a change

To cancel a DIRECT change, make a POST request to /commerce/contracts/2026-09-beta/changes/{changeId}/cancel. No request body is required.
This endpoint only works for DIRECT changes. QUOTE changes are canceled by voiding the associated quote.
Canceling a change transitions it to CANCELED status without applying any modifications to the contract. The response returns the updated change.

Renewal quotes

A renewal quote lets you initiate the renewal process for a contract that is approaching its end date. When a renewal quote is accepted by the buyer, a new contract is created and automatically associated with the previous one.

Create a renewal quote

To create a renewal quote, make a POST request to /commerce/contracts/2026-09-beta/contracts/{contractId}/renewal-quotes. When creating a renewal quote, you must associate it with a deal. In the request body, you can either:
  • Associate it with an existing deal by including dealId.
  • Generate a new deal by including both dealPipeline and dealStage.
The renewal quote is pre-populated with the contract’s active recurring line items as of the end date.
The response returns the newly created quote, including its line items and metadata.

Contract properties

Contract status

The status field reflects the contract’s current state, and is determined by the contractEffectiveDate date and end date:

Address format

The billingAddress and sellerCompanyAddress properties use the same structure:

Line items

Modes

The lineItems array accepts a mode field that determines how each line item is created:

Recurring billing

To configure recurring billing for line items, use the fields below, which map directly to the corresponding CRM line item property. Learn more about recurring billing. For example, the line item below would bill monthly for 8 months:
Last modified on August 7, 2026