Marketplace

00

Before you begin

The HubSpot Marketplace is a curated catalog. The team running it has the same incentive any app-store reviewer has: keep the catalog something the platform owner is proud to recommend. Getting listed is a review, not a publish, and the reviewer is a human who opens your install URL, clicks around, and reads your privacy policy. The clearer you make their job, the faster you get out of the queue.

HubSpot publishes its listing requirements, and the Ecosystem Quality team reviews against them by hand: an initial review within 10 business days, and a feedback loop bounded at 60 days from the time feedback is shared. Miss a minimum requirement and the listing is rejected; miss a listing-field requirement and it goes back to Draft with the reviewer's feedback. Only one app can be in review at a time; a second submission is rejected automatically.

The minimum requirements HubSpot checks

The listing fields have their own rules, and these are the ones that set a listing back to Draft. Every URL must be live, public, and crawlable (HubSpot verifies with its own crawler, so allow the HubSpot Crawler user agent), and URL fields are capped at 250 characters. You need a public setup guide specific to the HubSpot integration, a Shared data table that matches the scopes you request (read plus write scopes on an object means you advertise a bi-directional sync), pricing that matches your website and lists only the plans that include the integration, and at least one support contact method. The Testing info tab needs review instructions and credentials for the reviewer, plus at least a main Technology Partner Program point of contact.

The rest of this guide walks the artifacts in the order the reviewer opens them.

The app under review: Email Guard

The submission this guide prepares is Email Guard, the email-deliverability app every other guide builds: the validate-email workflow action, the suppression-list sync, the email-health card, and the email-verified timeline event. It started life as a private app in Getting started, and the app-events guide already flipped distribution: 'private' to 'marketplace' and auth to 'oauth' in hsx.config.ts, because timeline events require both. That flip is the technical half of going public; this guide is the review half, where the same declaration becomes the thing a human evaluates.

What HS-X handles for you (so you can skip those sections)

HS-X auto-generates the OAuth install URL, handles BAD_REFRESH_TOKEN recovery with a re-install nudge, pins your manifest to a supported platform version, and routes 429s through a rate-limit-aware HTTP client. The reviewer-facing surface is still yours, but the load-bearing parts of “yes the OAuth flow works” are handled. The places you still have to write something yourself are the questionnaire answers, the Shared data table, and the listing copy, which are exactly what the rest of this guide covers.

01/ 07

Pre-flight: from 'works on my portal' to OAuth-ready

Most pre-marketplace apps are subtly portal-coupled. They were built and tested on one developer portal, with one OAuth token, against one set of properties. The marketplace reviewer installs on a fresh portal with a different account topology, different custom properties, and a user role that may not match yours. Pre-flight is the exercise of making the app behave correctly under that mismatch.

Scope minimization

Ask for the narrowest scopes that let your features work, and nothing else. HubSpot's listing requirements say every requested scope must be used, and that the Shared data table must reflect the scopes you request; a write scope beside a listing that only describes reporting is exactly the mismatch that rule catches. Email Guard requests exactly two scopes, and each one maps to a feature the listing names:

// hsx.config.ts — declare scopes once; the app manifest is generated from this.
export default defineApp({
  name: "Email Guard",
  scopes: [
    "crm.objects.contacts.read",   // the email-health card and check-email-health tool read verdicts
    "crm.objects.contacts.write",  // validate-email and the suppression-list sync write them
  ],
});

The write scope survives review because the listing describes a write feature: the verdict properties on the contact. If Email Guard were card-only, the same scope would be the rejection example above. When a feature inside your app needs a broader scope than the core ones (say, a future deal-stage write from the card), declare it as an optional scope and gate the feature behind it. The reviewer sees a smaller required-scope list at install and a clearly named optional permission users opt into separately.

BAD_REFRESH_TOKEN recovery

HubSpot refresh tokens rotate. Tokens get revoked when a portal admin uninstalls and reinstalls, when a user is removed from a portal, or when HubSpot rotates the underlying app secret. Every production install hits this within the first few weeks. The reviewer will not test this directly, but they will install, uninstall, and reinstall on the same portal, and if your app crashes on the second install because it cached a stale token, that’s an immediate bounce.

The HS-X runtime owns this failure mode. When a token refresh fails with a definitive revocation (BAD_REFRESH_TOKEN, invalid_grant), the runtime marks the install uninstalled and stops invoking capabilities against that portal; the portal’s uninstalledAt lands in your install telemetry. It distinguishes revocation from transient failures, so a HubSpot 5xx never gets a portal marked dead. When the same portal reinstalls, the OAuth callback accepts the fresh install and the runtime resumes: no stale-token crash, because nothing in your handler code ever held the token.

What is yours: surfacing the state. Watch for uninstalled portals in your monitoring and treat a portal that could reinstall as a customer-success ping, not just a metric.

