HubSpot Developer Blog

A Developer’s Guide to HubSpot’s Date-Based API Versioning

If you’ve built against HubSpot’s public APIs, you’ve probably run into some versioning friction: v3 vs v4, legacy vs “next-gen” APIs, and the occasional breaking change that shows up where you didn’t expect it.

We’re changing that.

HubSpot is standardizing on date-based versioning (DBV) for public APIs. Therefore, instead of v1, v2, v3, or v4, you’ll see versions tied to release dates - paths like /2026-03/, and /2026-09/.

This guide explains what date-based versioning means in practice, how it affects integrations and beta APIs, and how to adopt DBV with minimal friction.

Table of Contents

Why HubSpot’s API versioning needed to change

Historically, HubSpot’s public APIs evolved along two parallel tracks.

On one side were legacy endpoints that pre-dated current API design guidelines. On the other hand, newer APIs were built with a more modern approach. Both used numeric versions (aka semantic versions) like v1, v3, and v4, but without a single, consistent policy governing how those versions changed over time. In practice, this made it hard to answer basic questions:

  • “Which version should I build on?”
  • “Is v3 always the latest?”
  • “Why is v1 no longer maintained?”

Because of breaking changes, the answers were not always clear. This made integrations harder to manage, especially if you’re supporting multiple customers, environments, or long-lived apps. The result was friction for anyone running HubSpot integrations in production. Without hard boundaries between versions, it’s harder to predict behavior, plan upgrades, or confidently ship changes.

Date-based versioning is designed to reset that experience. By associating versions with specific release windows, DBV creates clear boundaries, predictable support timelines, and a single versioning model that appears consistently across docs, SDKs, Postman, and the HubSpot Developer Platform.

What is date-based versioning?

Date-based versioning replaces semantic API versions (v1, v2, v3, v4) with versions based on release dates.

Instead of:

/v1/contacts /v3/contacts

You’ll see:

/2026-03/contacts /2026-09/contacts

For HubSpot’s CRM APIs, that looks like:

Old versioning

/crm/v3/objects/contacts

New versioning

/crm/objects/2026-03/contacts /crm/objects/2026-09/contacts

A few key properties to internalize:

  • Stable: Once a date-based version is General Availability (GA) (e.g., /2026-03/), its behavior is locked. HubSpot may ship critical security or bug fixes, but breaking changes only ship in a new version.
  • Explicit: The version is part of the URL path - no hidden headers, flags, or account-level switches.
  • Predictable: Versions align with HubSpot’s March and September release cadence, making it easier to align with your own roadmap.

 

Why HubSpot is adopting date-based versioning

There are three primary drivers behind this change.

1. Reduce confusion

Maintaining legacy and modern APIs with different versioning expectations made it difficult to answer simple questions about “the right version” to use. DBV unifies all public API surfaces under a single, date-based timeline.

2. Make changes predictable

Instead of rolling breaking changes into existing versions, DBV allows HubSpot to:

  • Ship breaking changes only in new versions.
  • Communicate clear support timelines.
  • Provide developers time to test and update their source code on their own schedule.
3. Align APIs with the HubSpot Developer Platform and tooling

HubSpot’s Developer Platform is also moving to date-based versions (for example, Projects on 2025.2 and 2026.03). Aligning public APIs to the same model improves clarity and consistency for developers building on HubSpot, without introducing functional dependencies between the platform and API versions.

This alignment means:

  • Developer documentation, Postman collections, and SDKs all speak the same version language.
  • It’s easier to identify which API behavior matches which platform version.
  • AI agents and MCP-based integrations can rely on a consistent, machine-friendly versioning model.

How date-based versioning works at HubSpot

Date-based versioning introduces a predictable lifecycle for every public API version. Instead of versions drifting over time, each release has a clear date, support window, and end-of-life path that you can plan around.

 

 

Release cadence

HubSpot releases new General Availability (GA) public API versions twice a year, on a fixed schedule that aligns with broader platform releases. These releases happen in March and September, and each version is named for its release window - for example, /2026-03/ or /2026-09/. You can think of each release as a snapshot of the public API surface at that point in time.

For developers, this means version numbers are no longer abstract counters. The version itself tells you when it was released, how long it will be supported, and where it sits relative to other platform changes.

Support window

Every GA date-based version is guaranteed to be supported for 18 months, with a defined lifecycle. For the first six months, the version is in active maintenance. During this period, HubSpot may ship bug fixes and small, non-breaking improvements, but the API's core behavior remains stable.

After that, the version enters a 12-month phase of critical fixes only. At this point, changes are limited to high-severity issues such as security vulnerabilities, data integrity problems, or major stability concerns. No new features or behavioral changes are introduced. Once the full 18-month support window ends, the version is moved to an unsupported state. At that point, it is no longer guaranteed to remain stable, receive fixes, or continue functioning as expected. We recommend upgrading to a supported version before the 18-month period ends.

