Developer platform versioning

HubSpot developer projects include a platformVersion field that enables you to control which version of the projects platform you’re developing on. This enables you to access updated functionality and ensure any new features don’t break an app you’ve released on a previous version of the platform. Below, learn about the available versions and their associated updates to specific APIs and features.

Manage versions

To check which version of the developer platform your projects are running on, locate the platformVersion field in your project’s top-level hsproject.json file.

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

Learn how to migrate an older version of a legacy app built with projects to the latest version of the developer platform:

If you’re just getting started, check out the app creation guide.

Versions

Parameter	Description
`2025.2` Latest	Available as of Sept 2, 2025. This platform version increases the minimum required version of Node.js to v22. Changes include a new file-based build-and-deploy framework. This framework contains an app’s configuration, assets, and other source code. Learn more in the developer platform overview.
`2025.1`	Available as of April 1, 2025. This platform version increases the minimum required version of Node.js to `v20`.
`2023.2` Sunset	This version was sunset on October 1, 2025, and attempts to upload projects at this version will fail. To continue building and deploying, upgrade to platform version `2025.1` or `2025.2`. To migrate to `2025.1`, update the project’s version to `2025.1`. To migrate to `2025.2`, first update the project’s version to `2025.1`, then follow the private app or public app migration guide. Note that you’ll need to be using Node version `20` or higher for compatibility. Learn more about this version below.
`2023.1` Sunset	Initial release of the developer platform. This version is no longer be available as of March 31, 2024. Attempts to upload projects at this version will fail.

Changes in 2025.2

The latest version of the developer platform provides a number of new features, a streamlined build-and-deploy process, and other productivity tools to help you build powerful integrations with HubSpot. Learn more about how to build an app, edit your app configuration, manage your app in HubSpot, and how to install the latest version of the HubSpot CLI. More details are available in the developer platform overview

Please note: if you opt to migrate a legacy private app or public app to version 2025.2, you won’t be able to downgrade back to a previous version after the migration process is complete.

Changes in 2025.1

Version 2025.1 increases the minimum version of Node.js to v20 for serverless functions, app functions, and endpoint functions.

Changes in 2023.2 (sunset)

This version was sunset on October 1, 2025. If you have a project that’s still on 2023.2, you can continue building it by migrating to either 2025.1 or 2025.2.

To migrate to 2025.1, update the project’s version to 2025.1.
To migrate to 2025.2, first update the project’s version to 2025.1, then follow the private app or public app migration guide.

For posterity, below are the changes included for version 2023.2.

Show serverless function updates

The following changes have been made for serverless function configuration (serverless.json):

Previously, serverless functions in projects supported two types of functions: app and API endpoint. App functions have been updated to support public URLs for making API requests, so you no longer need to build these as separate types.
With this update, the runtime and version fields have also been removed.
This version uses Node18, and lower versions cannot be specified.

Previous serverless function configuration

{
  "runtime": "nodejs18.x",
  "version": "1.0",
  "appFunctions": {
    "functionName": {
       "file": "function1.js"
    }
  },
"endpoints": {
  "path/to/endpoint": {
  "file": "githubUserFunction.js",
  "method": ["GET", "POST"]
  }
 }
}

Updated serverless function configuration

{
  "appFunctions": {
    "functionName": {
       "file": "function1.js",
       "endpoint": {
          "path": "path/to/endpoint",
          "method": ["GET"],
        }
     }
  }
}

Show async support changes

2023.2 projects now support asynchronous functions. Callbacks are no longer supported in this version.To update your serverless functions to use async:

Add async to the function definition.
Remove the callback (sometimes referred to as sendResponse), and use return statements to return response.
Use await and try/catch instead of promise chaining.
Return the desired response or throw an error.

Before:

const hubspot = require('@hubspot/api-client');

exports.main = myFunction = (context = {}, sendResponse) => {
  const { hs_object_id } = context.propertiesToSend;
  const userId = context.parameters.userId;

  const hubspotClient = new hubspot.Client({
    accessToken: process.env['PRIVATE_APP_ACCESS_TOKEN'],
  });

  const properties = {
    name: 'newName',
  };
  const SimplePublicObjectInput = { properties };
  const objectType = 'myObject';
  const objectId = hs_object_id;
  const idProperty = undefined;

  hubspotClient.crm.objects.basicApi
    .update(objectType, objectId, SimplePublicObjectInput, idProperty)
    .then((res) => {
      sendResponse(res);
    })
    .catch((err) => {
      console.error(err);
      sendResponse(err);
    });
};

After:

const hubspot = require('@hubspot/api-client');

exports.main = async (context = {}) => {
  const { hs_object_id } = context.propertiesToSend;
  const userId = context.parameters.userId;

  const hubspotClient = new hubspot.Client({
    accessToken: process.env['PRIVATE_APP_ACCESS_TOKEN'],
  });

  const properties = {
    name: 'newName',
  };
  const SimplePublicObjectInput = { properties };
  const objectType = 'myObject';
  const objectId = hs_object_id;
  const idProperty = undefined;

  try {
    const res = await hubspotClient.crm.objects.basicApi.update(
      objectType,
      objectId,
      SimplePublicObjectInput,
      idProperty
    );
    return res;
  } catch (err) {
    console.error(err);
    return err;
  }
};

Show access token authentication changes

Whereas previously you would refer to private app access tokens with context.secrets.PRIVATE_APP_ACCESS_TOKEN, you’ll now use process.env rather than context.secrets. For example:

// Include HubSpot node API client
const hubspot = require('@hubspot/api-client');

exports.main = async (context = {}) => {
  // instantiate HubSpot node API client
  const hubspotClient = new hubspot.Client({
    accessToken: process.env['PRIVATE_APP_ACCESS_TOKEN'],
  });

  //your function

  return response;
};

Show logging changes

Version 2023.2 increases log size from 4KB to 256KB and guarantees logs to be in order of execution. You can also take advantage of improved in-app logging, such as log tracing.

​Manage versions

​Versions

​Changes in 2025.2

​Changes in 2025.1

​Changes in 2023.2 (sunset)

Manage versions

Versions

Changes in 2025.2

Changes in 2025.1

Changes in 2023.2 (sunset)