Install URL and seamless-install return handling

A live install URL is required for submission. For an HS-X app, register the deployed tenant Worker’s /oauth-callback as the OAuth redirect URI, and use HubSpot’s generated install/authorize flow for the Marketplace Install button; do not substitute a marketing page or settings screen for the callback. The callback is where HS-X exchanges the authorization code, seals the install tokens, and records the portal before any browser redirect happens.

HubSpot’s seamless Marketplace flow calls that endpoint with code, returnUrl, and step=finalize. HS-X validates that returnUrl belongs to HubSpot, completes the install, and redirects the embedded installer back to it. Returning to HubSpot is mandatory — sending the browser somewhere else can create an install loop. This is different from partner sign-in, where step=authorize lets an app show its own login/onboarding page before OAuth finalization. HS-X does not currently implement partner sign-in, so leave that option disabled in the listing editor.

HubSpot is making this seamless flow mandatory. Per its app install flow page, after October 26, 2026 any listed app that changes its listing must use it, and opting in early (Listing info, Enable seamless install flow) is irreversible for that app. The install endpoint must also be frameable by HubSpot's embedded browser context: if you set a Content Security Policy, allow frame-ancestors 'self' https://app.hubspot.com https://app-eu1.hubspot.com.

For installs you initiate outside the Marketplace, build the authorize URL from your app’s client ID, scope list, and tenant callback, and confirm you’re hitting HubSpot’s current OAuth endpoints (double-check the OAuth quickstart before pasting). Keep the URL’s scope list in sync with the scopes array in hsx.config.ts; the reviewer compares scope-list-on-install against listing-page claims.

For direct/external installs, callback failures render the HS-X install error page. In HubSpot’s embedded seamless flow, the runtime returns the browser to HubSpot’s validated returnUrl even when finalization fails, as HubSpot requires, so the embedded installer can recover without an open redirect or a consent-screen loop.

For a direct/external install, you can send the installer to your own setup page after HS-X has safely stored the install:

// hsx.config.ts
export default defineApp({
  // ...
  install: {
    successUrl: "https://emailguard.example/setup/complete",
  },
});

HS-X appends hsxAppId, hsxInstallId, and hsxPortalId as non-secret query parameters. The destination must use HTTPS (localhost HTTP is allowed for development), cannot contain embedded credentials, and is baked into the deployed Worker rather than accepted from an untrusted request. A HubSpot-supplied seamless-install returnUrl always takes precedence.

Secrets handling (where the refresh token lives, who can read it, how it’s rotated) is covered separately. The reviewer will ask in the questionnaire how you store tokens at rest; read the secrets guide before you fill out step 2.

02/ 07

The security questionnaire

The questionnaire is the single longest artifact you will write for HubSpot. HubSpot requires it at certification, where it covers encryption, access controls, and OAuth token lifecycle management, and it is worth answering before you list, because the listing reviewer asks the same questions in writing when something looks off. Most answers are short; a handful are essay-length and those are where reviewers spend their time. This section gives you a fact matrix for HS-X — what is actually true about where your app’s data lives and how it is handled — so your answers are grounded rather than aspirational. It uses Email Guard as the worked example; the shape is the same for any HS-X app.

The HS-X data-handling fact matrix

HS-X stores data in two tiers, and almost every questionnaire answer follows from that split:

• Tenant data plane — the developer’s own Cloudflare account (D1, KV, R2). This holds installer/user records, app-generated data, and tenant-emitted events. In direct/unlinked mode it is the only place this data ever lives.
• HS-X control plane — HS-X’s own Cloudflare account. It holds only platform-operating metadata: install-lifecycle state, billing/invoice rows, sync mappings, and the platform credentials the developer explicitly connected. It never holds a shadow copy of installer PII or event payloads.

Paste-ready answers (adapt, then have them reviewed)

These honor the matrix above. Fill the bracketed owner-decision items with a real value after legal/security sign-off — do not ship them with the bracket text in place.

Data residency:

“Installer data and app-generated records live in the developer’s own Cloudflare account (D1/KV/R2), in whatever region that account provisions; HS-X does not relocate it. HS-X’s control plane stores only platform-operating metadata — install-lifecycle state, billing records, and connected platform credentials — and holds no copy of installer PII or event payloads. We do not currently guarantee a specific processing region for that control-plane tier and make no EU-residency commitment beyond the developer’s own Cloudflare account. [Owner to confirm any region commitment with legal before this answer ships.]”

Deletion on uninstall:

