canonical: https://jentic.com/apis/hubspot.com/hubspot-crm-taxes

# HubSpot Taxes

The HubSpot CRM Taxes API manages Tax records - the named tax rates that HubSpot Commerce applies to line items on quotes, invoices, and subscriptions. Each Tax record has a label, rate, and optional jurisdiction metadata, and can be associated with the line items it applies to. The API exposes single-record CRUD, batch read, batch create, batch update, batch upsert by unique property, batch archive, and a search endpoint with filters and sorting.

## For AI agents

Create, read, update, and search HubSpot CRM Tax records - the tax rates HubSpot Commerce applies to quote and invoice line items - through /crm/v3/objects/taxes.

## Scope

Does not calculate tax, file returns, or determine nexus - use for managing named tax rate records inside HubSpot CRM only.

## Capabilities

- Create a new tax rate via POST /crm/v3/objects/taxes
- Update a tax rate or label using PATCH /crm/v3/objects/taxes/{taxId}
- List all configured tax rates with GET /crm/v3/objects/taxes
- Search taxes by label or rate via POST /crm/v3/objects/taxes/search
- Bulk-create tax rates per jurisdiction with POST /crm/v3/objects/taxes/batch/create
- Upsert tax rates keyed by an external code via POST /crm/v3/objects/taxes/batch/upsert
- Archive a tax rate that is no longer applied with DELETE /crm/v3/objects/taxes/{taxId}

## Use cases

### Loading Tax Rates From an External Tax Service

Companies that calculate tax in an external service (Avalara, TaxJar, Stripe Tax) often need the resulting named rates to exist in HubSpot so they appear correctly on quotes and invoices. A scheduled job pulls the latest rates and uses POST /crm/v3/objects/taxes/batch/upsert keyed by an external_tax_code custom property. New rates are created, existing ones updated, and obsolete ones archived in a follow-up call.

Example prompt: Call POST /crm/v3/objects/taxes/batch/upsert with idProperty='external_tax_code' and inputs containing label, rate, and jurisdiction for each tax rate from the external service.

### Per-Jurisdiction Tax Configuration

B2B businesses selling across regions need tax records for each jurisdiction (VAT for the UK and EU member states, GST for Canada, state sales tax for the US). Using POST /crm/v3/objects/taxes/batch/create the configuration runs once during setup, creating dozens of rates in seconds. Quotes and invoices generated against the right jurisdiction line items then pick up the correct tax rate automatically.

Example prompt: Call POST /crm/v3/objects/taxes/batch/create with one input per jurisdiction (label='UK VAT 20%', rate=20, etc.).

### Tax Rate Audit and Cleanup

Finance teams periodically audit tax records to remove rates that are no longer used or have been superseded by new legislation. POST /crm/v3/objects/taxes/search returns all records (paged), the team flags obsolete entries, and POST /crm/v3/objects/taxes/batch/archive removes them in one call. Updates to active rates are applied via POST /crm/v3/objects/taxes/batch/update.

Example prompt: Call POST /crm/v3/objects/taxes/search to list all tax records, identify those with obsolete labels, then POST /crm/v3/objects/taxes/batch/archive with their IDs.

### AI Agent Tax Lookup During Quote Generation

An AI quoting agent generates a HubSpot quote and needs to attach the right tax rate to each line item based on jurisdiction. Through Jentic the agent searches for tax operations, queries existing tax records by jurisdiction label, and uses the returned taxId on line item creation. Jentic stores OAuth credentials in its vault so the agent only handles scoped execution tokens.

Example prompt: Search Jentic for 'find hubspot tax rate by jurisdiction', load the search operation, and execute POST /crm/v3/objects/taxes/search filtered by label='UK VAT 20%'.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /crm/v3/objects/taxes | Create a tax rate |
| GET | /crm/v3/objects/taxes/{taxId} | Read a tax rate |
| PATCH | /crm/v3/objects/taxes/{taxId} | Update a tax rate |
| DELETE | /crm/v3/objects/taxes/{taxId} | Archive a tax rate |
| POST | /crm/v3/objects/taxes/search | Search tax rates |
| POST | /crm/v3/objects/taxes/batch/upsert | Upsert tax rates by external key |
| POST | /crm/v3/objects/taxes/batch/create | Batch create tax rates |

