Skip to main content
This functionality is currently in beta. By participating in this beta, you agree to HubSpot's Developer Terms and Developer Beta Terms. Note that the functionality is still under active development and is subject to change based on testing and feedback.
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.

Contracts

Create a contract

To create a contract, make a POST request to /commerce/contracts/2027-03-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/2027-03-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/2027-03-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/2027-03-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.

Delete a contract

To delete a contract, make a DELETE request to /commerce/contracts/2027-03-beta/contracts/{contractId}, providing the contract’s ID as the contractId path parameter.
  • Any contract can be deleted except a contract with HubSpot billing enabled whose status is Active or Scheduled, which will trigger a VALIDATION_ERROR if you attempt to delete it. To delete a contract with one of these statuses, terminate it first, then delete it once the termination has taken effect.
  • The user associated with the access token must have Write permission for contracts, otherwise the request will result in a MISSING_PERMISSIONS error.
A successful request returns 204 No Content with no body. The contract will be deleted immediately, and the following behavior will occur:
  • Open change quotes and renewal quotes on the contract are voided.
  • The contract’s change history is removed.
  • Subscriptions, orders, and line items the contract created are deleted.
  • If the deleted contract was a renewal, the original contract no longer appears as renewed and can be renewed again.

Contract renewals

Use the renewal endpoints for a HubSpot-managed contract which will create a brand-new contract that starts on the provided effective date, carrying forward its recurring exit line items and (optionally) overriding fields on the new contract. Two endpoints are available: a preview endpoint that returns the default renewal line items, and the renewal endpoint which will commit the changes.

Preview a renewal

To make a dry-run preview of a contract renewal without creating anything, make a GET request to /commerce/contracts/2027-03-beta/contracts/{contractId}/renewal-preview, and provide the contract’s effective date as the ?contractEffectiveDate query parameter. For example, if you wanted to renew a contract with a new effective date of 2027-01-01, you’d make a GET request to /commerce/contracts/2027-03-beta/contracts/{contractId}/renewal-preview?contractEffectiveDate=2027-01-01. The response includes a list of standard line item entries.
  • Only existing exit line items from the current contract appear.
  • Returned line item ids are negative placeholder values: nothing is persisted.
  • Use this endpoint to check what line items will be on the renewal contract by default, and to get the existing rampKey fields to use if line item overrides are needed.
An example response is shown in the code block below:

Create and finalize a renewal

To officially renew a contract, make a POST request to /commerce/contracts/2027-03-beta/contracts/{contractId}/renew, and include the contract properties of the new contract in the body of your request, along with an optional lineItems override:
  • Only contractEffectiveDate is required: every other field is optional.
    • The name of the renewed contract will default to “Renewal” if left unspecified.
    • The owner of the renewed contract defaults to the user associated with the API request.
    • The previous contract’s property values will be copied forward onto the renewal contract if a field is not provided in the request, with the exception of the following properties: PO number, seller email, first name, last name, phone number, and deal association.
  • The optional lineItems override, if supplied, fully replaces the default renewal line items.
    • Within each entry of the lineItems array, use the previousRampKey field (the rampKey from the source contract’s line items, or from the /renewal-preview response) on each override entry to link it back to the corresponding line item on the previous contract.
    • You can also add new line items (with an empty previousRampKey) that are not linked to a previous line item. Beyond line items, the request also has optional fields to overwrite other properties on the new renewal contract (name, billing contact, addresses, deal association, etc).
The response will include the full contract object of the newly renewed contract. For example, if you made a POST request to /commerce/contracts/2027-03-beta/contracts/{contractId}/renew with the following request body.
The corresponding response, if successful, would be:

Example renewal flow

The steps below provide an example workflow to test out a contract renewal, assuming your app has authorized the revenue.contracts.write, revenue.contracts.read, and crm.objects.contacts.write scopes.
1

Preview the renewal

For an effective renewal date of 2027-01-01, start by making a GET request to https://api.hubapi.com/commerce/contracts/2027-03-beta/contracts/{contractId}/renewal-preview?contractEffectiveDate=2027-01-01.In the response, note each line item’s name and rampKey if you wish to override those values when you actually renew the contract in the following step.
2

Renew the contract