“Uninstalls are detected at the next authentication attempt for the portal (the runtime does not yet consume HubSpot's app-lifecycle uninstall events), at which point the install is marked uninstalled, all capability invocations for that portal stop, and uninstalledAt is recorded in install telemetry. Deletion of data keyed to that portal is application code running against the developer’s own Cloudflare bindings; there is no built-in automatic deletion job today, and we do not currently commit a deletion-window number. [Owner/legal to set and publish a retention-and-deletion policy before this answer ships.]”

Breach notification:

“HS-X operates incident runbooks covering credential exposure, data incidents, and related classes under a single-operator model in which the owner is the incident commander. Suspected security issues are reported to the owner directly today; a published security-reporting channel and a committed breach-notification SLA are not yet in place. [Owner/security to set the notification SLA and publish a security contact before this answer ships.]”

Reviewers strongly prefer one plain paragraph that names a gap over a confident claim they can disprove. The bracketed items are exactly the fields the app owner must close with legal and security before submission — not before this guide can help you draft the rest.

Sensitive Data scopes

Step 3 covers the rule. For an app that ships app cards it is a hard no, so settle it before you draft anything else.

03/ 07

Sensitive Data scopes and the allowlist rule

HubSpot's Sensitive Data scopes (crm.objects.contacts.sensitive.read, tickets.sensitive, and the rest of the *.sensitive.* and *.highly_sensitive.* family) are gated, not justified in a form field. Per HubSpot's Sensitive Data guide, a marketplace-bound app on 2025.2 or 2026.03 requests access from HubSpot's Ecosystem Quality team; if approved, the team allowlists the scopes so you can test, then helps you publish with them after a period of testing and compliance checks, and every existing install has to re-authorize.

Two hard limits decide whether that path is even open to you. HubSpot's listing requirements say an app with app cards must not access, request, or use Sensitive Data scopes, and the app card must not display sensitive information. Every HS-X card fetches through hubspot.fetch(), so an HS-X app that ships a card cannot hold Sensitive Data scopes at all. If a feature needs them, it belongs in a separate, card-free app with its own listing.

What does not work

Do not bundle a sensitive scope into the required list “in case we need it later.” Sensitive Data scopes also only work for customers on an Enterprise subscription, so they shrink your installable market the same way HubSpot-hosted serverless functions do. Add the scope when the feature ships and the allowlist is granted, not before.

04/ 07

Where branding lives: project source vs the listing editor

HubSpot shows your app’s branding on two surfaces, and they are edited in two different places. The install consent screen and the in-account app view read from the app manifest your project deploys. The marketplace listing page reads from a listing you fill out in HubSpot’s UI, and it never reads your project source. Most “where do I upload the logo?” confusion is a mix-up between the two.

What ships from your project source

The deployed app manifest carries the app name and the install-screen description. In an HS-X project both come from hsx.config.ts and are regenerated on every hs-x deploy:

// hsx.config.ts — name and description ship in the generated app manifest.
export default defineApp({
  name: "Email Guard",
  description: "Scores every contact's email deliverability and imports your suppression list every 5 minutes.",
  distribution: "marketplace",
  auth: "oauth",
  platformVersion: "2026.03",
  scopes: ["crm.objects.contacts.read", "crm.objects.contacts.write"],
});

App name and description ship from your project source on every deploy; HubSpot’s developer UI shows them read-only. To confirm what is live:

1. In your HubSpot developer account, go to Development.
2. On the Projects page, click your project’s name.
3. On the Overview tab, under Project Components, click your app’s name.

This page shows the most recently deployed app schema, with Auth and Distribution tabs alongside it. There is no edit field for name or description here; change them in hsx.config.ts and deploy again.

What you upload in the listing editor

Everything a marketplace visitor sees comes from the listing editor. The marketplace icon is an 800px by 800px JPG, JPEG, or PNG, uploaded on the listing’s Listing info tab: no text, no wordmark, and the image should touch at least two edges of the canvas. To open the editor:

1. In your HubSpot developer account, go to Development.
2. In the left sidebar, click App Listings.
3. In the upper right, click Create listing. To change an existing listing, hover over it, click More, then Edit.
4. Click your app, pick the primary listing language, and click Next.

You must be a Super admin in the developer account to create or submit an app listing. The wizard has seven tabs: Listing info, App details, Pricing, App features, Support info, Testing info, and Review info. Step 5 covers the copy that goes into them; the table below covers which place owns which branding field.

Field by field: source tree or HubSpot UI

The listing’s Public app name is a separate field from the manifest name; keep the two identical so the name a customer clicks in the marketplace matches the name on the consent screen. The verified domain in the last row is what replaces the “this app hasn’t been verified” install banner for apps that aren’t listed yet; HubSpot’s app management guide walks the DNS setup. For every manifest field beyond branding, the canonical reference is HubSpot’s app configuration page.

05/ 07

Listing copy: the four required artifacts

The listing page is your conversion surface. A reviewer reads it for accuracy. A prospective customer reads it for fit. The same copy has to satisfy both. Four artifacts carry the review (the tagline, the App Overview, the setup guide HubSpot requires you to link, and the screenshots), and each has a pattern that converts. HubSpot's documented limits on the wizard: up to two categories, up to eight screenshots, up to five pricing plans, up to 10 HubSpot features, and up to six other tools. The length advice below is ours, not HubSpot's.

The tagline

This is the headline next to your app icon in marketplace search results. HubSpot publishes no character limit; keep it to one line. The pattern that converts: a verb, a noun the user recognizes, and a payoff. Skip the company name, skip “the best,” skip adjectives.

• Bad: “Email Guard — the best email verification integration for HubSpot users.” (puffery, no payoff)
• Better: “Score every contact’s email deliverability before your next send.”
• Bad: “AI-powered email intelligence for revenue teams.” (vague, no concrete output)
• Better: “Flag bounced and suppressed addresses on the contact record automatically.”

The App Overview

HubSpot asks for what the app does, the business problems it solves, and why users should install it, with no length limit; we recommend 200 to 400 words, structured as: problem, who has it, what the app does in one sentence, how install works in three steps, who it integrates with. The reviewer is checking the third bullet against the actual install. The customer is reading the first two. Keep paragraphs short, and keep the copy specific to the integration rather than your product in general, because HubSpot names generic product copy as a reason to send a listing back to Draft. Email Guard’s:

Every send to a dead address chips away at your sender reputation, and
most teams find out from a bounce report after the damage is done. If
your deliverability rate drops every time marketing imports a list, this
app is for you.
 
Email Guard scores every contact's email deliverability through your
verification provider, imports your suppression list every 5 minutes,
and shows the verdict on an email-health card on every contact record.
Workflows can branch on the score before a send goes out.
 
To install:
1. Click Install on this page and grant the requested scopes.
2. Paste your verification provider's API key on the welcome screen.
3. Add the "Validate email address" action to any contact workflow — done.
 
Works with: any verification provider exposing a verify-and-suppression
API. Writes only Email Guard's own contact properties (email health
status, score, suppression fields); never edits the address itself.

