[object Object]

Most HubSpot apps that get built never ship to the marketplace because the team underestimates the gap between “works in our portal” and “works for any customer’s portal at any tier.” The marketplace is a real distribution channel, but it rewards apps that take install variability seriously and punishes apps that ship with hardcoded assumptions.

Developer account first, customer portal never

Sign up for a free developer account at developers.hubspot.com. This is the workspace where your app lives, separate from any customer portal. Within the developer account, create test portals for each tier (Free, Starter, Pro, Enterprise) so you exercise paywall edges before users find them.

Developer account
  ├─ App: Acme Sync
  ├─ Test portal: Free tier
  ├─ Test portal: Pro tier
  └─ Test portal: Enterprise tier

Three app types, three different commitments

  • Private apps: live in one portal, use a static access token, never appear in the marketplace. Right for internal tools and one-customer integrations.
  • Public apps: installable by any HubSpot customer with OAuth. Suitable for paid SaaS and free utilities.
  • Certified apps: public apps that passed HubSpot’s review and earn the certified badge, priority placement, and joint marketing.

Certification is worth the work for category-leading apps; mid-pack utilities can stay public uncertified without blocking installs.

Listing requirements you should plan for

Beyond the basics — OAuth flow, screenshots, pricing — the bar that catches most teams:

- Documented use case with concrete buyer outcomes
- Onboarding doc covering install, configure, first value
- Working uninstall flow that revokes tokens and stops billing
- Support email staffed within 1 business day
- Privacy policy and DPA available pre-install
- Localized listing for at least one non-English market

Plan for a 2 to 6 week review window. Address feedback in batches rather than reopening tickets per change.

Pricing models the marketplace supports

Free         - no charge, no revenue share
Subscription - per seat, per portal, or per usage
Freemium     - free tier + paid upgrade
Free trial   - time-bounded full access

HubSpot takes a revenue share on paid apps. Confirm the current rate during onboarding and bake it into pricing — discovering the share margin after launch is painful.

OAuth scope discipline

Request only the scopes you actually call. Apps requesting crm.schemas.contacts.write when they only read three properties stall in security review. Map every API call to its scope at PR time:

// Audit script
const callPaths = grep("hsClient.crm", "src/").map(extractPath);
const requiredScopes = callPaths.map(scopeForPath);
const requested = new Set(appConfig.scopes);
const missing = requiredScopes.filter(s => !requested.has(s));
const extra = [...requested].filter(s => !requiredScopes.includes(s));
console.log({ missing, extra });

Support is part of the product

A 4-star app with a 1-star support thread loses installs. Budget at minimum: a docs site, a one-business-day email SLA, an in-app status indicator, and a public changelog. Under-supported listings collect bad reviews that take quarters to undo.

What to do this week

Pick one private app you would consider publishing, audit its OAuth scopes against actual API calls, and write the install + uninstall flow as a one-page runbook before opening a marketplace listing draft.

[object Object]
Share