Contracts API (BETA) - HubSpot docs

Required Scopes

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.

Example request
Example response

{
  "name": "Enterprise Platform License",
  "currencyCode": "USD",
  "contractEffectiveDate": "2026-09-01",
  "billingContactId": "12345678901",
  "hubspotBillingEnabled": true,
  "paymentEnabled": false,
  "collectionProcess": "MANUAL_PAYMENTS",
  "netPaymentTerms": 30,
  "lineItems": [
    {
      "mode": "CUSTOM",
      "name": "Platform license",
      "quantity": 1,
      "pricing": {
        "pricingModel": "FLAT",
        "prices": [
          {
            "currencyCode": "USD",
            "price": "1200.00"
          }
        ]
      },
      "recurringBillingFrequency": "ANNUALLY",
      "recurringBillingTerms": "AUTOMATICALLY_RENEW"
    }
  ]
}

Property	Type	Description
`name`	String	The contract name.
`currencyCode`	String	ISO 4217 currency code (e.g., `"USD"`). Cannot be changed after creation.
`contractEffectiveDate`	String	The date the contract takes effect, in `YYYY-MM-DD` format. Cannot be changed after creation. If the date is today or in the past, the contract status will be set to `ACTIVE`. If the date is in the future, the contract is assigned the `DRAFT` status and will be set to `ACTIVE` on that date.
`billingContactId`	String	ID of the contact to bill.
`lineItems`	Array	Line items to include. At least one is required. See line item modes below.
`hubspotBillingEnabled`	Boolean	Whether HubSpot manages billing for this contract. Cannot be changed after creation.
`paymentEnabled`	Boolean	Whether online payment is enabled at checkout. Cannot be changed after creation.
`billingCompanyId`	String	ID of the billing company.
`dealId`	String	ID of the deal to associate with this contract.
`ownerId`	String	ID of the contract owner.
`collectionProcess`	String	How payments are collected. Allowed values: `"MANUAL_PAYMENTS"`, `"AUTOMATIC_PAYMENTS"`. Cannot be changed after creation.
`allowedPaymentMethods`	Array	Accepted payment methods. Allowed values: `"CREDIT_OR_DEBIT_CARD"`, `"ACH"`, `"SEPA"`, `"BACS"`, `"PADS"`.
`netPaymentTerms`	Integer	Number of days the buyer has to pay each invoice. Defaults to `0`.
`locale`	String	IETF locale tag (e.g., `"en-US"`).
`automatedTaxesEnabled`	Boolean	Whether automated sales tax is enabled for the contract (must be enabled in your account). Defaults to `false`. When `true`: `taxRateGroupId` cannot be set on line items You must include the `billingAddress` fields `address`, `state`, `zip`, and `countryCode`. See address format.
`addressTypesToCollect`	Array	Address types to collect at checkout. Allowed values: `"BILLING_ADDRESS"`, `"SHIPPING_ADDRESS"`.
`billingAddress`	Object	Billing address. See address format below.
`poNumber`	String	Purchase order number.
`sellerCompanyName`	String	Seller’s company name. Defaults to the account’s company name if not provided.
`sellerCompanyDomain`	String	Seller’s company website domain (e.g., `"example.com"`).
`sellerCompanyAddress`	Object	Seller’s company address. See address format.
`sellerEmail`	String	Seller’s email address.
`sellerFirstName`	String	Seller’s first name.
`sellerLastName`	String	Seller’s last name.
`sellerPhone`	String	Seller’s phone number.
`billingStartDateOverride`	String	Date when billing schedule entries begin for the contract’s recurring line items, in `YYYY-MM-DD` format. If not provided, billing starts from `contractEffectiveDate`.
`externalPaymentMethodReferenceId`	String	Reference ID of a payment method managed outside of HubSpot (e.g., a Stripe payment method ID).
`customProperties`	Object	Custom CRM property values as a string-to-string map.