The key takeaway: you always know how long a version will be supported, and you never have to guess whether new behavior might be introduced late in its lifecycle.

Unsupported versions

With date-based versioning, support happens at the version level, not as scattered, endpoint-by-endpoint changes. When HubSpot no longer supports a date-based version, such as /2026-03/, that support applies to the entire version family. You don’t need to track individual endpoints or wonder whether only part of the surface is affected.

Each GA version is guaranteed to be supported for 18 months. After that period, the version moves to an unsupported state, and end users are expected to upgrade to a supported date-based version. Remaining on an unsupported version is at your own risk.

HubSpot may later formally deprecate and remove unsupported versions. When we do, we will communicate through developer documentation, changelogs, and other appropriate communication channels, along with guidance on which newer version to adopt and what has changed.

Co-existence with semantic/numeric versions

Date-based versions don’t replace semantic versions overnight. During the transition period, existing semantic endpoints such as v3 and v4 will continue to function as they do today. This ensures that existing integrations don’t break simply because DBV is rolling out. At the same time, new development will increasingly target date-based versions. New features, enhancements, and future-facing API work will leverage /YYYY-MM/ path rather than on legacy semantic versions.

The practical implications are straightforward - you don’t need to migrate anything immediately (phew). For new development, date-based versions should be the default. Legacy semantic versions (for example, v4) will move to an unsupported state at HubSpot’s Spring Spotlight ‘27, but they will not be deprecated as part of this transition. Over time, as you update existing integrations on your own timeline, you’ll naturally move away from semantic versions and toward a supported date-based release to ensure continued stability and support.

 

Betas in a date-based world

Date-based versioning also standardizes how API betas work at HubSpot.

What an API beta is (and isn’t)

An API beta is:

  • A way to preview new features or breaking changes ahead of General Availability (GA).
  • A temporary surface intended for testing and feedback.

It is not:

  • A guarantee that every beta feature will ship in the next GA release.
  • A version you should pin long-term production traffic to without a migration plan.

Beta naming

Each beta corresponds to a future GA version:

  • GA: /2026-09/
  • Beta: /2026-09-beta/

Betas are typically available six months before the corresponding GA release, so /2026-09-beta/ would be available in March 2026. Think of /2026-09-beta/ as a preview of the /2026-09/ release - not a permanently supported version. The beta name indicates which GA release a feature targets, not when the beta itself becomes available.

What happens as GA approaches

As GA approaches, the next beta cycle is already open. For example, by the /2026-09/ ships, /2027-03-beta/ is available for testing. Beta features one of two paths: those ready to graduate to the GA release version, and those that need more time to roll forward into the next beta (for example, from /2026-09-beta/ to /2027-03-beta/). That means you should never assume a beta feature will automatically appear in the next GA release, or even ship GA at all. Once a GA version is live, the matching /YYYY-MM-beta/ version will be unsupported within about 8 weeks. After that window, calls to the beta version will fail, and you’ll need to either move to the GA version (for features that graduated) or update to the next /YYYY-MM-beta/ if the feature stays in beta.

 

What date-based versioning means for your integrations

If your integration is currently using semantic versions like v3 or v4, date-based versioning changes how you think about your upgrades - but not in a way that should feel disruptive.

With semantic versions, many integrations relied implicitly on HubSpot to manage changes over time. Even if you are pinned to v3, behavior could evolve as fixes, improvements, or breaking changes were introduced behind that version boundary. In practice, this meant fewer explicit upgrades, but also less certainty about when or why behavior changed.

Date-based versioning flips that model. Instead of an evolving version, each /YYYY-MM/ version represents a fixed snapshot of API behavior. Nothing changes unless you choose to move to a newer version.

Pinning to a version becomes explicit and intentional

Under DBV, the recommended pattern is to configure your integration to target a specific version in the API path, for example:

/crm/objects/2026-03/...

This approach differs significantly from simply pinning to v3. Breaking changes or substantial behavioral updates will only be introduced in a new date-based version, for example, /2026-09/. However, minor updates, such as security patches or bug fixes, will still be applied to existing versions.

For developers migrating from semantic versions, this means:

  • You no longer need to worry about unexpected behavior changes.
  • You do need to explicitly choose when to upgrade by changing the API version you call.
  • Version upgrades become a conscious, reviewable decision rather than a consistent background risk.

Most teams handle this by making the API version part of the configuration (e.g., an environment variable or a shared client setting) rather than hard-coding it throughout the codebase. This makes upgrades easier to test and, if needed, roll back.

Upgrades move from reactive to scheduled