## Key resources

- **Basic** — Single-record CRUD for Tax records on /crm/v3/objects/taxes.
- **Batch** — Batch read, create, update, upsert, and archive endpoints for managing many tax rates per request.
- **Search** — Filter tax records by label, rate, or custom properties via POST /crm/v3/objects/taxes/search.

## Why Jentic

- **Setup:** Wiring HubSpot Taxes by hand means learning its OAuth2 access token or private app token auth, targeting the api.hubapi.com host, and handling batch and search calls yourself. Through Jentic you install once, import HubSpot Taxes from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The Taxes API puts the tax id in the URL path (/crm/v3/objects/taxes/{taxId}), so a rule can pin your agent to one tax rate record for read and update. You choose the operations it may call, so destructive ones like deleting a rate or batch upsert are not included unless you add them.
- **Credential handling:** Your HubSpot access token or private app token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a HubSpot tax rate' or 'find a named tax record', and Jentic returns the matching Taxes operation with its input schema so the agent configures rates without browsing the reference docs.

## Related APIs

- **Avalara AvaTax** — Avalara calculates and files tax across thousands of jurisdictions with real-time rate determination.
- **TaxJar API** — TaxJar focuses on US sales tax calculation, nexus tracking, and filing for e-commerce.
- **HubSpot Line Items** — Tax rates are applied to line items on quotes and invoices - manage line items together with their tax associations.

## FAQ

### What authentication does the HubSpot Taxes API use?

It supports OAuth 2.0 (recommended for public apps) and HubSpot private app access tokens passed as a Bearer token in the Authorization header. Through Jentic the token is stored encrypted in the vault and injected at execution time so the agent never holds the raw secret.

### Can I associate a tax record with line items through this API?

Yes. The Taxes API exposes the standard CRM associations pattern, so you can pass association inputs when creating or updating a tax record, or use the Associations API to link existing tax records to line items after the fact.

### What are the rate limits for the HubSpot Taxes API?

HubSpot enforces 100 requests per 10 seconds for OAuth apps and 190 per 10 seconds for private apps on Enterprise tiers, plus daily quotas. Use POST /crm/v3/objects/taxes/batch/create and batch/upsert (up to 100 records per request) when loading many rates at once.

### How do I keep HubSpot tax rates in sync with Avalara through Jentic?

Search Jentic for 'upsert hubspot tax rates', load POST /crm/v3/objects/taxes/batch/upsert, and execute it with idProperty set to your external_tax_code property and inputs containing the latest rates from Avalara. Jentic returns typed responses for each upserted record.

### Does the Taxes API calculate tax for an order?

No. This API only manages named tax rate records. Actual tax calculation happens inside HubSpot Commerce when those rates are applied to line items, or in an external tax service whose results you sync into HubSpot via this API.

### Can I archive a tax rate that is still attached to historical line items?

Yes - archiving a tax record with DELETE /crm/v3/objects/taxes/{taxId} removes it from active selection but leaves historical line item associations intact. To remove permanently you must use HubSpot's GDPR delete process.

### Can I limit what my agent is allowed to do with the HubSpot Taxes API?

Yes. Jentic One is self-hosted, so your own rules decide which Taxes operations and credentials the agent may use. Because the tax id sits in the URL path (/crm/v3/objects/taxes/{taxId}), you can pin the agent to reading and updating a single tax rate record. You choose the operations it can call, so destructive actions like DELETE /crm/v3/objects/taxes/{taxId} or POST /crm/v3/objects/taxes/batch/upsert stay out of reach unless you add them.