How to Build a HubSpot App Your Customers Can Install

To build a HubSpot app, create a project with the HubSpot CLI on HubSpot's developer platform and set it to Marketplace distribution with OAuth. Then run your own backend that stores each customer's tokens and receives their webhooks. The code is the predictable part. What usually sets the launch date is HubSpot's rule that a listed app needs three active installs from customer accounts unaffiliated with your company, so the first customers have to be lined up while the app is still being built.

That makes a HubSpot app a product decision as much as an engineering one. You are shipping a customer-facing integration that each customer installs into their own HubSpot account, and someone has to own it after launch. Appnigma's marketplace apps service is built for this case. It delivers "a native app, marketplace listing preparation, and review support" for HubSpot and Salesforce. If you only need a key for internal scripts in your own account, HubSpot now points you to Service Keys instead, and the rest of this page won't apply.

Updated October 2026. Checked against HubSpot's developer platform documentation, the Marketplace listing and certification requirements, and the May 2026 developer changelog. This update replaces the older CLI commands and Developer Account steps, corrects which installs count toward listing, separates listing from certification, and removes cost estimates and an example that were not based on HubSpot sources.

Should a new app use a legacy app or the developer platform?

HubSpot now has two ways to build an app, and for a new Marketplace app only one of them still works. The developer platform overview describes apps "built and managed via projects," with a file-based build-and-deploy framework. Legacy private and public apps still run today, but they are on a clock. HubSpot's September 2026 changelog announced "the end of support for v1-v3 APIs, legacy public apps, and legacy private apps, all with a September 2027 enforcement date."

The difference shows up at listing. HubSpot's May 2026 changelog says that starting November 2, 2026, apps "using legacy apps or Projects 2023.2 / 2025.1 will be rejected for new listings." A team that starts today on the legacy public app route would build something it can't list.

For a team that already has a legacy public app, two dates matter. The same changelog says that to "remain listed in the Marketplace and retain certification," the app must move to the projects model by September 2027. A certification review can arrive sooner, and the May changelog gives apps in certification or recertification "~60 days to migrate to a supported version." API paths are changing on the same timeline. Numbered versions are being replaced by date-based paths such as /2026-03/, and HubSpot advises migrating straight to those rather than stopping at v3 or v4. Migration is also one-way. The versioning page warns that after migrating a legacy app to version 2026.03, "you won't be able to downgrade back to a previous version." So migrate on your own schedule, after the app's integration tests run against a test account, rather than inside a review window.

Setting up the project with the HubSpot CLI

Apps are built from a standard HubSpot account's Development area, because HubSpot's account types page says "all legacy developer accounts were migrated to standard HubSpot accounts" on March 9, 2026. Older guides that start with a separate developer account and hs init describe the legacy route. The app creation guide uses hs account auth, then hs project create, then hs project upload, with CLI version 7.6.0 or later.

The decisions that matter end up in one file. hs project create writes app-hsmeta.json, which holds what older apps configured in a settings screen, including redirect URLs, scopes and the URLs your app cards may call. This trimmed example follows HubSpot's own boilerplate.

{
  "uid": "acme_hubspot_app",
  "type": "app",
  "config": {
    "name": "Acme for HubSpot",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": ["https://app.acme.com/hubspot/oauth-callback"],
      "requiredScopes": ["crm.objects.contacts.read", "crm.objects.contacts.write"],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    }
  }
}

Two settings deserve care before the first upload. The uid identifies the app across builds, and the guide warns that changing it later makes the platform treat it as a different app. The scope lists are the other one. The listing requirements say to "only request scopes your app needs," and HubSpot's scopes reference lets you mark scopes as optional or conditionally required. Optional scopes behave differently from what many teams assume. The OAuth guide says they are "automatically dropped" when the customer's account lacks that tool, so a Starter customer can install successfully without the scope your Enterprise feature needs. Your backend has to read which scopes each token actually received and switch that feature off per customer. The project's hsproject.json sets platformVersion, and 2026.09 is the current version.

For testing, you can create up to 10 developer test accounts, each with "a 90-day trial of many enterprise features." Configurable test accounts let you choose the Hub tiers, which matters because a customer on Starter can't use features that need a Professional or Enterprise subscription. Run hs project dev once the app is installed in a test account to preview changes locally.

The backend that holds tokens and receives webhooks

