HubSpot Subscriptions
Browse all Hubspot APIs42
AI ReadinessFoundational (D-)42/100
Official vendor OpenAPI document · agent-readyPaymentsBilling Subscriptionsoauth2,apiKey11 EndpointsREST
For 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.
Use for: I need to create a subscription record in HubSpot Commerce, Retrieve a subscription by its CRM ID, Search for subscriptions renewing in the next 7 days, Update a subscription status to cancelled
Not supported: Does not handle billing, dunning, or cancellation at an external processor - use only for managing HubSpot CRM subscription records.
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.
Install Jentic One Beta
Connect the Subscriptions to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Subscriptions, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubspot.com%2Fhubspot-crm-subscriptions" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubspot.com%2Fhubspot-crm-subscriptions" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Subscriptions API.
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
Patterns agents use Subscriptions API for, with concrete tasks.
★ 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.
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.
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.
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.
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
11 endpoints — 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.
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
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
Jentic AI Readiness Score
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
S
Subscriptions
- Foundational (D-)42/100
74
Foundational Compliance63
Developer Experience & Jentic Compatibility18
AI-Readiness & Agent Experience94
Agent Usability63
Security67
AI DiscoverabilityPowered by JenticScoring Framework 1.0.0 | Scoring Engine 0.4.0
Show dimension breakdown
74
Foundational Compliance
Base layer of spec validity and structural soundness.
Grade: A-Signals: 4
94%
Lint Results
Aggregated quality score from linter diagnostics, weighted by severity.
100%
Resolution Completeness
Percentage of `$ref` references that resolve successfully.
0%
Specification Validity
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
100%
Structural Integrity
Structural correctness score based on schema issues using logarithmic dampening.
63
Developer Experience & Jentic Compatibility
Clarity, completeness, and ingestion readiness for developers and tooling.
Grade: BSignals: 4
8%
Example Density
How richly the API is illustrated with examples.
95%
Example Validity
Percentage of examples that conform to their schemas.
50%
Response Coverage
Percentage of operations with complete response definitions (success, client error, server error).
100%
Tooling Readiness
Health of API ingestion, bundling, and resolution within Jentic pipelines.
18
AI-Readiness & Agent Experience
Semantic breadth, depth, and agent comprehension for AI systems.
Grade: FSignals: 4
19%
Description Coverage
Coverage of descriptions across API elements.
0%
Error Standardization
Coverage of RFC 9457 Problem Details for error responses.
0%
OperationId Quality
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
53%
Summary Coverage
Coverage of summaries across operations/tags/info.
94
Agent Usability
Functional utility, complexity comfort, and AI orchestration readiness.
Grade: A+Signals: 1
94%
Complexity Comfort
Agent comfort level based on API operational and structural complexity.
63
Security
Trust, risk posture, and security compliance.
Grade: BSignals: 1
63%
Authentication Strength
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
67
AI Discoverability
Findability, semantic richness, and reasoning readiness.
Grade: B+Signals: 1
67%
Descriptive Richness
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
Alternative
Stripe
Stripe Billing manages real subscription state and billing - HubSpot subscriptions are the CRM-side mirror.
Choose Stripe when the agent must change billing state (cancel, pause, change price); use HubSpot Subscriptions to mirror those changes into CRM.
FAQs
Specific to using Subscriptions API through Jentic.
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.
GET STARTED