Which HubSpot platform version should I be on in 2026?

TL;DR

The 30-second answer

The current platform version is 2026.03, released March 30, 2026. Use it for every new project. If you're already running an app on the developer platform, the version you should target depends on three things: whether HubSpot has set a hard deprecation date for your current version, whether you use serverless functions, and how much time you have to do the work.

Two hard dates drive every decision below. 2023.2 is already sunset (Oct 1, 2025 — uploads fail), and 2025.1 deprecates on August 1, 2026. Everything else is a preference, not a deadline.

01 · Matrix

Platform version comparison matrix

Every platform version HubSpot currently lists in its versioning docs, with the support status, the Node.js floor, the serverless-function story, and the date by which you must move off it.

Source of truth: HubSpot's Developer platform and API versioning page. HubSpot ships a new platform version every six months (March + September) and runs a three-stage lifecycle — Current for 6 months, then Supported until 18 months after GA, then Unsupported (uploads fail).

02 · Calendar

The full deprecation calendar

Pin this in whatever planning doc you use. Every date is a hard date — HubSpot has set the cutover; you cannot ask for an extension.

If you only remember one date from this guide, remember August 1, 2026 — that's the next forced migration for anyone still on 2025.1, and 2025.1 is the version most established apps are sitting on.

03 · New projects

Which version should a new project use?

Use 2026.03. It's the current version, it's the only version that supports both the modern file-based project framework and serverless functions inside the same project, and it's the version every HubSpot doc and CLI command now defaults to. There is no good reason to scaffold a new project on an older platform version.

The one historical reason people pinned 2025.1 instead of 2025.2 — needing serverless functions — went away when 2026.03 shipped. The one reason people pinned 2025.2 — wanting the modern projects framework without serverless — also no longer applies, because 2026.03 is a strict superset of 2025.2.

{
  "name": "my_project",
  "srcDir": "src",
  "platformVersion": "2026.03"
}

04 · 2023.2 path

I'm on 2023.2 — what do I do now?

2023.2 was sunset on October 1, 2025. Any hs project upload attempt against a 2023.2 project now fails server-side, regardless of CLI version. The project still runs in production until you redeploy, but you cannot ship a code change until you migrate.

Your migration target is 2026.03. The path:

1. Audit whether the project uses serverless functions (src/app/app.functions/ exists, and appFunctions is non-empty in your config).
2. If it uses legacy CRM cards, convert them to app cards before migrating — hs project migrate will refuse otherwise.
3. Run hs project migrate to convert the project shape to 2026.03. The CLI rewrites hsproject.json, splits any legacy serverless.json into per-function *-hsmeta.json files, and updates the directory layout.
4. Re-upload with hs project upload and validate the build.

A common failure mode here is the "create empty project, copy modules" escape hatch — if hs project migrate fails on a specific file (the CLI's error messages can be cryptic), scaffold a fresh 2026.03 project with hs project create --platform-version 2026.03 and move modules in by hand. The migrate command is fancier; the hand-copy is more reliable.

05 · 2025.1 path

I'm on 2025.1 — when do I have to move?

August 1, 2026. After that date HubSpot stops accepting uploads at platform version 2025.1. That gives you roughly two months from today's date (May 19, 2026) — short, but workable if you start now.

The 2025.1 → 2026.03 migration is the gentlest of the three covered here, because 2025.1 already uses the projects framework. The two real changes:

• Node.js version bumps from v20 to v22. Update your local Node, your CI image, and any per-function runtime declarations.
• Serverless function configuration moves from serverless.json to per-function *-hsmeta.json files. hs project migrate does this rewrite for you, but read the diff before committing — the new shape exposes a secretKeys array instead of the old secrets array, and the entrypoint path is now absolute from the project root.

If you do not use serverless functions, the migration is mostly a platformVersion bump and a hs project upload. If you do, give it a half-day and budget a re-test of every function endpoint.

06 · 2025.2 path

I'm on 2025.2 — should I jump to 2026.03?

Yes, unless you have no serverless functions and no near-term need for them. 2025.2 is supported through March 2027, so there's no immediate forcing function — but the migration is the cheapest of any version jump (just bump platformVersion in hsproject.json and re-upload), and it unlocks serverless functions without breaking anything else.

If you stay on 2025.2, the only durable downside is that you cannot use HubSpot-hosted serverless functions — you have to keep porting that logic to Cloudflare Workers, AWS Lambda, or Vercel and calling it via hubspot.fetch(). That's a valid choice (and what HS-X does by default), but it's a choice you should make on architectural grounds, not because the upgrade is hard.

 {
   "name": "my_project",
   "srcDir": "src",
-  "platformVersion": "2025.2"
+  "platformVersion": "2026.03"
 }

Then hs project upload. That's the entire 2025.2 → 2026.03 migration for apps that don't use serverless functions.

07 · Background

Why did serverless functions disappear and come back?

When 2025.2 shipped in September 2025, HubSpot rebuilt the project framework around a new file-based build-and-deploy model — but project-built apps on 2025.2 lost serverless function support in the transition. The official guidance for 2025.2 was: if you need serverless functions, stay on 2025.1; otherwise, move to 2025.2 for the new build system.

2026.03 resolves the split. It uses the same file-based projects framework as 2025.2, but reintroduces serverless functions with a new per-function configuration shape (*-hsmeta.json) instead of the old monolithic serverless.json. Migration from 2025.2 to 2026.03 does not require any code changes if you don't use serverless functions — just the platformVersion bump.

The takeaway: the 2025.2-without-serverless era is over. If you ported your function logic to an external runtime during that window (which many teams did), you can keep that architecture — HS-X recommends it for portability — or you can move it back into HubSpot-hosted serverless on 2026.03. Both are valid; the runtime is a deploy-time choice, not a platform-version constraint.

08 · Check yours

How do I check which version my project is on?

Open the top-level hsproject.json in your project directory and read the platformVersion field. That single string is the authoritative answer.

{
  "name": "my_project",
  "srcDir": "src",
  "platformVersion": "2026.03"
}

If there's no hsproject.json file in your project, your app is not on the projects framework at all — it's a legacy private or public app. Those migrate via hs app migrate (a different command), and the path depends on whether the app is listed on the HubSpot Marketplace and how many accounts it's installed in. The migration overview in HubSpot's docs has the full decision tree.

Related

Related questions

• Legacy CRM cards → UI Extensions migration playbook — covers the October 31, 2026 deadline that runs in parallel with the platform-version deadlines above.
• Where did serverless functions go in 2025.2? — the escape-hatch guide for teams who got caught mid-migration.
• Surviving hs project migrate failures — error-by-error decision tree for the migration command this guide tells you to run.
• Legacy public app → projects: the full rebuild guide — for apps that pre-date the projects framework entirely.
• Private app vs public app vs OAuth — decision tree — orthogonal to platform version, but the second question people ask after this one.

Last updated: May 19, 2026. Sourced from HubSpot's Developer platform and API versioning and Determine your migration path to 2026.03 pages. Refreshed whenever HubSpot ships a new platform version (every six months, March and September).