HubSpot hosts your project's configuration and UI, but customer data still flows through a service you run. That service has three jobs, and all three are per customer account.

OAuth tokens. When a customer approves the install, your redirect URL receives a code that you exchange for an access token and a refresh token. HubSpot's OAuth token guide says access tokens are "short-lived (30 minutes)," so the service refreshes them per account, ideally before they expire. The May 2026 changelog also requires new listings to use the current OAuth endpoints, such as POST /oauth/2026-03/token, because the v1 endpoints are being deprecated. One property of these tokens shapes your product design. HubSpot's OAuth guide says access tokens "do not reflect the permissions or limitations" of the user who installed the app. A token with the contacts read scope can see every contact in the account, even if the installing user only sees their own. If your product shows HubSpot data to its own users, apply your own permission rules, or use the user-level access that platform version 2026.09 added.

Webhooks. Subscriptions live in a webhooks folder inside the project, configured in a *-hsmeta.json file per the webhook configuration guide. Each request is signed. Validate the X-HubSpot-Signature-v3 header with your client secret and reject any request whose timestamp is "older than 5 minutes," per HubSpot's request validation docs.

Uninstalls. When a customer disconnects your app from your own product, the certification requirements expect you to call the Uninstall App API endpoint. That endpoint fully removes the app and its webhooks from the customer's account. Your service should then delete that account's tokens. Uninstalls that start on the HubSpot side show up differently. HubSpot's certification feedback examples say that if you see 401 errors for 100% of requests and can't refresh the token, consider the app uninstalled and stop making requests. Build that rule into the token service early, because an app that keeps calling a disconnected account adds failed requests to the success rate HubSpot reviews.

What one customer's sync costs against the rate limit

Every installing account gets its own budget. HubSpot's usage guidelines limit a Marketplace OAuth app to "110 requests every 10 seconds" per installed account. The API limit increase add-on doesn't raise it. The arithmetic below uses only those documented limits, so treat it as a planning example rather than a benchmark.

Take a customer with 50,000 contacts on the day they install. The contacts API returns up to 100 contacts per request and limits batch operations "to 100 records at a time." Reading the whole set in pages of 100 takes 500 requests, which is about 46 seconds of that account's budget at the full rate. Fetching the same contacts one at a time takes 50,000 requests, or roughly 76 minutes at the full rate. During that time every other call your app makes for that customer competes for the same budget.

Two other limits change the design. The CRM search API is limited to "five requests per second per account" and returns at most 10,000 results per query. So search works for finding changed records, but it can't serve as the backfill for a 50,000-contact account. Webhooks have their own clock. HubSpot sends up to 100 events per request with up to 10 requests in flight per account, and the webhooks guide treats any response slower than five seconds as a failure, retried up to 10 times. If your handler spends 100 milliseconds on each event, a full request of 100 events takes 10 seconds and times out every time. Store the events, return a 2xx response, and process them afterwards.

This is also what certification measures later. An app needs an API success rate above 95 percent, and HubSpot's own feedback example describes an app at 83 percent, mostly from 429 rate limit errors.

App cards, settings pages and workflow actions

Features inside HubSpot are project components you add with hs project add. Besides webhooks, the app creation guide offers app cards on CRM records, a settings page, custom workflow actions and app functions. App functions are serverless support, which version 2026.03 "re-introduced." HubSpot's serverless functions page says installing an app that uses them requires an Enterprise subscription, so a Marketplace app aimed at every tier keeps those endpoints on its own backend.

For most SaaS products, an app card on the record your product cares about earns its build time, and the reason goes beyond the user interface. The card is a React component that gets its data with hubspot.fetch() from your backend, and HubSpot's data fetching guide requires every backend URL to be listed in permittedUrls or the request fails with a 403. Each of those requests is signed by HubSpot, and the listing requirements count "app card data fetch requests" as app activity. So a customer who opens records with your card keeps their install active even in a month when your sync has nothing new to write, which protects both the three-install rule and the 60-install certification bar.

Classic CRM cards are no longer an option. The listing requirements say they are "no longer supported as of June 16, 2025," and listed apps that still use them must migrate by October 31, 2026. App cards come with their own listing rules too. The card name can't use HubSpot's brand names, and the app must not request sensitive data scopes.

How long does it take to build and list a HubSpot app?

