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

# HubSpot Fees

The HubSpot Fees API manages fee records used on quotes and line items, exposing single and batch CRUD plus search across /crm/v3/objects/fees. Fees represent shipping, handling, processing, or service charges that are added to a customer-facing quote alongside the product line items. Agents use this API to maintain a reusable fee catalogue, attach fees to quotes, and reconcile billed fees in commission or revenue reporting.

## For AI agents

Create, update, search, and batch-manage HubSpot fee records used on quotes and line items via /crm/v3/objects/fees.

## Scope

Does not calculate quote totals, run pricing approval workflows, or process payment - use for managing reusable fee records inside HubSpot CRM only.

## Capabilities

- Create reusable fee records via POST /crm/v3/objects/fees
- Update fee labels or amounts with PATCH /crm/v3/objects/fees/{feeId}
- Search fees by amount, label, or custom property through POST /crm/v3/objects/fees/search
- Bulk-import a fee catalogue with POST /crm/v3/objects/fees/batch/create
- Upsert fees by external ID using POST /crm/v3/objects/fees/batch/upsert
- Archive obsolete fees via DELETE /crm/v3/objects/fees/{feeId}

## Use cases

### Fee Catalogue Management

Maintain a single source of truth for shipping, handling, and processing fees so quotes are consistent across reps. The batch create endpoint imports a fee list in one request, and the search endpoint lets a quote generator pick fees by region or service tier. Updating a fee centrally propagates the new amount to every quote that references the fee record.

Example prompt: Batch-create six regional shipping fees via POST /crm/v3/objects/fees/batch/create with a region property set to NA, EU, or APAC.

### Quote-Time Fee Lookup

When generating a quote, search for the right fee - for example, 'standard shipping NA' - and attach it to the quote so totals reflect the correct charge. The search endpoint accepts filterGroups, sorting, and paginated results so a quote generator can fetch candidates fast even with hundreds of active fees. Apply the fee ID through the Quotes API afterwards.

Example prompt: Search HubSpot fees where label contains 'shipping' and region equals NA, sorted by hs_value ascending, returning the top result.

### Fee Reconciliation

Pull all fees referenced on closed-won deals to reconcile billed amounts against the commission or finance system. The list and batch read endpoints retrieve fee records by ID with their full property set, so a reconciliation job can match each fee to the corresponding ledger line.

Example prompt: Batch-read fees for the IDs referenced on last quarter's closed deals via POST /crm/v3/objects/fees/batch/read, returning hs_label and hs_value.

### Agent-Driven Fee Updates via Jentic

An AI ops agent reading a memo about a price change updates HubSpot fee records without an engineer touching the CRM. Through Jentic the agent searches for the patch operation, loads its schema, and executes it with the new amount. The flow runs on a single Jentic credential without exposing the HubSpot key.

Example prompt: Use Jentic to search 'update a HubSpot fee record', load the PATCH /crm/v3/objects/fees/{feeId} schema, and execute it with the new hs_value.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /crm/v3/objects/fees | List fees with pagination |
| POST | /crm/v3/objects/fees | Create a fee record |
| PATCH | /crm/v3/objects/fees/{feeId} | Update a fee |
| POST | /crm/v3/objects/fees/batch/create | Batch-create up to 100 fees |
| POST | /crm/v3/objects/fees/batch/upsert | Batch-upsert fees by external ID |
| POST | /crm/v3/objects/fees/search | Search fees by property filters |

## Key resources

- **Basic** — Single-record CRUD on fee objects
- **Batch** — Bulk read, create, update, upsert, and archive across up to 100 fees per request
- **Search** — Filter, sort, and paginate fees by any property

## Why Jentic

- **Setup:** Wiring the HubSpot Fees API by hand means handling its OAuth 2.0 authorization-code flow or a private app token, targeting api.hubapi.com, and building batch and search payloads yourself. Through Jentic you install once, import HubSpot Fees from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** HubSpot gates this API with per-object OAuth scopes, so you grant only the fee scopes your agent needs and you choose which operations it may call: you can allow reading and searching fee records while leaving create and update out of the allowed set unless you add them.
- **Credential handling:** Your HubSpot OAuth 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 fee record' or 'list fee records', and Jentic returns the matching fees operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot Quotes** — Attach fee records to customer-facing quotes
- **HubSpot Line Items** — Apply fees alongside product line items on a deal or quote
- **HubSpot Discounts** — Discounts are the inverse pattern - subtract from quote totals
- **Salesforce** — Salesforce CPQ adds product-level surcharges through its own data model

## FAQ

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

Fees accepts OAuth 2.0 access tokens and HubSpot private app API keys passed in the private-app or private-app-legacy header. Through Jentic the credential lives in your Jentic One instance and is injected at execution time so it never enters the agent's context.

### Can I attach a fee to a quote through this API?

The Fees API only manages the fee records themselves. To attach a fee to a quote or line item, reference its ID through the Quotes or Line Items APIs - Jentic exposes those as separate operations you can chain after creating the fee.

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

Account-level limits apply - typically 100 requests per 10 seconds for OAuth apps and 190 per 10 seconds for private apps on paid tiers. Use POST /crm/v3/objects/fees/batch/create for catalogue imports since each batch counts as one request.

### How do I search fees through Jentic?

Run jentic.search('search HubSpot fee records'), load the schema for POST /crm/v3/objects/fees/search, and execute it with a filterGroups payload (for example, hs_label contains 'shipping'). Jentic returns matching fees as structured JSON ready for the next step.

### Can I upsert a fee by an external ID?

Yes. POST /crm/v3/objects/fees/batch/upsert accepts an idProperty referencing a unique custom property such as an internal SKU. HubSpot inserts new fees and updates existing ones in the same call without producing duplicates.

### What is the difference between a fee and a discount in HubSpot?

Fees add to a quote total (shipping, handling, processing). Discounts subtract from a quote total (percentage off, promotional reductions). Both attach to quotes, but they live as separate object types and are managed through their own APIs.

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

Yes. Because your Jentic One instance is self-hosted, you decide which fee operations the agent may call and which credentials it uses. For example, you can allow reading and searching fee records via GET /crm/v3/objects/fees and POST /crm/v3/objects/fees/search while leaving create, update, and archive out of the allowed set. This lines up with HubSpot's per-object OAuth scopes, so the agent only ever exercises the fee operations you have explicitly granted.