{
  "id": "420963644724",
  "createdAt": "2026-08-07T18:58:34.855Z",
  "updatedAt": "2026-08-07T18:58:36.063Z",
  "status": "DRAFT",
  "name": "Enterprise Platform License",
  "currencyCode": "USD",
  "contractEffectiveDate": "2026-09-01",
  "startDate": "2026-09-01",
  "billingContactId": "102",
  "lineItems": [
    {
      "id": "24584111229",
      "createdAt": "2026-08-07T18:58:35.295Z",
      "updatedAt": "2026-08-07T18:58:35.295Z",
      "pricing": {
        "pricingModel": "FLAT",
        "prices": [
          {
            "currencyCode": "USD",
            "price": "1200.00"
          }
        ]
      },
      "name": "Platform license",
      "quantity": 1,
      "price": "1200.00",
      "amount": "1200.00",
      "pricingModel": "FLAT",
      "totalDiscount": "0.00",
      "preDiscountAmount": "1200.00",
      "effectiveUnitPrice": "1200.00",
      "postTaxAmount": "1200.00",
      "acv": "1200.00",
      "arr": "1200.00",
      "mrr": "100.00",
      "tcv": "1200.00",
      "lineItemCurrencyCode": "USD",
      "positionOnQuote": 0,
      "recurringBillingFrequency": "ANNUALLY",
      "recurringBillingStartDate": "2026-09-01",
      "recurringBillingTerms": "AUTOMATICALLY_RENEW",
      "billingCycleAnchorDate": "2026-09-01",
      "billingStartDelayType": "HS_RECURRING_BILLING_START_DATE",
      "rampKey": "35a2886a-d838-44e6-aa18-ecc547275f12"
    }
  ],
  "customProperties": {},
  "addressTypesToCollect": [],
  "allowedPaymentMethods": [],
  "collectionProcess": "MANUAL_PAYMENTS",
  "netPaymentTerms": 30,
  "sellerCompanyName": "Coffee Inc.",
  "automatedTaxesEnabled": false,
  "hubspotBillingEnabled": true,
  "paymentEnabled": false,
  "storePaymentMethodAtCheckout": false
}

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.

{
  "id": "420963644724",
  "createdAt": "2026-08-07T18:58:34.855Z",
  "updatedAt": "2026-08-07T18:58:46.249Z",
  "status": "DRAFT",
  "name": "Enterprise Platform License",
  "currencyCode": "USD",
  "contractEffectiveDate": "2026-09-01",
  "startDate": "2026-09-01",
  "billingContactId": "102",
  "lineItems": [
    {
      "id": "24584111229",
      "createdAt": "2026-08-07T18:58:35.295Z",
      "updatedAt": "2026-08-07T18:58:35.931Z",
      "pricing": {
        "pricingModel": "FLAT",
        "prices": [
          {
            "currencyCode": "USD",
            "price": "1200.00"
          }
        ]
      },
      "name": "Platform license",
      "quantity": 1,
      "price": "1200.00",
      "amount": "1200.00",
      "pricingModel": "FLAT",
      "totalDiscount": "0.00",
      "preDiscountAmount": "1200.00",
      "effectiveUnitPrice": "1200.00",
      "postTaxAmount": "1200.00",
      "acv": "1200.00",
      "arr": "1200.00",
      "mrr": "100.00",
      "tcv": "1200.00",
      "lineItemCurrencyCode": "USD",
      "positionOnQuote": 0,
      "recurringBillingFrequency": "ANNUALLY",
      "recurringBillingStartDate": "2026-09-01",
      "recurringBillingTerms": "AUTOMATICALLY_RENEW",
      "billingCycleAnchorDate": "2026-09-01",
      "billingStartDelayType": "HS_RECURRING_BILLING_START_DATE",
      "rampKey": "35a2886a-d838-44e6-aa18-ecc547275f12"
    }
  ],
  "customProperties": {},
  "addressTypesToCollect": [],
  "allowedPaymentMethods": [],
  "collectionProcess": "MANUAL_PAYMENTS",
  "netPaymentTerms": 30,
  "sellerCompanyName": "Coffee Inc.",
  "totalBilledAmount": 1200.00,
  "totalBilledAmountPreTax": 1200.00,
  "totalPaidAmount": 0.00,
  "automatedTaxesEnabled": false,
  "hubspotBillingEnabled": true,
  "paymentEnabled": false,
  "storePaymentMethodAtCheckout": false
}

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.

