import { GuideHero, GuideSection, GuideOut } from '~/components/Guide';
import { GuideArticleSchema } from '~/components/Guide/GuideArticleSchema';
import { CopyAsMarkdown } from '~/components/CopyAsMarkdown/CopyAsMarkdown';

export const topic = 'Platform & versions';

export const metadata = {
  title: 'Which HubSpot platform version should I be on in 2026? — HS-X',
  description: 'Decision matrix for HubSpot developer platform versions 2023.2, 2025.1, 2025.2, and 2026.03 — deprecation dates, serverless support, and the right migration path.',
  alternates: { canonical: '/docs/answers/which-hubspot-platform-version' },
  openGraph: {
    type: 'article',
    title: 'Which HubSpot platform version should I be on in 2026?',
    description: 'Decision matrix for HubSpot developer platform versions 2023.2, 2025.1, 2025.2, and 2026.03 — deprecation dates, serverless support, and the right migration path.',
    url: '/docs/answers/which-hubspot-platform-version',
  },
};

<GuideArticleSchema
  url="/docs/answers/which-hubspot-platform-version"
  title="Which HubSpot platform version should I be on in 2026?"
  description="Decision matrix for HubSpot developer platform versions 2023.2, 2025.1, 2025.2, and 2026.03 — deprecation dates, serverless support, and the right migration path."
  datePublished="2026-05-19"
  keywords={[
    'HubSpot platform version',
    'HubSpot 2026.03',
    'HubSpot 2025.2',
    'HubSpot 2025.1',
    'HubSpot 2023.2 sunset',
    'platformVersion hsproject.json',
    'HubSpot serverless functions',
    'HubSpot developer platform migration',
  ]}
  faq={{
    items: [
      {
        question: 'Which HubSpot platform version is current in 2026?',
        answer: 'Version 2026.03, released March 30, 2026, is the current version of the HubSpot developer platform. It reintroduces serverless function support, which 2025.2 dropped, and is the recommended target for every new project and every migration.',
      },
      {
        question: 'When does HubSpot platform 2025.1 get deprecated?',
        answer: 'Platform version 2025.1 is scheduled for deprecation on August 1, 2026. After that date HubSpot will no longer accept uploads for 2025.1 projects, so you need to migrate to 2026.03 before then.',
      },
      {
        question: 'Was HubSpot platform 2023.2 sunset?',
        answer: 'Yes. Platform 2023.2 was sunset on October 1, 2025 and 2023.1 was sunset on March 31, 2024. Any upload attempt at those versions now fails. Both can still be migrated forward to 2026.03 via hs project migrate.',
      },
      {
        question: 'Do HubSpot serverless functions work on platform 2025.2?',
        answer: 'No. Project-built apps on 2025.2 do not support serverless functions. You either stay on 2025.1 (deprecated Aug 1, 2026), port the function out to Workers or Lambda, or migrate to 2026.03 where serverless functions return with a new *-hsmeta.json configuration shape.',
      },
      {
        question: 'How long is HubSpot platform 2025.2 supported?',
        answer: 'Apps on platform version 2025.2 are supported through March 2027. You can stay on 2025.2 until then, but migrating to 2026.03 is the recommended path because it unlocks serverless functions and aligns with the every-six-months release cadence.',
      },
    ],
  }}
  breadcrumb={[
    { name: 'Home', url: '/' },
    { name: 'Docs', url: '/docs' },
    { name: 'Answers', url: '/docs/answers' },
    { name: 'Which HubSpot platform version should I be on in 2026?', url: '/docs/answers/which-hubspot-platform-version' },
  ]}
/>

<CopyAsMarkdown src="/docs/answers/which-hubspot-platform-version.md" />

<GuideHero
  eyebrow="Reference · Platform"
  title="Which HubSpot platform version should I be on in 2026?"
  tagline="If you're starting fresh, use 2026.03. If you're on 2025.1 you have until August 1, 2026 to migrate. If you're on 2025.2 without serverless functions you can stay through March 2027 — with serverless, migrate to 2026.03 now. 2023.x is already sunset; upload attempts fail."
  duration="≈ 8 min read"
  outcome="A clear answer to which platformVersion to put in your hsproject.json today, and what date forces you to move off it."
