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

# HubSpot Invoices

The HubSpot CRM Invoices API exposes the invoice object that sits alongside deals, line items, and quotes in HubSpot Commerce. Agents and integrations can create, read, update, archive, search, and batch-process invoice records, and associate invoices with the contacts, companies, deals, and line items they belong to. It is intended for synchronising invoice data between HubSpot and external billing systems and for building invoice-aware sales workflows inside HubSpot.

## For AI agents

Manage HubSpot Commerce invoice records: create, search, batch-update, and associate invoices with contacts, deals, and line items.

## Scope

Does not handle payment capture, tax calculation, or PDF invoice rendering - use for HubSpot CRM invoice record management only.

## Capabilities

- Create individual or batched invoice records with property values and association references
- Search invoices by property filters such as invoice status, amount, due date, or associated deal
- Update invoice properties via PATCH on a single record or batch update across many records
- Archive invoices that should no longer appear in active reporting without permanently deleting them
- Upsert invoices by a unique property value to keep an external billing system in sync

## Use cases

### Sync Invoices from a Billing System

Mirror invoice records from QuickBooks, Stripe Billing, or NetSuite into HubSpot so sales reps see live billing status next to deals and contacts. The Invoices API supports batch upsert by external ID, which lets a sync job push hundreds of invoices in a single request and keep HubSpot in lock-step with the source. Sync jobs typically run on a 5-15 minute cadence and complete with two batch calls: read existing IDs, then upsert the delta.

Example prompt: Call POST /crm/v3/objects/invoices/batch/upsert with 100 invoice records keyed by an external invoiceNumber property and verify the response status counts match the input.

### Surface Outstanding Invoices in a Sales Workflow

Power a sales-rep dashboard or AI agent that surfaces outstanding invoices for a given account so reps can prioritise collections calls. The search endpoint accepts filter groups on hs_invoice_status and hs_due_date, allowing queries like 'all overdue invoices for accounts owned by this rep'. Returns are paginated and typically respond in under a second for filtered queries against a single account.

Example prompt: POST /crm/v3/objects/invoices/search with a filter group for hs_invoice_status equals OPEN and hs_due_date less than today, returning the first 100 results with id, amount, and associated company.

### Agent-Driven Invoice Triage

An AI agent embedded in a finance copilot can read invoice records, decide which need follow-up, and update properties or trigger associated workflows. Through Jentic, the agent finds the search and update operations by intent, loads the input schemas, and chains them without needing to memorise endpoint paths. This keeps the agent's prompt focused on the business decision instead of on REST plumbing.

Example prompt: Search for invoices where hs_invoice_status equals OPEN and hs_due_date is more than 30 days past, then PATCH each result via /crm/v3/objects/invoices/{invoiceId} to set a follow_up_required custom property to true.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /crm/v3/objects/invoices | Create an invoice |
| GET | /crm/v3/objects/invoices | List invoices |
| GET | /crm/v3/objects/invoices/{invoiceId} | Read a specific invoice |
| PATCH | /crm/v3/objects/invoices/{invoiceId} | Update an invoice |
| POST | /crm/v3/objects/invoices/search | Search invoices by property filters |
| POST | /crm/v3/objects/invoices/batch/upsert | Batch upsert invoices by unique property |

## Key resources

- **Invoices** — Single-record CRUD plus batch read, create, update, archive, upsert, and search for HubSpot Commerce invoices

## Why Jentic

- **Setup:** Wiring HubSpot Invoices by hand means implementing its OAuth2 authorization-code flow (or managing a private-app token), sending every call to api.hubapi.com with the right property and association payloads, and handling token refresh yourself. Through Jentic you install once, import HubSpot Invoices from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** This API uses operations against the invoices object collection, and the invoice id travels in the URL path (/crm/v3/objects/invoices/{invoiceId}) only on reads and updates. Limit the agent to the operations it needs, such as creating and searching invoices, so a write path like update or batch upsert is not included unless you add it.
- **Credential handling:** Your HubSpot 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 invoice' or 'search invoices by status', and Jentic returns the matching invoice operation with its input schema, including its property and association fields, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot CRM Line Items** — Line items are the per-product rows that sit on each invoice, deal, or quote
- **HubSpot CRM Deals** — Invoices are typically created from a closed-won deal in HubSpot
- **Stripe API** — Stripe Invoicing serves the same role outside the HubSpot CRM ecosystem

## FAQ

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

OAuth 2.0 Bearer tokens or HubSpot Private App tokens, sent in the Authorization header. With Jentic, the token is stored encrypted in the vault and the agent receives a scoped reference rather than the raw secret.

### Can I create an invoice and link it to a deal in one call?

Yes. POST /crm/v3/objects/invoices accepts an associations array on the request body so the new invoice is created and linked to a deal, contact, or company in a single request, avoiding a follow-up association call.

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

Rate limits follow the standard HubSpot account-wide quotas: 100 requests per 10 seconds for OAuth apps and 110 for Private Apps, with daily caps that vary by Hub subscription. Batch endpoints count as a single request regardless of the number of records, which is why batch/upsert is the recommended sync pattern.

### How do I search invoices by status and due date through Jentic?

Run pip install jentic, call client.search('search HubSpot invoices'), client.load to get the schema for POST /crm/v3/objects/invoices/search, and client.execute with a filterGroups array combining hs_invoice_status and hs_due_date conditions.

### Can I batch update many invoices at once?

Yes. POST /crm/v3/objects/invoices/batch/update accepts up to 100 records per call with property changes keyed by invoice ID. Use this for status transitions or bulk corrections instead of looping per-record PATCH calls.

### How do I keep invoices in sync with an external billing system?

POST /crm/v3/objects/invoices/batch/upsert keyed by a unique external identifier property (such as quickbooks_invoice_id) handles both create and update in one call, which is the typical integration pattern for syncing from QuickBooks, Stripe Billing, or NetSuite.

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

Yes. Because you run Jentic One yourself, your own rules decide which invoice operations the agent may call and which stored HubSpot credential it uses. You can allow only the operations it needs, such as creating invoices and searching them by status or due date, while withholding write paths like update on /crm/v3/objects/invoices/{invoiceId} or batch upsert unless you explicitly add them. This keeps a read-and-create agent from modifying or bulk-overwriting invoice records it was never meant to touch.