{
  "name": "Enterprise Platform License — Renewed",
  "poNumber": "PO-2026-0042",
  "netPaymentTerms": 30
}

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:

Property	Type	Description
`name`	String	The contract name.
`billingContactId`	String	ID of the contact to bill.
`billingCompanyId`	String	ID of the billing company.
`dealId`	String	ID of the associated deal.
`ownerId`	String	ID of the contract owner.
`billingAddress`	Object	Billing address. See address format below.
`netPaymentTerms`	Integer	Number of days the buyer has to pay each invoice.
`locale`	String	IETF locale tag (e.g., `"en-US"`).
`automatedTaxesEnabled`	Boolean	Whether automated sales tax is enabled for the contract (must be enabled in your account). Defaults to `false`. When `true`: `taxRateGroupId` cannot be set on line items You must include the `billingAddress` fields `address`, `state`, `zip`, and `countryCode`. See address format.
`addressTypesToCollect`	Array	Address types to collect at checkout.
`allowedPaymentMethods`	Array	Accepted payment methods.
`poNumber`	String	Purchase order number.
`sellerCompanyName`	String	Seller’s company name.
`sellerCompanyDomain`	String	Seller’s company website domain (e.g., `"example.com"`).
`sellerCompanyAddress`	Object	Seller’s company address. See address format.
`sellerEmail`	String	Seller’s email address.
`sellerFirstName`	String	Seller’s first name.
`sellerLastName`	String	Seller’s last name.
`sellerPhone`	String	Seller’s phone number.
`billingStartDateOverride`	String	Date when billing schedule entries begin for the contract’s recurring line items, in `YYYY-MM-DD` format.
`externalPaymentMethodReferenceId`	String	Reference ID of a payment method managed outside of HubSpot (e.g., a Stripe payment method ID).
`customProperties`	Object	Custom CRM property values as a string-to-string map.

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.

{
  "terminationDate": "2026-12-31"
}

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:

Type	Description
`DIRECT`	Line item modifications are specified in the API request body. With `autoAccept: true`, the change is applied immediately. With `autoAccept: false` (default), the change sits at `DRAFT` until accepted via the accept endpoint.
`QUOTE`	A HubSpot quote is generated for the buyer to review and sign. The change is accepted when the buyer signs the quote, or canceled when the quote is voided. Accept and cancel actions happen through the quote lifecycle, not through this API.

Changes move through the following statuses:

Status	Description
`DRAFT`	Created but not yet submitted. Line item changes can be modified at this stage.
`PROPOSED`	Submitted for review (for `QUOTE` changes).
`ACCEPTED`	Approved and applied to the contract. `DIRECT` changes with `autoAccept: true` skip to this status immediately.
`CANCELED`	Voided before acceptance.
`FAILED`	A processing error occurred during acceptance.
`EXPIRED`	Not accepted before the expiration date.

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.

DIRECT
QUOTE

{
  "contractId": "123456789",
  "type": "DIRECT",
  "prorating": true,
  "autoAccept": false,
  "effectiveDate": "2026-10-01",
  "name": "Q4 seat expansion",
  "lineItemChanges": [
    {
      "action": "UPDATE",
      "rampKey": "20b25cb9-a4da-4b62-81b8-2821cc45f2a6",
      "lineItemUpdate": {
        "quantity": "5"
      }
    }
  ]
}