/>

<GuideSection eyebrow="TL;DR" title="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.

<GuideOut label="If you only read one thing">
**Use `2026.03` for new projects. Migrate off `2025.1` before August 1, 2026.** `2025.2` is fine through March 2027 unless you need serverless functions, in which case move to `2026.03` now.
</GuideOut>

</GuideSection>

<GuideSection eyebrow="01 · Matrix" title="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.

| Version | Status (May 2026) | Released | Node.js min | Serverless functions | Hard deadline to move off |
| --- | --- | --- | --- | --- | --- |
| **`2026.03`** | Current | Mar 30, 2026 | v22 | **Yes** — new `*-hsmeta.json` shape | None yet (next release ~Sept 2026) |
| **`2025.2`** | Supported | Sept 2, 2025 | v22 | **No** — not supported on this version | March 2027 |
| **`2025.1`** | Upcoming deprecation | Apr 1, 2025 | v20 | Yes (legacy shape) | **August 1, 2026** |
| **`2023.2`** | Sunset | — | v18 | Yes (legacy shape) | Already sunset — Oct 1, 2025 |
| **`2023.1`** | Sunset | — | v18 | Yes (legacy shape) | Already sunset — Mar 31, 2024 |

**Source of truth:** HubSpot's [Developer platform and API versioning](https://developers.hubspot.com/docs/developer-tooling/platform/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).

</GuideSection>

<GuideSection eyebrow="02 · Calendar" title="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.

| Date | Event | Action required |
| --- | --- | --- |
| Mar 31, 2024 | `2023.1` sunset | Migrate to `2026.03` if you haven't already (uploads currently fail) |
| Oct 1, 2025 | `2023.2` sunset | Migrate to `2026.03` (uploads currently fail) |
| Oct 1, 2025 | Node.js v18 dropped from serverless functions and CLI | Move serverless functions to v20+ |
| Mar 30, 2026 | `2026.03` GA | New projects default to `2026.03`; serverless functions return |
| **Aug 1, 2026** | **`2025.1` deprecated** | **Migrate to `2026.03` before this date** |
| ~Sept 2026 | Next platform version GA | `2025.2` enters its last 6 months of *Supported* |
| Mar 2027 | `2025.2` reaches end of *Supported* window | Migrate `2025.2` apps to current |

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.

</GuideSection>

<GuideSection eyebrow="03 · New projects" title="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`.

```json hsproject.json
{
  "name": "my_project",
  "srcDir": "src",
  "platformVersion": "2026.03"
}
```

</GuideSection>

<GuideSection eyebrow="04 · 2023.2 path" title="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.

</GuideSection>

<GuideSection eyebrow="05 · 2025.1 path" title="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.

</GuideSection>

<GuideSection eyebrow="06 · 2025.2 path" title="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.

```diff hsproject.json
 {
   "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.

</GuideSection>

<GuideSection eyebrow="07 · Background" title="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.

</GuideSection>

<GuideSection eyebrow="08 · Check yours" title="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.

```json hsproject.json
{
  "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.

</GuideSection>

<GuideSection eyebrow="Related" title="Related questions">

- [Legacy CRM cards → UI Extensions migration playbook](/docs/answers/legacy-crm-cards-to-ui-extensions) — covers the October 31, 2026 deadline that runs in parallel with the platform-version deadlines above.
- [Where did serverless functions go in 2025.2?](/docs/answers/hubspot-serverless-functions-2025-2) — the escape-hatch guide for teams who got caught mid-migration.
- [Surviving `hs project migrate` failures](/docs/answers/hs-project-migrate-troubleshooting) — error-by-error decision tree for the migration command this guide tells you to run.
- [Legacy public app → projects: the full rebuild guide](/docs/answers/legacy-public-app-to-projects) — for apps that pre-date the projects framework entirely.
- [Private app vs public app vs OAuth — decision tree](/docs/answers/hubspot-private-vs-public-vs-oauth) — 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](https://developers.hubspot.com/docs/developer-tooling/platform/versioning) and [Determine your migration path to 2026.03](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/overview) pages. Refreshed whenever HubSpot ships a new platform version (every six months, March and September).*

</GuideSection>