The engineering time depends on your scope, but HubSpot publishes the clock for everything after it. Listing needs at least three active installs from production accounts "unaffiliated with your organization" that show app activity "within the past 30 days," per the listing requirements. Your sandbox, your own portal and your test accounts don't count.

Read as a plan, the table says the earliest launch date is set by the third customer, not the last commit. The 30-day window is about recent use, not age. An install made last week counts if it is making successful calls, while a pilot customer who connected three months ago and stopped using the integration no longer counts. Give the first customers a workflow they run every week, and check activity per account before you submit, because HubSpot can remove a listed app that falls below three active installs. Certification is a separate milestone at least six months after launch, so it shouldn't appear on a launch plan. HubSpot doesn't charge for any of it. Its certification FAQ says "we do not charge you a fee to list or certify your apps," and adds that "there is no revenue sharing."

Since March 31, 2026, listing submissions no longer need testing credentials, according to the changelog. HubSpot asks for demo videos or guided walkthroughs of your core user flows instead, so record them while the first customers set up.

Mistakes that delay a HubSpot Marketplace launch

These come straight from HubSpot's requirements and feedback examples.

• Starting on the legacy public app route after November 2, 2026, when legacy apps are rejected for new listings.
• Counting your own sandbox, test accounts or an agency's portal toward the three installs.
• Requesting scopes for features you haven't built yet. Every scope must be used, and the listing's Shared data table must reflect them.
• Writing the listing like a product homepage. HubSpot wants content "specific to the integration as opposed to general product information."
• Blocking HubSpot's crawler. Listing URLs are checked with HubSpot's SEO tools, and HubSpot recommends allowlisting the HubSpot Crawler user agent.
• Calling the API with expired tokens. Refreshing only after a 401 lowers the success rate certification reviews later.

For the full review process, see our guides to listing requirements and partner status and HubSpot app certification requirements.

Frequently Asked Questions

Can I still create a legacy private app in HubSpot?

Not for long. HubSpot disables legacy private app creation on October 26, 2026 for existing accounts and recommends Service Keys for in-account integrations, while Marketplace apps need a developer platform project with OAuth.

Do I still need a HubSpot developer account?

No. Legacy developer accounts became standard accounts on March 9, 2026, and you create apps and up to 10 developer test accounts from the Development menu.

Do test accounts count toward the three installs needed to list?

No. HubSpot counts only unaffiliated production accounts with successful app activity in the past 30 days, so plan three real customer pilots alongside the build.

What API rate limit does a HubSpot Marketplace app get?

110 requests every 10 seconds for each installed account, with the CRM search API limited separately to five requests per second. Batch endpoints of 100 records keep a large first sync inside that budget.

Can Appnigma build our HubSpot app?

Yes. Appnigma's marketplace apps service delivers a native HubSpot app with listing preparation and review support, including HubSpot listing review and certification support where eligible. HubSpot controls approval timing, and ongoing maintenance of a standalone app runs on a separate maintenance retainer.

About the author

Sunny Chauhan is the co-founder and CEO of Appnigma AI, which builds and maintains customer integrations and native Salesforce and HubSpot apps for B2B SaaS teams. Before Appnigma, he was on Salesforce's AppExchange team, where he worked with more than 300 SaaS partners. He has spent close to a decade on the Salesforce platform, including work at Zennify, and holds Salesforce certifications including Platform Developer II, Platform App Builder, Administrator, Data Cloud Consultant, and AI Associate.

Related Articles

• How to become a HubSpot App Partner
• HubSpot app certification requirements
• HubSpot OAuth scopes guide
• HubSpot webhooks implementation guide
• HubSpot app cards and UI extensions

Sources

1. Developer platform overview and Create a new app using the CLI, HubSpot Developers
2. Developer platform and API versioning, HubSpot Developers
3. Legacy APIs and legacy apps, what's going unsupported and when and Legacy private app creation sunset, HubSpot Developer Changelog
4. App listing and app certification requirement updates for May 2026, HubSpot Developer Changelog
5. HubSpot account types, HubSpot Developers
6. Manage OAuth tokens and Validate requests, HubSpot Developers
7. API usage guidelines and limits, HubSpot Developers
8. Contacts API, CRM search and Webhooks API, HubSpot Developers
9. App listing requirements and Certification requirements, HubSpot Developers