What HubSpot Tier Does a Client Portal Actually Need?

Every agency running client portals gets the question eventually: "are we paying HubSpot for things we do not use?" It is a fair question and a dangerous one to answer casually, because the two possible mistakes are not symmetrical. Overstate what a client needs and you look like you are protecting a line item. Understate it and they downgrade, lose a feature they were quietly relying on, and the failure has your name on it.

So we built a tool to answer it properly, gave it away, and this post is what we learned making it. It is free, open source, and read-only: HubSpot License Fit.

Why can't you just look up what a client is paying?

Because HubSpot's API does not expose it. The account information endpoint returns the portal ID, account type, timezone, currency and data hosting location. There is no subscription object, no tier field, and no entitlement list anywhere in the public API.

That constraint sounds like a limitation. It is actually the most useful thing about this problem, because it forces the honest framing. A tool cannot tell you what somebody pays, so it must not pretend to. What it can do is compute the floor: the cheapest tier the portal's current usage requires. The agency compares that to the invoice, which is the one document the agency can actually see.

This is why our tool never prints a sentence like "you are wasting $18,000 a year." That is a claim about a contract nobody in the loop can read, and it ages the moment HubSpot changes packaging or the client changes seats.

What does "the floor your usage sets" mean?

It means working backwards from evidence. If three custom objects exist in a portal, some Enterprise subscription is in play, because custom objects do not exist below Enterprise. If eight deal pipelines exist, the account is above Starter, because Starter allows two.

The useful output is not "Sales Hub Professional." It is "Sales Hub Professional, because five sequences exist." The first cannot be argued with or verified. The second can be checked in ninety seconds by anyone with portal access, which is exactly what you want when the conclusion is going in front of a client.

We enforced that in code: the tool refuses to print a tier claim that does not name the observation driving it.

Which features actually force a tier?

Far fewer than you would guess. HubSpot ships hundreds of features, and almost all of the packaging churn happens at the margins where it does not change anybody's subscription decision. The gates that genuinely force a tier are roughly twenty: custom objects, deal and ticket pipeline counts, workflows and what sits inside them, sequences, teams, permission sets, association labels, calculated properties, business units, HubDB, memberships, campaigns, goals and multiple currencies.

Narrowing to twenty is a maintenance decision as much as an accuracy one. Tracking twenty gates is an order of magnitude cheaper to keep correct than tracking two hundred, and each individual claim ends up more reliable because it gets checked more often.

That maintenance burden is real, and we have the scars. In one verification sweep of our own reference data, the first four tier claims we checked came back half wrong. Association labels had moved from Enterprise to Professional. Quotes were not where we had recorded them at all.

What does a 403 have to do with a license review?

This is the part that matters most and gets the least attention, so it is worth being blunt about.

When you read a HubSpot portal with a properly scoped read-only token, some endpoints refuse you. The teams endpoint returns 403 on most tokens even when teams plainly exist. If your review treats that refusal as "this portal has no teams," you have produced a finding that points a client toward a downgrade, and the downgrade will break something.

A refused read and an empty result are different answers. They have to stay separate all the way to the output. Our tool keeps three states, not two: the gate fired, the gate is genuinely clear, or the gate could not be read. The third one gets its own appendix listing the endpoint and the scope that would fix it.

There is a wrinkle that makes this harder than it sounds: HubSpot's 403 response does not name the missing scope. Every scope failure returns the same generic message pointing at the documentation. Any tool that tells you which scope to grant is using its own mapping, not quoting the API.

Where a refusal can be routed around, it should be. Teams is a tier-deciding gate, so when the teams endpoint refuses, we count teams from owner records instead, and the report says which source answered the question.

What HubSpot ships itself, and why it fools tier audits

Here is the trap that would have made our tool wrong on every portal on earth, including free ones.

Calculated properties are a Professional feature. So a naive check looks for properties carrying a calculation formula and, finding some, concludes Professional. But HubSpot ships its own calculated properties into every portal. days_to_close is one. When we ran the check against our own portal, 21 contact properties carried a calculation formula and every single one of them was HubSpot's, not ours. User-created calculated properties: one.

Association labels have the identical problem. Every portal ships Primary and Billing Contact as HubSpot-defined labels. Only labels somebody created themselves say anything about tier.

The fix in both cases is to filter on who made the thing, not whether it exists. It is a two-line change and it is the difference between a tool that works and a tool that confidently upsells every client you point it at.

What we found pointing it at our own portal

We ran it against our own HubSpot portal before anyone else's, which is the only honest order to do this in. It read 828 contact properties, 398 of them created by us rather than shipped by HubSpot, against 46 users. It found 113 workflows, 58 of them disabled.

Neither of those is a tier problem. Both are the kind of finding that starts a real conversation, and neither needs a tier table to be true. That is why the tool's first section is pure observation with no claims in it at all: counts stay true forever, while tier claims expire the next time HubSpot reorganizes its packaging.

Which they do. HubSpot's own product catalogue, read while building this, puts Enterprise deal pipelines at 100 per account. Our older reference data said 50. Every tier claim the tool makes therefore carries the date it was verified, and the whole table expires itself after 60 days, downgrading every claim to "unverified, confirm before quoting" rather than quietly serving stale data to someone about to advise a downgrade.

Why it is read-only, and why that is the product

The tool issues HTTP GET requests and nothing else. Not as a policy note in a readme: there is one function that builds every request and it refuses any other method, and a test that fails the build if a write verb appears anywhere in the source.

Two reasons, and the second is the one worth stealing.

The first is trust. An agency asking a client for API access to their portal is having a security conversation. "It can only read, and here is the test that proves it" is a much shorter conversation than "we promise."

The second is where the line sits. A tool that tells you what is wrong makes an agency valuable. A tool that fixes it replaces one. Diagnosis is worth giving away for free precisely because the remediation is the work, and that is the same instinct behind our white-label portal audits, which exist to turn a messy inherited portal into a prioritized roadmap rather than a status report.

There is a related decision we are quietly proud of. Some HubSpot scopes have no read-only variant: content, the forms scope, and behavioral event definitions all grant write alongside read. We do not ask for them. The features behind those scopes come back in the report as unreadable, with that as the stated reason, because asking an agency to grant write access to a client portal in order to run a diagnostic would undermine the entire point.

What it will not do

It will not tell you what a client is paying, and it will not tell you to downgrade. It reports a floor and an appendix of what it could not see, and the judgment stays with the person holding the invoice and the client relationship.

It also cannot answer three tier-deciding questions at all, because HubSpot exposes no endpoint for them: single sign-on, content partitioning, and nested team structures. Those are listed in the output with instructions to check them by hand, rather than silently omitted, because a gap you know about is a different thing from a gap you do not.

How to run it

It is a Python package with no dependencies, so there is nothing to install:

git clone https://github.com/meticulosity/hubspot-license-fit.git
cd hubspot-license-fit
python3 -m license_fit --dry-run

The dry run renders a complete report from a bundled fixture without contacting anything and without a token, so you can see exactly what it produces before granting access to a client's portal. Then create a private app in the portal, grant the read scopes it lists, and point it at the real thing.

It also works as a Claude skill, so you can ask the question in plain language rather than reading Markdown output, which matters more than it sounds when the person asking is an account manager rather than an operator.

If you would rather hand the whole review to someone else, portal audits are one of the things we do for agencies under their brand. If you are doing it yourself, our guides to conducting a comprehensive agency HubSpot audit and expert HubSpot portal audits cover the parts a tool cannot reach, and how seat types interact with admin permissions is worth reading before anybody touches a subscription.