HubSpot Developer Platform 2026.03 Upgrade

Look for `hsproject.json` and its `platformVersion` property before discussing a `2026.03` upgrade. The migration overview explains how existing platform versions relate to `2026.03`, including cases where no migration is necessary and cases where older versions need more careful review.

A platform-version upgrade is not the same as the May/June 2026 legacy public app creation sunset. The creation sunset affects new legacy public app creation. The `2026.03` workstream affects project structure, platform version, and supported feature migration paths.

If the project is already on `2026.03`, record that and check whether there is any separate Marketplace, CI, or CRM card work. If it is on an older version, open the latest-platform migration docs before changing files or running commands.

Create a small inventory: current platform version, app type, serverless functions, app cards, static auth or OAuth, Marketplace status, and CI upload flow. This keeps version work tied to actual app features.

Use the documented route, not a generic upgrade command. For 2025.2, update the top-level `hsproject.json` value to 2026.03 and run `hs project upload`. For 2023.1, 2023.2, 2025.1, or a project that predates versioning, run `hs project migrate` from that project's working directory and review every feature confirmation prompt.

Do not apply public app assumptions to private app cases. The latest-platform docs include a private-app limitation for legacy non-project-based private apps, so those cases should be flagged for manual review.

Confirm the current CLI before starting; the current 2026.03 page recommends 8.4.0 or above, while the installation page identifies the latest recommended release. Commit or otherwise preserve the pre-upgrade source state. On the 2025.2 edit-and-upload route, run `hs project validate` after changing `platformVersion` and before upload. On 2023.1, 2023.2, 2025.1, or pre-version routes, run `hs project migrate` first, then validate the generated 2026.03 project before any follow-up upload; do not make a legacy project's pre-migration validate result a gate.

If the older project used serverless functions with `environment` values in `serverless.json`, inventory each name before migration and recreate those values through the documented `hs secret add` flow. Do not copy secret values into source control, the handoff, CI logs, or an agent prompt.

Completion means the project reports 2026.03, the new build succeeds, the intended deployment state is confirmed, and auth, installs, app cards, functions, webhooks, and other affected features pass a written test plan. Use `hs project open` for Builds & Deploys. If validation or build fails, stop deployment, repair the reported source/configuration issue, and create a new build rather than forcing a warning bypass.

A useful handoff states the current version, the target version to verify, the command or file change to review, and the official docs used. It also lists features that could change migration complexity, such as serverless functions or app cards.

Keep the recommendation reversible until a developer has run the current preflight. The language should be 'likely path to verify,' not 'guaranteed upgrade path.'

Add a source-check date. This repository's official source archive was captured on 2026-05-24, and production decisions should re-open current HubSpot docs.