Required Scopes
Required Scopes
Contracts
Create a contract
To create a contract, make aPOST request to /commerce/contracts/2027-03-beta/contracts.
The request body must include name, billingContactId, currencyCode, contractEffectiveDate, and at least one entry in lineItems.
- Example request
- Example response
Retrieve a contract
To retrieve a contract, make aGET request to /commerce/contracts/2027-03-beta/contracts/{contractId}.
To batch retrieve or retrieve all contract records, use the Contracts object API.
Update a contract
To update a contract’s properties, make aPATCH 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 response returns the full updated contract object.
Terminate a contract
To terminate an active contract, make aPOST 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.
terminationDate property set to reflect the date of termination.
Delete a contract
To delete a contract, make aDELETE 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_ERRORif 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_PERMISSIONSerror.
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 aGET 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
rampKeyfields to use if line item overrides are needed.
Create and finalize a renewal
To officially renew a contract, make aPOST 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
contractEffectiveDateis 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
lineItemsoverride, if supplied, fully replaces the default renewal line items.- Within each entry of the
lineItemsarray, use thepreviousRampKeyfield (the rampKey from the source contract’s line items, or from the/renewal-previewresponse) 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).
- Within each entry of the
POST request to /commerce/contracts/2027-03-beta/contracts/{contractId}/renew with the following request body.
Example renewal flow
The steps below provide an example workflow to test out a contract renewal, assuming your app has authorized therevenue.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.
- Renew with default line items
- Renew with line item overrides
- Renew with all property overrides
To renew the contract and carry over the same line items, make a You can then verify the contract object in the response includes the same
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: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 thetype field:
Changes move through the following statuses:
Create a change
To create a contract change, make aPOST 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.
- DIRECT
- QUOTE
The response returns the change:
Line item changes
ForDIRECT changes, each entry in lineItemChanges represents a modification to a single line item:
Co-term a line item (BETA)
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
cotermtotrueon anADDline item change, and omitrecurringBillingPeriod. - The billing period is calculated from the change’s
effectiveDateto the contract end date. - The change’s
effectiveDatemust be before the contract’s end date. A co-termedADDwith aneffectiveDateat or after the contract end date is rejected. Evergreen contracts have no end date, so this check doesn’t apply to them.
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 aGET 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 aGET request to /commerce/contracts/2027-03-beta/changes/{changeId}.
The response returns the full change object.
Update a change
To update a change, make aPATCH request to /commerce/contracts/2027-03-beta/changes/{changeId}.
A change can only be updated while it has
DRAFT status.Accept a change
To accept aDIRECT 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.Cancel a change
To cancel aDIRECT 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.CANCELED status without applying any modifications to the contract.
The response returns the updated change.
Preview a change
To preview the effects of aDIRECT 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 aPOST 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
dealPipelineanddealStage.
The response returns the newly created quote, including its line items and metadata.
Contract properties
Contract status
Thestatus field reflects the contract’s current state, and is determined by the contractEffectiveDate date and end date:
Address format
ThebillingAddress and sellerCompanyAddress properties use the same structure:
Line items
Modes
ThelineItems array accepts a mode field that determines how each line item is created:
- CUSTOM
- FROM_PRODUCT
- CLONE
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:
taxAmount field is returned in line item responses and is automatically calculated based on the line item’s tax configuration.
Pricing models
Thepricing 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.
- Flat
- Volume
- Graduated
- Stairstep
In the
FLAT pricing model, a single fixed price per unit is charged, regardless of quantity. prices contains a single entry per currency.- Tiers must be ordered low to high by
maxQuantity. maxQuantitymust be a positive integer (e.g.,10).- The last tier must always be unbounded (omit
maxQuantity). - The
pricefield 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
pricesarray.
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.
Querying contract revenue events requires the
business-intelligence scope.Retrieve contract revenue events
To retrieve contract revenue events, make aGET 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
Thee_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
Thee_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.