Property	Type	Description
`type`	String	Must be `"DIRECT"`.
`prorating`	Boolean	Whether to prorate the change based on the effective date.
`lineItemChanges`	Array	Line item modifications to apply. See line item changes below.
`contractId`	String	ID of the contract to apply this change to.
`autoAccept`	Boolean	When `true`, the change is applied immediately. Defaults to `false`.
`effectiveDate`	String	Date the change takes effect, in `YYYY-MM-DD` format.
`name`	String	A name for this change.

The response returns the change:

{
  "id": "234567890",
  "contractId": "123456789",
  "type": "DIRECT",
  "status": "DRAFT",
  "prorating": true,
  "effectiveDate": "2026-10-01",
  "name": "Q4 seat expansion",
  "createdAt": "2026-09-15T14:00:00.000Z",
  "updatedAt": "2026-09-15T14:00:00.000Z",
  "lineItemChanges": [
    {
      "action": "UPDATE",
      "rampKey": "20b25cb9-a4da-4b62-81b8-2821cc45f2a6",
      "lineItemUpdate": {
        "quantity": "5"
      }
    }
  ],
  "deltaLineItems": [
    {
      "id": "24584111229",
      "name": "Platform license",
      "quantity": 5,
      "rampKey": "20b25cb9-a4da-4b62-81b8-2821cc45f2a6"
    }
  ],
  "proposedLineItems": [
    {
      "id": "24584111229",
      "name": "Platform license",
      "quantity": 5,
      "price": "1200.00",
      "amount": "6000.00",
      "rampKey": "20b25cb9-a4da-4b62-81b8-2821cc45f2a6"
    }
  ]
}

When creating a change 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.

Unlike DIRECT changes, change quotes don’t support updating line items directly when creating the change. Instead, you’ll use the quotes API to handle any line item updates.

{
  "contractId": "420538663347",
  "type": "QUOTE",
  "prorating": false,
  "quoteTemplateId": "987654321",
  "dealId": "29451866158",
  "name": "Q4 upgrade"
}

Property	Type	Description
`type`	String	Must be `"QUOTE"`.
`prorating`	Boolean	Whether to prorate the change based on the effective date.
`quoteTemplateId`	String	ID of the change quote template to use.
`contractId`	String	ID of the contract to apply this change to.
`dealId`	String	ID of an existing deal to associate with the change quote. This field is required unless you are providing both `dealPipeline` and `dealStage`.
`dealPipeline`	String	The ID of the pipeline for the new associated deal. Required for generating a new deal for the quote (must also include `dealStage`).
`dealStage`	String	The ID of the pipeline stage for the new associated deal. Required for generating a new deal for the quote (must also include `dealPipeline`).
`sellerEmail`	String	Email address of the seller on the change quote.
`effectiveDate`	String	Date the change takes effect, in `YYYY-MM-DD` format.
`name`	String	A name for this change.

The response returns the change, as shown below. You can separately retrieve the resulting quote via the quotes API using the returned quoteId value.

{
  "location": null,
  "createdResourceId": "16677927",
  "entity": {
    "id": "16677927",
    "contractId": "420538663347",
    "type": "QUOTE",
    "status": "DRAFT",
    "createdAt": "2026-07-24T20:08:49.124Z",
    "updatedAt": "2026-07-24T20:08:49.124Z",
    "name": "Q4 upgrade",
    "quoteId": "11688277651",
    "effectiveDate": "2026-07-25",
    "prorating": false,
    "lineItemChanges": []
  }
}

Line item changes

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

Property	Type	Description
`action`	String	The type of modification. Allowed values: `"ADD"`, `"UPDATE"`, `"REMOVE"`.
`lineItemAdd`	Object	Line item to create. Required for `ADD` actions. See line item fields for the full set of supported fields. In responses, `ADD` actions populate `lineItemAdd` (not `lineItemUpdate`).
`lineItemUpdate`	Object	Fields to modify on the existing line item. Required for `UPDATE` actions. Uses patch semantics: absent fields are unchanged, empty string clears a field, a non-empty value sets the field.
`rampKey`	String	The `rampKey` of the line item to update or remove. Required for `"UPDATE"` and `"REMOVE"`.

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.