Consult the tabs below based on whether you want to carry over the same default line items, override them, or override all properties in the new contract.
To renew the contract and carry over the same line items, make a POST request to https://api.hubapi.com/commerce/contracts/2027-03-beta/contracts/{contractId}/renew, and include only the new contract effective date in the request body:
You can then verify the contract object in the response includes the same lineItems from the preview in the step above.

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/2027-03-beta/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:

Co-term a line item (BETA)

The co-terming feature is currently in private beta. You can opt into this beta via the associated product update in your HubSpot account.
Co-terming lets you add a line item partway through a contract and have it end on the contract’s end date, without calculating the billing period yourself. To co-term a line-item:
  • Set coterm to true on an ADD line item change, and omit recurringBillingPeriod.
  • The billing period is calculated from the change’s effectiveDate to the contract end date.
  • The change’s effectiveDate must be before the contract’s end date. A co-termed ADD with an effectiveDate at or after the contract end date is rejected. Evergreen contracts have no end date, so this check doesn’t apply to them.
How the line items are calculated depends on whether the time remaining on the contract is a whole number of billing cycles, and on the prorating setting of the change: To see the line items that will be created before you commit to them, send the same request body to the preview endpoint.

Retrieve changes for a contract

To retrieve all changes for a contract, make a GET request to /commerce/contracts/2027-03-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/2027-03-beta/changes/{changeId}. The response returns the full change object.

Update a change

To update a change, make a PATCH request to /commerce/contracts/2027-03-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/2027-03-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/2027-03-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.

Preview a change

To preview the effects of a DIRECT change without creating it, make a POST request to /commerce/contracts/2027-03-beta/changes/preview. The request body uses the same schema as creating a DIRECT change. The endpoint does not persist the change or affect the contract. The response returns only the projected line item state:

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/2027-03-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:

Taxes

To configure taxes for a line item, you can set the following fields: The following example shows how to manually specify a tax rate for a line item using taxRateGroupId:
The taxAmount field is returned in line item responses and is automatically calculated based on the line item’s tax configuration.

Pricing models

The pricing object supports four pricing models. All tiered models (VOLUME, GRADUATED, STAIRSTEP) share the same prices array structure: maxQuantity defines the upper bound of each tier, and the last tier is always unbounded.
In the FLAT pricing model, a single fixed price per unit is charged, regardless of quantity. prices contains a single entry per currency.
Key rules for tiered pricing
  • Tiers must be ordered low to high by maxQuantity.
  • maxQuantity must be a positive integer (e.g., 10).
  • The last tier must always be unbounded (omit maxQuantity).
  • The price field means different things depending on the model:
    • VOLUME, GRADUATED: per-unit rate, multiplied by quantity.
    • STAIRSTEP: total flat fee for the tier (quantity is not factored in).
  • For multi-currency line items, include one full set of tiers per currency code within the same prices array.

Revenue reporting

When contract actions occur, HubSpot automatically generates contract revenue events. These events power HubSpot’s built-in revenue reports (MRR Waterfall, Net New MRR, Booked MRR, and Booked TCV). They are available through the Events API so you can build custom reports or combine HubSpot revenue data with external sources. HubSpot provides two contract revenue event types that you can retrieve:
  • e_contract_booking: records each committed revenue change at the line-item level. Fires once per line item, per contract action. Powers the Booked MRR and Booked TCV reports.
  • e_contract_revenue_scheduled: records the full revenue schedule, with one entry per line item per billing month. Fires on contract creation, accepted changes, renewals, and terminations. Regenerates all affected months when a change occurs. Powers the MRR Waterfall and Net New MRR reports.
The data for these events is generated automatically by HubSpot’s contract system. You cannot write to them via the API. To access the data, query the Events API as described below.
Querying contract revenue events requires the business-intelligence scope.

Retrieve contract revenue events

To retrieve contract revenue events, make a GET request to /events/event-occurrences/2027-03-beta with the eventType query parameter set to the event type you want to retrieve (e_contract_booking or e_contract_revenue_scheduled). For example: /events/event-occurrences/2027-03-beta?eventType=e_contract_booking Example response:

e_contract_booking event properties

The e_contract_booking event fires once per line item each time a contract is created, a change or renewal is accepted, or a contract is terminated.

e_contract_revenue_scheduled event properties

The e_contract_revenue_scheduled event fires once per line item per billing month. It is generated on contract creation, accepted changes, renewals, and terminations. When a change occurs, affected months are regenerated, so each month always reflects the latest revenue figures.
Last modified on November 16, 2026