With semantic versions, upgrades often happen reactively - triggered by a deprecation notice or an unexpected change. Date-based versioning is designed to make upgrades routine instead. Because new versions ship in March/September and are supported for 18 months, you can plan upgrades the same way you plan other dependency updates. Suggested patterns to begin scheduling upgrades:

  • Reviewing each new March release during Q3.
  • Test and adopt at least one new API version per year.

The key difference is that you’re no longer racing a surprise change. You know exactly how long your current version is supported and can slot upgrades into your existing release cycles.

Error handling and monitoring still matter - but for clearer reasons

Even though DBV reduces surprise changes, integrations should still monitor for signals that a version is approaching end of life. That means watching for support or deprecation notices in changelogs, docs, and developer communications from HubSpot, as well as paying attention to any unsupported headers returned by the API. These signals are now tied to version-level events, not subtle behavior shifts. From an operational perspective, version updates should be treated like any other upstream dependency change:

  • You should have basic alerting around error rates and failed API calls.
  • Your integration should be able to switch versions via configuration if needed.
  • Rolling back to a previously supported version should be straightforward during an incident.

The difference is that these scenarios should be rare and well-telegraphed, not unexpected.

Testing and migration look more like parallel validation

When moving from a semantic version (V1, V2, v3, v4) to a date-based version, or from one DBV release to the next, testing is less about discovering surprise behavior and more about validating known differences. A common and effective approach is to:

  • Run the existing version and the new date-based version in parallel for a subset of traffic.
  • Compare responses, performance, and downstream effects.
  • Gradually shift traffic once you’re confident in the new version’s behavior.

Beta versions can also play a role here. Using /YYYY-MM-beta/ in non-production environments lets you see upcoming changes early, so migrations to GA versions are mostly a matter of confirmation rather than discovery.

 

What date-based versioning means for your apps

Date-based versioning applies to every app you build on the HubSpot Developer Platform. What changes between apps isn’t the code you write - it’s how you distribute the app: privately to specific accounts, or broadly through the HubSpot Marketplace.

Upgrading legacy apps

Legacy private and public apps are still supported (for now), but they cannot access the newest Developer Platform capabilities. When Developer Platform version 2026.09 launches in September 2026:

will no longer be eligible for app listing, certification, or recertification.

To remain eligible for listing and certification, recertification, and access to new platform capabilities, you must migrate your app in accordance with HubSpot’s Developer Documentation.

Marketplace certification and recertification requirements

When you set your app’s distribution to “Marketplace,” it means you intend for your app to be installable across multiple customer accounts via OAuth and to be eligible for a HubSpot Marketplace listing. That raises the bar on how you manage API versions for your apps.

To qualify for certification:

  • Stable behavior for every install: Pin your production Marketplace app to a specific date-based version so existing installs don’t see unexpected changes without a planned upgrade.
  • A clear upgrade policy: Publish how often you move to a new date-based version, how long you support previous versions inside the support window, and how you’ll communicate app changes to your customers.
  • Distribution and auth are set up correctly: Marketplace apps must use OAuth and declare the correct scopes so customers understand exactly what your app can access or modify.
  • Supported date-based versioning (DBV) API versions: Your app must use API versions within the current DBV support window. Net new apps that call unsupported DBV API versions will not pass certification.
  • Signals of trust: Verifying your domain through Marketplace review removes warning banners on install screens and gives users more confidence when installing an app that controls API versions on their behalf.

To qualify for recertification:

  • Supported date-based versioning (DBV) API versions: Your app must use API versions within the current DBV support window. Apps that call unsupported DBV API versions will not pass recertification.
  • No unresolved support escalations: Your app must not have any open escalations with customers at the time of recertification submission.
  • Continued compliance: Your app must remain in compliance with all applicable HubSpot terms and API usage guidelines.

Note: Additional technical requirements unrelated to DBV will be introduced, including those related to adopting the Uninstall API and migrating from legacy CRM cards to App Cards. Full details and enforcement timelines will be communicated in advance in the HubSpot Developer Changelog.

Date-based versioning best practices (applied to all apps)
These recommendations help you manage API upgrades safely and predictably with your app:

  • Make API versions explicit: Avoid relying on “latest” behavior. Instead, ping requests to a specific date-based version (for example, /2026-03/). This freezes API behavior until you intentionally upgrade.
  • Migrate incrementally: You can run both semantic and date-based versions. Keep stable paths on v3/v4 while building or refactoring new functionality on a date-based version. Upgrades only occur when you choose to change the version.
  • Control when changes land: Each date-based version has a defined support window (for example, 18 months). This allows you to plan migrations in advance rather than reacting to unexpected changes.

 

Where you’ll see date-based versioning as a developer

HubSpot’s API Developer Documentation

  • Latest GA date-based versions are shown by default.
  • Version picker for /YYYY-MM/ versions or legacy version.
    • All semantic versions will be labeled “Legacy” and grouped separately from date-based versions.

