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

# HubSpot Subscriptions

The HubSpot Commerce Subscriptions API manages subscription records inside HubSpot Commerce - the CRM-side representation of a recurring billing relationship between a contact and a product. It exposes the standard CRM v3 object pattern with batch read, create, update, archive, search, and upsert against the subscriptions object. Each subscription can carry properties such as billing cycle, next renewal date, status, and associated contact, deal, and line items, mirroring an external billing system into the CRM.

## For AI agents

Create, read, update, archive, search, and upsert HubSpot Commerce subscription records, with batch endpoints for syncing recurring billing state from an external billing system.

## Scope

Does not handle billing, dunning, or cancellation at an external processor - use only for managing HubSpot CRM subscription records.

## Capabilities

- Create subscription records with billing cycle, next renewal date, and status properties
- Batch upsert subscriptions by an external billing id to keep HubSpot in sync without duplicates
- Search subscriptions by status, contact, or renewal date using filter groups
- Retrieve a subscription with its associated contacts, deal, and line items in one call
- Update subscription state (paused, cancelled, renewed) as the billing system changes
- Archive cancelled subscriptions in batch to keep active CRM views clean
- Page through all subscription records for export or churn reporting

## Use cases

### Billing System Mirror

Mirror subscription state from an external billing platform into HubSpot so sales and customer success can see active and at-risk subscriptions in the CRM. The batch upsert endpoint handles up to 100 subscriptions per request keyed on the billing system's subscription id, eliminating duplicates from retried webhooks.

Example prompt: POST 100 subscription payloads to /crm/v3/objects/subscriptions/batch/upsert with idProperty = external_subscription_id and hs_status from the billing source.

### Renewal Pipeline

Search for subscriptions renewing in the next two weeks so customer success can run a renewal play. The search endpoint filters by hs_next_renewal_date and status, returning the subscription id, contact id, and amount for the renewal queue.

Example prompt: POST /crm/v3/objects/subscriptions/search with filterGroups for hs_status = ACTIVE and hs_next_renewal_date in the next 14 days, returning hs_amount and contact id.

### Churn Analysis

Search for subscriptions cancelled in the last quarter, group by cancellation reason, and feed into a churn dashboard. The CRM-side record keeps cancellation context alongside contact properties for cohort analysis.

Example prompt: Search /crm/v3/objects/subscriptions/search with filterGroups for hs_status = CANCELLED and hs_cancelled_date in the last 90 days, returning hs_cancellation_reason and contact id.

### AI Agent Renewal Outreach

An AI agent runs daily to identify upcoming renewals, drafts a personalised outreach message, and assigns a task to the account owner. Jentic exposes the search and contact read operations with typed schemas, so the agent does not need to read HubSpot docs.

Example prompt: Search subscriptions renewing in the next 14 days, fetch the contact owner, and create a task for each owner via the HubSpot tasks API with the renewal context.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /crm/v3/objects/subscriptions/batch/create | Create subscription records in batch |
| POST | /crm/v3/objects/subscriptions/batch/upsert | Idempotent upsert by external id |
| POST | /crm/v3/objects/subscriptions/batch/read | Read subscriptions in batch by ID |
| POST | /crm/v3/objects/subscriptions/batch/update | Update subscription properties in batch |
| POST | /crm/v3/objects/subscriptions/search | Search subscriptions by filter groups |
| GET | /crm/v3/objects/subscriptions/{subscriptionId} | Retrieve a single subscription |
| GET | /crm/v3/objects/subscriptions | List subscriptions with pagination |

## Key resources

- **subscriptions** — Subscription object with billing cycle, status, renewal date, and amount.
- **Batch operations** — Batch read, create, update, upsert, and archive endpoints for billing-system sync.
- **Search** — Filter subscriptions by status, renewal date, contact, or cancellation reason.

## Why Jentic

- **Setup:** Wiring the HubSpot Subscriptions 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 Subscriptions 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 subscription scopes your agent needs and you choose which operations it may call: you can allow reading and searching subscription records while leaving batch updates 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 'sync a subscription to HubSpot' or 'read subscription records', and Jentic returns the matching subscriptions operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Commerce Payments** — Records the payments captured against an active subscription.
- **Invoices** — Tracks invoice records issued to subscribers.
- **Stripe** — Stripe Billing manages real subscription state and billing - HubSpot subscriptions are the CRM-side mirror.

## FAQ

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

It supports OAuth 2.0 and HubSpot private app tokens. Through Jentic, tokens are stored encrypted in the vault and a scoped token is injected per request, keeping raw credentials out of the agent context.

### Can I cancel a subscription via the HubSpot Subscriptions API?

You can update the CRM record (set hs_status to CANCELLED via PATCH /crm/v3/objects/subscriptions/{subscriptionId}) but the API does not cancel billing at an external processor. Cancel at the billing system first, then update the HubSpot record to reflect that state.

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

Standard CRM v3 limits apply - 100 requests per 10 seconds for OAuth apps and 110 per 10 seconds for private apps. Use /crm/v3/objects/subscriptions/batch/upsert (up to 100 records per call) when syncing from a billing system.

### How do I upsert subscriptions through Jentic?

Run the Jentic search "upsert hubspot subscription" to find POST /crm/v3/objects/subscriptions/batch/upsert, load the schema, and execute with idProperty set to your billing system's subscription id. Jentic handles authentication.

### Is the HubSpot Subscriptions API free?

Access requires HubSpot Commerce Hub. There is no per-call HubSpot fee on top of the Commerce subscription, but the underlying tier price applies.

### Can I associate a subscription with a deal and a contact?

Yes - pass an associations array on create, or use the CRM Associations API afterwards, to link a single subscription to a deal, contact, and line items. The single-record GET supports an associations parameter to return linked IDs in one call.

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

Yes. Because you run Jentic One yourself, your own rules decide which subscription operations and credentials the agent may use, so you can grant only the per-object HubSpot scopes it actually needs. For example, you can allow the agent to read a subscription (GET /crm/v3/objects/subscriptions/{subscriptionId}) and run search (POST /crm/v3/objects/subscriptions/search) while keeping batch create, update, upsert, and archive out of its allowed set. Because your HubSpot OAuth or private app token is stored on your own instance and injected only at execution time, the agent can call only the operations you have explicitly permitted.