The setup guide

HubSpot requires a public setup guide specific to the HubSpot integration, linked from the listing, and publishes its own requirements and template for it. Write it as a linear, screenshot-backed walkthrough of the first 90 seconds after Install: three to five screens, each with a one-sentence caption. Your review instructions on the Testing info tab are the reviewer's test script, and the setup guide is what customers follow, so keep the two consistent. If step 2 of Email Guard’s guide shows a “paste your API key” screen and the reviewer can’t find that screen after Install, the listing fails on accuracy.

Screenshots and video

HubSpot allows up to eight screenshots, each with alt text. Capture three or more from a real portal seeded with the kind of data your target customer would have, and never show personal data (HubSpot asks for placeholder or hidden data). Stock-looking screenshots (three contacts named “John Doe,” empty pipeline columns, lorem-ipsum company names) read as generic product copy, which is a documented reason to send a listing back. The demo video slot is optional for a listing and mandatory later for certification; a 60 to 90 second video generally helps install conversion.

06/ 07

The platform-version supported requirement

HubSpot’s versioning page lists 2026.03 as Current and 2025.2 as Supported; either one can be listed. Once a version is announced unsupported (2025.1 and 2023.x today), apps on it cannot be listed. The HS-X CLI defaults new projects to 2026.03.

Check your current version in hsproject.json (the first deploy writes it; the value mirrors platformVersion in hsx.config.ts):

{
  "name": "email-guard",
  "srcDir": "src",
  "platformVersion": "2026.03"
}

Before you submit, confirm your last deploy ran against a currently supported version. HubSpot’s platform versioning page is the source of truth; re-check it when you submit, because the supported set rolls forward over time.

Multi-environment setup (which Cloudflare account ID and which HubSpot portal each platform version targets) is covered in the environments guide. Get that wired before you submit, so the reviewer’s test portal lands on your prod environment, not your dev.

07/ 07

The rejection reasons HubSpot documents, and how to dodge them

HubSpot's listing requirements name the conditions that reject a listing or set it back to Draft. The five that map most directly onto an HS-X app, each with a fix. Run through the table before you submit; most teams get bounced on something they could have caught in 20 minutes of self-review.

What happens after submission

HubSpot's listing requirements state an initial review within 10 business days, and a review and feedback loop of no more than 60 days from the time HubSpot shares feedback. You'll get the feedback in writing. Answer the same day if you can; each round adds days to the queue.

You can ship updates to the underlying app during review without resubmitting the listing, as long as you don't change the scope list or break the setup guide. HubSpot's stated bound is the 60 days above; keep scopes and listing copy stable during review so you are not restarting the conversation, and save both kinds of change for after approval.