{
  "changes": [
    {
      "id": "234567890",
      "contractId": "123456789",
      "type": "DIRECT",
      "status": "ACCEPTED",
      "prorating": true,
      "effectiveDate": "2026-10-01",
      "name": "Q4 seat expansion",
      "createdAt": "2026-09-15T14:00:00.000Z",
      "updatedAt": "2026-10-01T00:00:00.000Z",
      "lineItemChanges": [
        {
          "action": "UPDATE",
          "rampKey": "20b25cb9-a4da-4b62-81b8-2821cc45f2a6",
          "lineItemUpdate": {
            "quantity": "5"
          }
        }
      ]
    }
  ]
}

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.

Property	Type	Description
`prorating`	Boolean	Whether to prorate the change based on the effective date.
`effectiveDate`	String	Date the change takes effect, in `YYYY-MM-DD` format.
`lineItemChanges`	Array	Replaces the current line item change list. See line item changes.
`name`	String	A name for the change. Set to `null` to clear.

{
  "prorating": true,
  "effectiveDate": "2026-11-01",
  "lineItemChanges": [
    {
      "action": "UPDATE",
      "rampKey": "20b25cb9-a4da-4b62-81b8-2821cc45f2a6",
      "lineItemUpdate": {
        "quantity": "10"
      }
    }
  ]
}

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:

{
  "deltaLineItems": [
    {
      "id": "24584111229",
      "name": "Platform license",
      "quantity": 5,
      "rampKey": "20b25cb9-a4da-4b62-81b8-2821cc45f2a6"
    }
  ],
  "proposedLineItems": [
    {
      "id": "24584111229",
      "name": "Platform license",
      "quantity": 5,
      "price": "1200.00",
      "amount": "6000.00",
      "rampKey": "20b25cb9-a4da-4b62-81b8-2821cc45f2a6"
    }
  ]
}

Property	Type	Description
`deltaLineItems`	Array	The modifications that would be applied to the contract’s line items when the change is enacted.
`proposedLineItems`	Array	The resulting state of the contract’s line items if the change were to be applied.

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.

{
  "quoteTemplateId": "987654321",
  "dealId": "29451866158",
  "name": "2027 Annual Renewal"
}

Property	Type	Description
`quoteTemplateId`	String	ID of the quote template to use for the renewal quote.
`dealId`	String	ID of an existing deal to associate with the renewal quote. This field is required unless you are providing both `dealPipeline` and `dealStage` to generate a new deal.
`dealPipeline`	String	The ID of the pipeline when generating a new associated deal. Required for generating a new deal for the quote (must also include `dealStage`).
`dealStage`	String	The ID of the pipeline stage when generating a new associated deal. Required for generating a new deal for the quote (must also include `dealPipeline`).
`name`	String	A name for the renewal quote.

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:

Status	Description
`DRAFT`	Created in the HubSpot UI but not yet finalized, or created via the API with a future `contractEffectiveDate` (scheduled to become active on that date).
`ACTIVE`	Contract is currently in effect.
`COMPLETED`	The contract’s billing period has ended. A contract’s end date is automatically calculated from the latest `hs_recurring_billing_end_date` across its recurring line items, and cannot be set directly. Contracts with evergreen line items (`recurringBillingTerms: "AUTOMATICALLY_RENEW"`) have no calculated end date and will not naturally reach this status, but must instead be terminated.
`TERMINATED`	Contract has been manually terminated.

Address format

The billingAddress and sellerCompanyAddress properties use the same structure:

"billingAddress": {
  "address": "123 Fake Street",
  "address2": null,
  "city": "Somerville",
  "country": "United States",
  "countryCode": "US",
  "state": "MA",
  "zip": "02145"
}

