Taxes API - HubSpot docs

Scope requirements

When you’re creating a quote in HubSpot, you can create and associate a tax as part of the pricing details of the quote.

Please note:The functionality described in this article pertains to the order-level tax object you can create and apply to invoices and subscriptions. This object is distinct from the tax rate object that applies separately to line items only. Learn more about tax rates in the line items API guide.

Create a tax

Taxes are used in conjunction with discounts and fees when determining the pricing details for a quote. Any discounts you associate with your quote will be applied first, followed by associated fees, and then any associated taxes will apply.

{
  "properties": {
    "hs_label": "A percentage-based tax of 6.5%",
    "hs_type": "PERCENT",
    "hs_value": "6.5"
  }
}

After you create a tax, you can use its ID to associate it with a quote. To retrieve a list of taxes you’ve created, you can make a GET request to /crm/objects/2026-03/tax.

Merge taxes

To merge two tax records, make a POST request to /crm/objects/2026-03/tax/merge. The remaining record combines activities, associations, and most property values from both records. For example, merge duplicate taxes to preserve historical context and consolidate their activity timelines. Learn more about what happens when you merge HubSpot records. Include the following in your request body:

Field	Description
`objectIdToMerge`	The record ID to merge with the primary record.
`primaryObjectId`	The record ID of the primary record, which is the record that will remain after the merge.

For example, to merge the record 45678 into the record 12345, your request would look like:

{
  "objectIdToMerge": "45678",
  "primaryObjectId": "12345"
}

In a successful merge response, the id is the record ID of the merged record.

Please note: if an account is enrolled in the Primary ID Preservation for Merged Records public beta, the primary (i.e., the remaining record after a merge) record’s Record ID value (primaryObjectId) is preserved instead of generating a new one. Once enrolled, this behavior applies to all merges, including in HubSpot and all versions of the API.

​Create a tax

​Merge taxes

Create a tax

Merge taxes