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.

There are five concerns the reviewer works through, in roughly this order. Get all five right and the review is short. Miss one and you bounce, usually with a one-line reason and a four-week wait before you can resubmit.

The five reviewer concerns, in order

1. Security. OAuth handling, token storage, the scopes you ask for, and what happens when something goes wrong. The May 2026 update expanded the OAuth/token sections of the questionnaire and a lot of the new fields are about sensitive-scope justification.
2. Reliability. Does the app stay up? Does it handle HubSpot's 429s gracefully? Does it degrade or just throw on a transient failure? Reviewers test this by installing on a clean portal and watching for visible errors during the first 24 hours.
3. UX. Does install actually work? Does the app communicate state (loading, empty, error) instead of staring blankly at the user? Is there a path to uninstall and re-install without manual support?
4. Accuracy. Does what the listing claims match what the app does? If your one-liner says "scores email deliverability" and the reviewer can't find a score anywhere inside the app within 60 seconds of installing, that's a rejection.
5. Brand fit. Is the app something HubSpot is comfortable recommending? This is the soft criterion and the one most under-prepared founders skip. A perfectly secure app that overlaps 90% with HubSpot's native CRM is a harder sell than a perfectly secure app that fills an obvious gap.

The rest of this guide walks the five concerns in order, with the exact artifacts each one asks for.

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 scope justifications, 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. Reviewers explicitly look at the scope list on install and flag any scope whose use is not obvious from the listing description. A common 2026 rejection is "asks for crm.objects.contacts.write but the listing only describes a reporting feature." 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 builder and install error handling

A live install URL is required for submission. Build it from your app's client ID, scope list, and redirect URI, and confirm you're hitting HubSpot's current OAuth endpoints (the 2026 update migrated to the v3 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-claim.

For install error handling, the rule is simple: if anything fails during the OAuth callback, show a page that names the error and links to your support URL. The most common bounce in this area is "install loop": the OAuth callback throws, the user gets bounced back to the consent screen, they click approve again, the callback throws again. See step 7 for the fix pattern.

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 How to · Secrets before you fill out step 2.

02/ 07

The security questionnaire

The questionnaire is the single longest artifact in the submission. The May 2026 update expanded the OAuth/token sections; the form spans data handling, access control, incident response, and sensitive-scope justification. Most are short text answers; 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 (ADR-014 §9), 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 (ADR-010, ADR-014 §9).
• 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 (ADR-014 §9).

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 (ADR-010, ADR-014 §9). 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 — HubSpot sends no uninstall webhook — 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 honest 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-scope justification

Step 3 covers this in full because it is the single most-rejected questionnaire section in 2026.

03/ 07

Sensitive-scope justification — the 2026 rule

Some OAuth scopes are flagged sensitive and require a written justification at submission. The exact list and the format HubSpot wants you to use both move around. Check the current app marketplace listing requirements before you write yours, and treat that page as canonical.

The shape of a justification that tends to land: name the user-visible feature that requires the scope, then name the safeguards (what you write, when, what you don't touch, how conflicts resolve). Keep it specific. "We sync data" with no feature named or no conflict rule is the most common rewrite request.

What does not work

Do not bundle a sensitive scope into the required list "in case we need it later." The justification reviewer asks "what feature today uses this scope," and if the answer is "future roadmap," the listing is rejected. Add the scope when the feature ships, 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. Select 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 are required, and each has a pattern that converts.

The one-liner (≤80 characters)

This is the headline next to your app icon in marketplace search results. 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 description

Roughly 200–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. 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 install walkthrough

A linear, screenshot-backed walkthrough of the first 90 seconds after Install. Three to five screens, each with a one-sentence caption. Reviewers use this as the test script when they install your app; if step 2 of Email Guard's walkthrough shows a "paste your API key" screen and the reviewer can't find that screen after Install, the listing fails accuracy review.

Screenshots and video

Three to six screenshots minimum, captured from a real portal with realistic data. Stock-looking screenshots (three contacts named "John Doe," empty pipeline columns, lorem-ipsum company names) are a common reason we see listings sent back ("screenshots not from a real portal"). Use a dev portal seeded with the kind of data your target customer would have. A 60–90 second video is optional but generally helps install conversion.

06/ 07

The platform-version supported requirement

HubSpot's May 2026 changelog lists both 2025.2 and 2026.03 as currently supported platform versions for new listings; either one is fine, as long as you target a currently supported version. Older versions outside that supported set 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 supported platform versions 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 How to · Environments. Get that wired before you submit, so the reviewer's test portal lands on your prod environment, not your dev.

07/ 07

Common rejection reasons and how to dodge them

Five reasons we commonly see listings sent back. Each one has a specific 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 doc states the review/feedback loop should take no more than 60 days from the time HubSpot shares feedback; expect up to that long, and longer when sensitive scopes are involved. You'll get one or two rounds of questions from the reviewer in writing. Answer the same day if you can, because every reply restarts a multi-day clock on their side.

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 install walkthrough. Scope changes mid-review reset the security clock. Listing copy changes mid-review reset the accuracy clock. Save both for after approval.

Where next

• How to · Billing — once the listing is live, wire usage-based or seat-based billing so installs actually generate revenue. HubSpot does not currently operate a marketplace billing system; you bring your own (Stripe, etc.) and the billing guide covers the wiring.
• How to · Secrets — the questionnaire's "how do you store tokens at rest" section maps directly onto HS-X's secrets handling, and the answer is short if you've already read this guide.
• How to · Environments — keeping a clean prod environment separate from your dev and staging portals is what lets the marketplace reviewer land on the right install without you scrambling at the last minute.