Property	Type	Description
`address`	String	Street line 1 (e.g., `"123 Fake Street"`). Required when `automatedTaxesEnabled` is `true`.
`address2`	String	Street line 2 (e.g., `"Unit 12"`)
`city`	String	City (e.g., `"Portland"`)
`state`	String	State or province (e.g., `"ME"`). Required when `automatedTaxesEnabled` is `true`.
`zip`	String	Postal code (e.g., `"04101"`). Required when `automatedTaxesEnabled` is `true`.
`country`	String	Country name (e.g., `"United States"`).
`countryCode`	String	Two-letter ISO 3166-1 alpha-2 country code (e.g., `"US"`). You can provide `country`, `countryCode`, or both. If both are provided, they must be consistent with each other. Required when `automatedTaxesEnabled` is `true`.

Line items

Modes

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

Mode	Required fields	Description
`CUSTOM`	`name`, `quantity`, `pricing`	Creates a line item from scratch.
`FROM_PRODUCT`	`productId`	Copies a product from your HubSpot product library. Product defaults are used for any fields not specified.
`CLONE`	`sourceLineItemId`	Copies an existing line item. Cloned values are used for any fields not specified.

CUSTOM
FROM_PRODUCT
CLONE

"lineItems": [
  {
    "mode": "CUSTOM",
    "name": "Platform license",
    "quantity": 1,
    "pricing": {
      "pricingModel": "FLAT",
      "prices": [
        {
          "currencyCode": "USD",
          "price": "1200.00"
        }
      ]
    },
    "recurringBillingFrequency": "ANNUALLY",
    "recurringBillingTerms": "AUTOMATICALLY_RENEW"
  }
]

"lineItems": [
  {
    "mode": "FROM_PRODUCT",
    "productId": "15686964654",
    "quantity": 1
  }
]

"lineItems": [
  {
    "mode": "CLONE",
    "sourceLineItemId": "24574616090",
    "quantity": 1
  }
]

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.

Field	Type	Description
`recurringBillingTerms`	String	Whether the line item is evergreen or fixed-term. Allowed values: `AUTOMATICALLY_RENEW`: billing recurs indefinitely. `FIXED`: billing ends after a set period. Use with `recurringBillingPeriod` or `recurringBillingNumberOfPayments`. Maps to `hs_recurring_billing_terms`.
`recurringBillingFrequency`	String	How often billing occurs. Allowed values: `ANNUALLY` `BIWEEKLY` `MONTHLY` `QUARTERLY` `WEEKLY` `PER_SIX_MONTHS` `PER_TWO_YEARS` `PER_THREE_YEARS` `PER_FOUR_YEARS` `PER_FIVE_YEARS` Maps to `recurringbillingfrequency`.
`recurringBillingPeriod`	String	Total duration of a fixed-term billing period as an ISO 8601 duration string (e.g., `"P8M"` for 8 months). Use with `recurringBillingTerms: "FIXED"`. Maps to `hs_recurring_billing_period`.
`recurringBillingNumberOfPayments`	Integer	Number of billing payments for a fixed-term line item. Use as an alternative to `recurringBillingPeriod`. Maps to `hs_recurring_billing_number_of_payments`.

For example, the line item below would bill monthly for 8 months:

{
  "recurringBillingFrequency": "MONTHLY",
  "recurringBillingTerms": "FIXED",
  "recurringBillingPeriod": "P8M"
}

Taxes

To configure taxes for a line item, you can set the following fields:

Field	Type	Description
`taxCategory`	String	Intended for use with automated sales tax. The ID of the tax category, which you can find in your account’s line item property settings.
`taxRateGroupId`	String	Intended for manually setting sales tax when automated sales tax isn’t enabled. The ID of the tax rate group that determines the tax rate applied to this line item, which you can retrieve via the tax rates API.

The following example shows how to manually specify a tax rate for a line item using taxRateGroupId:

"lineItems": [
      {
        "mode": "CUSTOM",
        "name": "Test line item",
        "quantity": 1,
        "pricing": {
          "pricingModel": "FLAT",
          "prices": [{ "currencyCode": "USD", "price": "100.00" }]
        },
        "taxRateGroupId": "2147636425"
      }
    ]

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.

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.

{
  "mode": "CUSTOM",
  "name": "Support Package",
  "quantity": 1,
  "pricing": {
    "pricingModel": "FLAT",
    "prices": [{ "currencyCode": "USD", "price": "500.00" }]
  },
  "recurringBillingPeriod": "P12M",
  "recurringBillingFrequency": "MONTHLY"
}

In the VOLUME pricing model, all units are billed at the per-unit rate of whichever tier the total quantity falls into. The price field is a per-unit rate, multiplied by the total quantity.Example: 15 seats → tier 2 rate applies to all 15 → 15 ×

8.00 =

120.00

{
  "mode": "CUSTOM",
  "name": "User Seats",
  "quantity": 15,
  "pricing": {
    "pricingModel": "VOLUME",
    "prices": [
      { "currencyCode": "USD", "price": "10.00", "maxQuantity": 10 },
      { "currencyCode": "USD", "price": "8.00",  "maxQuantity": 20 },
      { "currencyCode": "USD", "price": "6.00" }
    ]
  },
  "recurringBillingPeriod": "P12M",
  "recurringBillingFrequency": "MONTHLY"
}

In the GRADUATED pricing model, each unit is billed at the rate of the tier it falls within, applied incrementally across tiers. The price field is a per-unit rate for that tier’s range.Example: 25 seats → (10 ×

10.00) + (10 ×

8.00) + (5 ×

6.00) =

210.00

{
  "mode": "CUSTOM",
  "name": "API Calls",
  "quantity": 25,
  "pricing": {
    "pricingModel": "GRADUATED",
    "prices": [
      { "currencyCode": "USD", "price": "10.00", "maxQuantity": 10 },
      { "currencyCode": "USD", "price": "8.00",  "maxQuantity": 20 },
      { "currencyCode": "USD", "price": "6.00" }
    ]
  },
  "recurringBillingPeriod": "P12M",
  "recurringBillingFrequency": "MONTHLY"
}

In the STAIRSTEP pricing model, a flat fee is charged based on whichever tier the total quantity falls into, with no per-unit math. The price field is the total flat fee for that tier, not a per-unit rate.Example: 15 seats → tier 2 applies → flat fee of $120.00 (quantity is ignored in the calculation)

{
  "mode": "CUSTOM",
  "name": "Storage Tier",
  "quantity": 15,
  "pricing": {
    "pricingModel": "STAIRSTEP",
    "prices": [
      { "currencyCode": "USD", "price": "80.00",  "maxQuantity": 10 },
      { "currencyCode": "USD", "price": "120.00", "maxQuantity": 20 },
      { "currencyCode": "USD", "price": "150.00" }
    ]
  },
  "recurringBillingPeriod": "P12M",
  "recurringBillingFrequency": "MONTHLY"
}

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.

​Contracts

​Create a contract

​Retrieve a contract

​Update a contract

​Terminate a contract

​Contract changes

​Create a change

​Line item changes

​Retrieve changes for a contract

​Retrieve a change

​Update a change

​Accept a change

​Cancel a change

​Preview a change

​Renewal quotes

​Create a renewal quote

​Contract properties

​Contract status

​Address format

​Line items

​Modes

​Recurring billing

​Taxes

​Pricing models

Contracts

Create a contract

Retrieve a contract

Update a contract

Terminate a contract

Contract changes

Create a change

Line item changes

Retrieve changes for a contract

Retrieve a change

Update a change

Accept a change

Cancel a change

Preview a change

Renewal quotes

Create a renewal quote

Contract properties

Contract status

Address format

Line items

Modes

Recurring billing

Taxes

Pricing models