developer docs UI with date-based versioning

HubSpot’s Developer Platform & Projects

Projects are also versioned by release date in configuration files such as hsproject.json (e.g., project version 2026.03). Together, platform and API versions tell a consistent story: “This app runs on platform version 2026.03 and targets public API version 2026-03.”

SDKs, client libraries, and samples

  • SDKs will increasingly expose methods that map directly to /YYY-MM/ API endpoints.
    • Note: DBV does not change authentication, scopes, or how you initialize SDK clients. The main change is which endpoint paths are being called.
  • Code samples will gradually default to date-based versions.
  • HubSpot’s public Postman workspace will remain grouped by product at the top level; within each product, requested resources are grouped, and within each resource, all versions live side by side so consumers can compare and choose versions without navigating to separate areas within the Postman workspace.

Rule: Product → Resource → Versions (v1/v3/date-based together)

CRM API Collections (top-level, by product) └─ Contacts API (resource) ├─ v1 ├─ v3 └─ 2026-03

Please note: Updated date-based versioned Postman collections will be available in early Q2 2026.

Developer Changelog and release communications

You can expect DBV updates to show up in:

Every March and September, HubSpot will publish a single bundled developer announcement that includes platform version releases, API version releases, support changes, and advanced support or deprecation notices. Ensuring changes are communicated clearly, consistently, and with sufficient lead time.

 

Developer benefits

Date-based versioning isn’t just a new naming scheme. It changes how you manage upgrades, stability, and long-term maintenance of your HubSpot integrations, making production systems easier to understand and maintain.

Stability you can count on

With date-based versions, behavior is locked per release. Once a version like /2026-03/ is GA, it won’t change - aside from critical security or stability fixes. This means:

  • No unexpected breaking changes.
  • No subtle behavior shifts over time.
  • Clear guarantees about the API behavior your integration depends on.

If behavior changes, it happens in a new version. You choose when to adopt it.

Upgrades on your schedule

Instead of opaque version numbers like v3 or v4, date-based versions tell you exactly when changes are introduced. Combined with a predictable March/September release cadence and an 18-month support window, upgrades become something you can plan for.

You’re no longer reacting to version drift, and instead, you’re making intentional decisions about when to move forward.

Clear lifecycle and support expectations

Each date-based version has a transparent lifecycle:

  • 18 months of support.
  • Advanced support notice.
  • A defined removal timeline.

You always know what’s supported, what’s aging, and how much time you have to migrate. That clarity reduces production risk and removes guesswork from long-term maintenance planning.

Breaking changes are explicit 

Breaking changes are introduced only in new versions - not gradually inside an existing one. If a future version introduces a breaking change, you can stay on your current supported version while you evaluate and test.

That flexibility dramatically lowers the risk of production issues.

Innovation without disruption

HubSpot can continue improving APIs, adding features, and evolving behavior - while your integration remains stable on a known version. When you want new capabilities, you upgrade. Until then, nothing changes.

Tooling and docs stay aligned

The Developer Platform, documentation, SDKs, Postman collections, and samples are increasingly centered around date-based versions. Over time, semantic versions will receive fewer active enablements. That means clearer examples, better migration guidance, and less ambiguity about which version to build against.

A familiar, modern pattern

Date-based versioning is widely used by modern API platforms like Stripe and Amazon Web Services (AWS). If you’ve built against those ecosystems, this model will likely feel intuitive.

Why upgrade sooner rather than later?

If you’re currently on the latest semantic version of any API (like v3 or v4), the initial move to date-based versioning is intended to be low-friction. Early DBV releases align closely with current functionality, so migration is primarily about updating the version path - not rewriting business logic. Upgrading earlier has practical advantages:

  • You can future-proof your integration while changes are minimal.
  • You avoid rushed migrations later when older versions approach the end of support.
  • You ensure access to new features and improvements, which will increasingly land only on date-based versions.

The sooner you adopt DBV, the more control you have over timing, testing, and risk.

 

FAQ

Do I need to migrate immediately?

No. Semantic versions will continue to work during the rollout, and DBV versions have documented support timelines. For new work, DBV is the recommended default.

Can I stay on v3 forever?

No. Semantic versions are now referred to as “legacy”. They won’t disappear overnight, but future development will land on date-based versions.

What happens when a version is unsupported?

You’ll receive advance notice, a clear removal date, and guidance on which version to move to. After removal, calls may fail or behave differently.

What about existing betas?

When a General Availability (GA) version ships, the corresponding beta is unsupported within 8 weeks. Plan to migrate promptly once GA is available.

Where can I get help?

Date-based versioning is a significant shift, but the goal is simple: make it easier and safer to build long-lived, production-grade integrations on HubSpot without having to guess what might change next.