{"name":"Projects App Guide Answer Index","url":"https://projectsappguide.com/answers","generatedFrom":"https://projectsappguide.com/sitemap.xml","disclaimer":"Independent educational guide. Not affiliated with, endorsed by, or sponsored by HubSpot. Verify critical commands and platform behavior against official HubSpot documentation before deploying.","keyBoundary":"The May 26 and June 23, 2026 dates discussed here affect new legacy public app creation through the legacy Developer Platform UI. They should not be described as existing legacy public app shutdown dates under that specific sunset.","pages":[{"title":"HubSpot Legacy Public App Creation Sunset: May 26 and June 23, 2026","url":"https://projectsappguide.com/hubspot-legacy-public-app-creation-sunset","intent":"Understand the deadline and avoid overreacting.","lastSourceCheck":"2026-08-29","summary":"The May/June sunset disables new legacy public app creation in the legacy UI. It does not mean existing legacy public apps stop functioning under this specific event.","answerSnapshot":{"shortAnswer":"The May 26 and June 23, 2026 HubSpot dates affect new legacy public app creation through the legacy Developer Platform UI, not existing legacy public app runtime under this specific sunset.","appliesTo":"Developer teams planning to create a new public or Marketplace app after the relevant account-date cutoff.","verify":"Open HubSpot's legacy public app creation sunset changelog and the Projects CLI create-app docs before choosing a path.","boundary":"Do not describe these dates as an existing legacy public app shutdown notice."},"claims":[{"claim":"May 26, 2026 affects new developer accounts created on or after that date.","source":{"label":"Legacy Public App Creation Sunset","url":"https://developers.hubspot.com/changelog/legacy-public-app-creation-sunset"}},{"claim":"June 23, 2026 affects developer accounts created before May 26, 2026.","source":{"label":"Legacy Public App Creation Sunset","url":"https://developers.hubspot.com/changelog/legacy-public-app-creation-sunset"}},{"claim":"The safer next step for new public app creation is to review the Projects-based CLI app creation path.","source":{"label":"Create a new app using the CLI","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"}}],"sections":[{"heading":"What changed","body":["HubSpot's changelog describes a staged sunset for creating new legacy public apps through the legacy Developer Platform UI. Beginning May 26, 2026, developer accounts created on or after that date cannot use that legacy UI path for new public app creation. Beginning June 23, 2026, the same new legacy public app creation path is disabled for developer accounts created before May 26, 2026.","The practical planning question is narrow: does your team need to create a new public or Marketplace app after these dates? If yes, your review should move toward the Projects-based developer platform and CLI app creation docs. If no, this sunset may still be a reason to plan modernization, but it should not be treated as an immediate breakage event for an existing legacy public app.","For searchers landing here in a hurry, the safe wording is: new legacy public app creation is affected. Existing legacy public apps continue functioning under this specific sunset. Any separate platform migration, Marketplace, or CRM card deadline should be evaluated from its own official source."]},{"heading":"Affected vs not affected","body":["Affected: a team that needs to create a new public app through the legacy Developer Platform UI after the relevant account-date cutoff. That team should review the Projects-based app creation path and the CLI project commands before starting new work.","Not affected by this specific event: an existing legacy public app simply continuing to run. That app may still deserve an inventory, migration plan, or Marketplace readiness review, but the May 26 and June 23 dates should not be described as a shutdown date for existing legacy public apps.","Adjacent but separate: apps with classic or legacy CRM cards have their own October 31, 2026 modernization deadline. Keep that card workstream separate from the May/June public app creation sunset so teams do not mix two different official notices."]},{"heading":"What to do next","body":["First, record whether the developer account was created before or after May 26, 2026 and whether the team needs a net-new public or Marketplace app. Second, classify the app state: new app, existing non-project legacy public app, existing project-based app, private app, or CRM card modernization. Third, open the official HubSpot source linked below before selecting a command.","If the work is a new public app, review `hs project create`. If the work is an existing public app that is not already project-based, review the public app migration docs and `hs app migrate` path. If the work is an existing project app, inspect `hsproject.json` and platform-version guidance before deciding whether `hs project migrate` is relevant.","Use this page as a scope guard. It helps prevent both underreaction and overreaction: do not ignore the creation sunset if you build new public apps, and do not tell stakeholders that existing legacy public apps stop functioning on May 26 or June 23, 2026."]}],"executionContract":null,"checklist":["Confirm whether you need to create a new public or Marketplace app.","If yes, review the Projects CLI create-app flow.","If no, document whether you only need monitoring, modernization, or app-card planning."],"officialSources":[{"label":"Legacy Public App Creation Sunset","url":"https://developers.hubspot.com/changelog/legacy-public-app-creation-sunset"},{"label":"Create a new app using the CLI","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"}],"faq":[{"question":"Do existing legacy public apps stop working on May 26 or June 23, 2026?","answer":"No. This specific sunset affects new legacy public app creation through the legacy Developer Platform UI. It should not be described as a shutdown date for existing legacy public apps."},{"question":"Who should care about the May and June 2026 dates?","answer":"Teams that need to create a new public or Marketplace app through the legacy UI after the relevant account-date cutoff should review the Projects-based CLI app creation path."},{"question":"What is the safest next step?","answer":"Classify the app state, record whether the work is new app creation or modernization, then open the current HubSpot changelog and Projects CLI docs before choosing a command path."}],"naturalLanguageQuestions":["HubSpot Legacy Public App Creation Sunset: May 26 and June 23, 2026","Do existing legacy public apps stop working on May 26 or June 23, 2026?","Who should care about the May and June 2026 dates?","What is the safest next step?"]},{"title":"HubSpot Projects CLI Checklist","url":"https://projectsappguide.com/hubspot-projects-cli-checklist","intent":"Run a preflight before creating or migrating an app.","lastSourceCheck":"2026-08-29","summary":"Use this checklist to classify the app, verify local environment, inspect project files, and choose a command path to verify in official docs.","answerSnapshot":{"shortAnswer":"Before running HubSpot Projects CLI commands, classify the app, inspect project files, record environment details, and identify the official command path to verify.","appliesTo":"Developers and agencies preparing new app creation, migration planning, Marketplace readiness, or CI upload workflows.","verify":"Check current HubSpot CLI create-app, project command, migration, and Marketplace listing docs before production-affecting work.","boundary":"This checklist is a planning and handoff aid, not an official HubSpot migration instruction or approval guarantee."},"claims":[{"claim":"New app creation, public app migration, project migration, private app planning, and CRM card modernization should be classified separately.","source":{"label":"Determine your migration path to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/overview"}},{"claim":"At the 2026-08-29 live check, HubSpot's installation guide supports Node.js 20 or higher, lists CLI 8.12.0 as the current recommended release, and uses `hs account auth` for account authentication.","source":{"label":"Install the HubSpot CLI","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/install-the-cli"}},{"claim":"`hs project create`, project upload, and project open commands should be checked against current project command documentation.","source":{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"}},{"claim":"Marketplace readiness needs listing and review materials beyond project file readiness.","source":{"label":"Listing your app","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/listing-your-app"}}],"sections":[{"heading":"Preflight order","body":["Start with classification, not commands. A new public or Marketplace app, an existing non-project legacy public app, an existing project-based app, an existing private app, and a CRM card modernization project each point to different official docs. Writing down the app category first prevents a common failure mode: running a plausible CLI command before the app structure is understood.","After classification, inspect the local and account context. Record HubSpot CLI version, Node version, authenticated account, developer account ID, whether `hsproject.json` exists, current `platformVersion`, and where `app-hsmeta.json` lives. These checks are deliberately simple, because they create the evidence a developer or agent needs before giving production-affecting guidance.","Finally, connect the app inventory to delivery risk: OAuth redirect URLs, scopes, Marketplace listing requirements, support URL, privacy URL, CI secret handling, and a source recheck date. The checklist is meant to produce a handoff that another developer can verify, not a blind migration script."]},{"heading":"Prove the local environment and account","body":["Run `node --version` and `hs --version` before touching an app. At this page's 2026-08-29 source check, HubSpot's installation guide supports Node.js 20 or higher and lists HubSpot CLI 8.12.0 as the current recommended release. Because the recommended CLI release changes over time, re-open that guide and update with its documented `npm install -g @hubspot/cli` command when your recorded version is not acceptable for the task.","Authenticate with `hs account auth`, then use `hs account list` to confirm the intended account is present. If the repository should always target one account, review HubSpot's directory-level `hs account link` flow instead of depending on whichever account happened to be the global default.","The pass condition is evidence, not a lack of errors: record Node and CLI versions, the intended account name or ID, and the project directory's account selection. If authentication, account visibility, or developer-tool access is wrong, stop before create, migrate, upload, or deploy and repair that prerequisite against the current official CLI docs."]},{"heading":"How to use this checklist with an agent","body":["Paste the app classification, file tree, CLI version, Node version, and target timeline into your coding agent. Ask the agent to return a likely path to verify, open questions, and source links. The packaged skill uses the same sequence and explicitly tells the agent to avoid official, certified, endorsed, or guaranteed claims.","If the agent cannot see current HubSpot docs during the session, require it to say that. This matters because HubSpot platform documentation can change, and the local source archive in this project was captured on 2026-05-24.","For agencies, use the checklist as a client intake artifact. It gives non-developers a way to see why the project is being routed to new app creation, public app migration, project migration, private app manual planning, or CRM card modernization."]}],"executionContract":null,"checklist":["Run `node --version`; require Node.js 20 or higher unless current HubSpot guidance has changed.","Run `hs --version`, recheck the current recommended release, and update with the documented `npm install -g @hubspot/cli` command when needed.","Authenticate with `hs account auth`, then confirm the intended account with `hs account list`.","Use or review `hs account link` when a repository directory must target a specific authenticated account.","Find `hsproject.json` and record `platformVersion` if present.","Find `app-hsmeta.json` and confirm its expected project location.","Inventory OAuth redirect URLs and scopes.","Document whether `hs project create`, `hs app migrate`, or `hs project migrate` is the path to verify.","Check Marketplace listing requirements before submission."],"officialSources":[{"label":"Install the HubSpot CLI","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/install-the-cli"},{"label":"HubSpot CLI reference","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/reference"},{"label":"Create a new app using the CLI","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"},{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"},{"label":"Determine your migration path to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/overview"},{"label":"Listing your app","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/listing-your-app"}],"faq":[{"question":"What should I check before running a HubSpot Projects CLI command?","answer":"Classify the app first, then record CLI version, Node version, authenticated account, project files, platform version, app configuration, scopes, redirect URLs, and source-check date."},{"question":"Can this checklist replace HubSpot documentation?","answer":"No. It is an independent planning checklist. Production-affecting commands, uploads, submissions, and client handoffs should be verified against current official HubSpot documentation."},{"question":"What does the paid bundle add?","answer":"The bundle packages the checklist into reusable buyer files, including a command cheatsheet, CSV inventory tracker, developer handoff template, agent skill folder, and source map."}],"naturalLanguageQuestions":["HubSpot Projects CLI Checklist","What should I check before running a HubSpot Projects CLI command?","Can this checklist replace HubSpot documentation?","What does the paid bundle add?"]},{"title":"Use hs project create for a New HubSpot Marketplace App","url":"https://projectsappguide.com/hs-project-create-marketplace-app","intent":"Create a new app with the Projects-based workflow.","lastSourceCheck":"2026-08-29","summary":"HubSpot's create-app docs describe new developer platform apps as initialized using the HubSpot CLI, with `hs project create` as the setup command to review.","answerSnapshot":{"shortAnswer":"`hs project create` is the Projects CLI path to review when creating a new HubSpot developer platform app.","appliesTo":"Teams creating a new public or Marketplace app rather than modernizing an existing app.","verify":"Open the create-app docs, project commands docs, and Marketplace listing docs before upload or submission.","boundary":"Do not use new app creation guidance as a substitute for an existing app migration plan."},"claims":[{"claim":"New developer platform apps are created through the HubSpot CLI workflow.","source":{"label":"Create a new app using the CLI","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"}},{"claim":"`hs project create` prompts for project and app choices, then creates a project directory containing `hsproject.json` and `src`.","source":{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"}},{"claim":"`hs project validate` checks whether `app-hsmeta.json` is valid and the project is ready to upload.","source":{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"}},{"claim":"Marketplace submission has separate listing requirements and review materials.","source":{"label":"Listing your app","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/listing-your-app"}}],"sections":[{"heading":"When this path fits","body":["This page is for teams creating a new public or Marketplace app, especially after the legacy public app creation path is no longer available for their developer account. HubSpot's create-app documentation points new developer platform apps toward the CLI-based Projects workflow, with `hs project create` as the setup command to review.","This is not the page to use when you only need to maintain an existing legacy public app. It is also not enough for a private app migration decision. In those cases, classify the app first and follow the relevant migration or private app docs.","The output you want before a developer starts is a short creation brief: target developer account, app name, authentication type, OAuth redirect URLs, scopes, feature list, Marketplace intent, and who owns listing/support/privacy materials."]},{"heading":"Command flow to verify","body":["First satisfy the CLI preflight: Node.js and CLI versions recorded, `hs account auth` completed, and the target developer account confirmed. From the parent directory where the project should live, run `hs project create`. The current project-command reference says the interactive flow asks for name, destination, project base, distribution, authentication type, and features; choose App as the project base for the full app-creation guide.","The expected local result is a new project directory containing top-level `hsproject.json` and an `src` folder. Do not continue if those are absent or the generated choices do not match the creation brief. Review the generated app and feature `*-hsmeta.json` files, set stable UIDs before first upload, and configure OAuth redirect URLs and scopes when OAuth applies.","Run `hs project validate` from the project directory before `hs project upload`. Fix validation findings rather than using upload as the first syntax check. A successful upload creates a build; open it with `hs project open`, confirm the build/deploy result, connect OAuth client credentials to the backend when applicable, and complete a test install before calling the task finished."]},{"heading":"Completion evidence and failure recovery","body":["A complete creation handoff should show the recorded Node and CLI versions, intended account, generated project path, `hsproject.json`, selected distribution and auth model, stable UIDs, validation result, build ID, deploy state, and test-install result. Project creation alone is not a completed app workflow.","If creation stops before the expected directory and files exist, keep the incomplete directory out of the upload path, confirm account/auth and prompt choices, and rerun only after deciding whether to remove or preserve the partial output. If `hs project validate` fails, repair the reported `app-hsmeta.json` or feature configuration before upload. If the build fails, inspect Builds & Deploys through `hs project open`; do not claim installation readiness.","For OAuth apps, an uploaded project is still incomplete until the backend uses the app's HubSpot client ID and client secret and the configured redirect URL matches the tested OAuth callback. Keep credentials out of source control, tickets, and agent prompts."]},{"heading":"Marketplace readiness notes","body":["A Projects CLI app can still fail a launch workflow if Marketplace materials are unfinished. Assign owners for support contact, privacy policy, testing instructions, screenshots or assets, and install-flow evidence.","Keep the product language precise with clients: this checklist helps prepare a reviewable workflow, but it does not guarantee Marketplace approval or certify compliance. Marketplace requirements must be checked against HubSpot's current listing documentation before submission.","If the app includes classic CRM cards, create a separate app-card modernization task. The CRM card deadline is not the same as the May/June legacy public app creation sunset."]}],"executionContract":null,"checklist":["Complete Node, CLI, authentication, and target-account preflight.","Run `hs project create` and confirm the generated directory contains `hsproject.json` and `src`.","Record distribution, auth model, selected features, and stable component UIDs.","Run `hs project validate` and resolve configuration findings before upload.","Run `hs project upload`, then use `hs project open` to capture the build and deploy state.","Connect OAuth backend credentials when applicable without committing secrets.","Complete and record a developer or test-account install."],"officialSources":[{"label":"Install the HubSpot CLI","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/install-the-cli"},{"label":"Create a new app using the CLI","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"},{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"},{"label":"Listing your app","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/listing-your-app"}],"faq":[{"question":"When should I use hs project create?","answer":"Use it as the official path to review when creating a new Projects-based app. Do not use it as a substitute for planning an existing app migration."},{"question":"Is a Marketplace app automatically ready after project creation?","answer":"No. Marketplace readiness also requires support, privacy, testing, install-flow, listing, and review materials checked against current HubSpot requirements."}],"naturalLanguageQuestions":["Use hs project create for a New HubSpot Marketplace App","When should I use hs project create?","Is a Marketplace app automatically ready after project creation?"]},{"title":"Legacy Public App vs Projects App","url":"https://projectsappguide.com/hubspot-legacy-public-app-vs-projects-app","intent":"Decide whether this is a creation issue or a modernization issue.","lastSourceCheck":"2026-08-29","summary":"The sunset is about creating new legacy public apps. Projects-based apps are the path HubSpot directs new public app development toward.","answerSnapshot":{"shortAnswer":"The key distinction is creation versus modernization: the May/June 2026 sunset affects new legacy public app creation, while migration decisions depend on the existing app state.","appliesTo":"Stakeholders deciding whether a HubSpot app needs new app creation, modernization, migration planning, or a separate card workstream.","verify":"Compare the sunset changelog with the create-app and migration overview docs before telling a client what changed.","boundary":"Do not collapse all older HubSpot app work into one migration deadline."},"claims":[{"claim":"The legacy public app sunset concerns new legacy public app creation.","source":{"label":"Legacy Public App Creation Sunset","url":"https://developers.hubspot.com/changelog/legacy-public-app-creation-sunset"}},{"claim":"New Projects-based app development should be reviewed from the create-app docs.","source":{"label":"Create a new app using the CLI","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"}},{"claim":"Existing app migration paths should be evaluated from migration documentation.","source":{"label":"Determine your migration path to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/overview"}}],"sections":[{"heading":"The difference that matters","body":["A legacy public app and a Projects-based app are not just two labels for the same workflow. The May/June 2026 changelog is about the ability to create new legacy public apps through the legacy Developer Platform UI. The Projects-based developer platform uses CLI and file-based project configuration for new app development.","This distinction matters because stakeholders often compress the announcement into a vague deadline. The safe planning statement is narrower: new legacy public app creation is being disabled; existing legacy public apps continue functioning under that specific sunset.","When you explain this to a client or internal team, separate three questions: Do we need a new public app? Do we need to modernize an existing app? Do we have a separate Marketplace or CRM card deadline?"]},{"heading":"Legacy public app creation","body":["Legacy UI creation is the path being sunset for new public apps. If a team was planning to create a new public app from the old UI, they should shift their planning to the Projects-based CLI app creation flow.","For existing legacy public apps, the right next step is usually inventory and risk review, not panic migration language. Document installs, OAuth behavior, scopes, webhooks, CRM cards, Marketplace status, and any modernization timeline before assigning a command path.","If the existing app is not project-based and modernization is desired, review the public app migration docs and `hs app migrate` guidance. Do not assume a new-app creation flow is the same as migrating an existing app."]},{"heading":"Projects-based app development","body":["Projects-based apps use file-based configuration and HubSpot CLI workflows. That makes the project easier to review in source control, pass through CI checks, and hand off between developers compared with an undocumented UI-only process.","The main planning artifacts are the project files, platform version, app schema/config files, auth configuration, and the commands used for creation, upload, local development, and migration. Those artifacts should be reviewed together instead of scattered across chat notes.","A good handoff ends with the likely path to verify, relevant official source links, and open questions. It should not end with a guaranteed command, because the correct path depends on app type, project state, platform version, and current official docs."]}],"executionContract":null,"checklist":[],"officialSources":[{"label":"Legacy Public App Creation Sunset","url":"https://developers.hubspot.com/changelog/legacy-public-app-creation-sunset"},{"label":"Create a new app using the CLI","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"},{"label":"Determine your migration path to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/overview"}],"faq":[{"question":"Is the legacy public app sunset the same as a migration deadline?","answer":"No. The May and June 2026 sunset affects new legacy public app creation. Migration and platform-version work should be evaluated from the relevant migration sources."},{"question":"How do I explain the difference to a client?","answer":"Separate new app creation, existing app modernization, Marketplace readiness, and CRM card modernization as different workstreams with different official sources."}],"naturalLanguageQuestions":["Legacy Public App vs Projects App","Is the legacy public app sunset the same as a migration deadline?","How do I explain the difference to a client?"]},{"title":"hs app migrate vs hs project migrate","url":"https://projectsappguide.com/hs-app-migrate-vs-hs-project-migrate","intent":"Choose the likely migration command path.","lastSourceCheck":"2026-08-29","summary":"Use app structure and platform version to decide which path to verify. Non-project legacy public app, existing project app, and private app cases should not be collapsed into one generic migration step.","answerSnapshot":{"shortAnswer":"Choose between `hs app migrate` and `hs project migrate` only after inspecting whether the app is non-project legacy, already project-based, public, private, and which platform version it uses.","appliesTo":"Developers with an existing HubSpot app who need to identify the likely migration command path to verify.","verify":"Open the migration overview, public app migration, latest-platform migration, and project command docs before running a command.","boundary":"Treat commands as paths to verify, not commands to run from memory."},"claims":[{"claim":"`hs app migrate` belongs to public app migration guidance, not new app creation.","source":{"label":"Migrate an existing public app","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-an-existing-public-app"}},{"claim":"For 2026.03, a 2025.2 project updates `platformVersion` then uploads, while 2023.1, 2023.2, 2025.1, and pre-version projects use `hs project migrate`.","source":{"label":"Migrate an existing app to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-to-the-latest-platform-version"}},{"claim":"The migration path depends on app state and current project structure.","source":{"label":"Determine your migration path to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/overview"}},{"claim":"A successful non-project public app migration creates and deploys Build #1 as a baseline that HubSpot says can be redeployed to revert later project changes.","source":{"label":"Migrate an existing app to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-to-the-latest-platform-version"}},{"claim":"Migrated v1/v3 timeline-event requests must move to v4 within seven days or the old event endpoints return 401 errors.","source":{"label":"Migrate an existing public app","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-an-existing-public-app"}}],"sections":[{"heading":"Decision rule","body":["Do not choose between `hs app migrate` and `hs project migrate` from memory. Start by inspecting the app: does the repo have `hsproject.json`, what `platformVersion` is recorded, and is the app public, Marketplace-oriented, project-based, or private? Confirm the latest CLI first; the current 2026.03 migration page recommends CLI 8.4.0 or above.","Use the current 2026.03 matrix: a project already on 2025.2 updates top-level `hsproject.json` from `platformVersion` 2025.2 to 2026.03 and runs `hs project upload`; a project on 2023.1, 2023.2, 2025.1, or predating platform versions runs `hs project migrate` from the project working directory; an existing non-project legacy public app uses `hs app migrate` from the parent directory where the new project should be downloaded.","A legacy non-project private app cannot currently migrate to 2026.03 through this path. Stop and use the private-app planning guide rather than substituting a public-app command. Also treat the older public-migration page as feature/limitation evidence, not the authority for the latest target version, because that live page still contains 2025.2 wording while the latest-platform page defines the 2026.03 routes."]},{"heading":"What to inspect before running either command","body":["Inspect the repository root for `hsproject.json`, then record `platformVersion`. Also find the app configuration files, including `app-hsmeta.json` where relevant, and list any serverless functions, app cards, OAuth settings, webhooks, scopes, and Marketplace listing dependencies.","For an existing public app, check active installs and test-install implications before migration. For a project app, understand whether the work is a platform-version update or a broader feature migration. For a private app, capture backend and token implications because the public-app migration decision tree does not automatically apply.","Write down the command as a path to verify, not a command to run immediately. The final pre-run step should be opening the relevant official HubSpot docs and confirming they still match the local source archive."]},{"heading":"Expected output, verification, and recovery","body":["For `hs app migrate`, expect prompts to select the app, confirm compatible components, provide a project name and local path, and set required UIDs. The documented successful operation creates the HubSpot project, converts supported features to source files, builds and deploys Build #1, downloads the new local project, and, when an existing project is migrated, moves the prior `src` files into `archive` before populating the new `src`.","Before making follow-up changes, confirm the new project exists locally and in HubSpot, preserve UID values, record Build #1, open Builds & Deploys, and test existing authentication, installs, and supported features. HubSpot documents Build #1 as the baseline that can be redeployed to revert later project changes; that is a recovery point for later builds, not permission to skip pre-migration backups or feature testing.","If serverless functions used `environment` entries in legacy `serverless.json`, the current 2026.03 guide says those variables are not migrated automatically; recreate them as secrets with the documented `hs secret add` flow before testing functions. If the app has v1/v3 timeline events, move occurrence requests to v4 within seven days because the older endpoints then return 401. Do not schedule migration until that backend cutover has an owner and test window."]},{"heading":"Common wrong turns","body":["Wrong turn 1: using `hs project create` for an existing app modernization project. That command belongs to new Projects-based app creation, while migration paths require a separate review.","Wrong turn 2: treating every older project app as a non-project legacy public app. If `hsproject.json` exists, inspect platform-version guidance before selecting a migration path.","Wrong turn 3: promising automatic private app migration. Private app cases have documented limitations and may need manual planning or a net-new app approach depending on features."]}],"executionContract":null,"checklist":["Run `hs --version`; the current 2026.03 guide recommends CLI 8.4.0 or above.","Find `hsproject.json`, record `platformVersion`, app distribution, and whether the app is legacy or project-based.","Select exactly one current path: 2025.2 edit-and-upload, older-project migrate, non-project public app migrate, or unsupported non-project private review.","Inventory serverless `environment` values, timeline events, UIDs, OAuth, installs, and unsupported features before confirmation.","For `hs app migrate`, record the generated project path, `src`/`archive` result, Build #1, auth/install checks, and feature tests.","Plan `hs secret add` work for legacy serverless environment values and a seven-day v4 cutover for migrated v1/v3 timeline events when applicable.","Open the current official migration docs immediately before running a command."],"officialSources":[{"label":"Determine your migration path to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/overview"},{"label":"Migrate an existing public app","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-an-existing-public-app"},{"label":"Migrate an existing app to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-to-the-latest-platform-version"},{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"}],"faq":[{"question":"How do I choose between hs app migrate and hs project migrate?","answer":"Inspect the repo and app state first. Existing non-project legacy public apps, already project-based apps, and private apps point to different official migration guidance."},{"question":"Should I run a migration command immediately?","answer":"No. Treat the command as a path to verify after app classification, file inspection, install-risk review, and a current official source check."},{"question":"What proves that hs app migrate completed?","answer":"Confirm the new local project and HubSpot project, expected source files, Build #1, preserved auth and installs, and feature tests. Keep Build #1 recorded as the documented baseline for reverting later project changes."}],"naturalLanguageQuestions":["hs app migrate vs hs project migrate","How do I choose between hs app migrate and hs project migrate?","Should I run a migration command immediately?","What proves that hs app migrate completed?"]},{"title":"HubSpot Private App Projects Migration","url":"https://projectsappguide.com/hubspot-private-app-projects-migration","intent":"Avoid choosing an unsupported automatic path.","lastSourceCheck":"2026-08-29","summary":"Private app cases require special care. The latest-platform migration docs warn that migrating a legacy non-project-based private app to 2026.03 is not currently supported.","answerSnapshot":{"shortAnswer":"Private app migration should be treated as source-checked planning; do not assume every private app has an automatic Projects CLI migration path.","appliesTo":"Teams reviewing existing private apps, especially legacy non-project-based private apps.","verify":"Open current private app migration and latest-platform migration docs before proposing a command or replacement path.","boundary":"Do not promise automatic private app migration, compatibility, or official approval."},"claims":[{"claim":"Private app migration has separate guidance from public app migration.","source":{"label":"Migrate an existing private app","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-an-existing-private-app"}},{"claim":"Legacy non-project-based private app migration to 2026.03 has documented limitations.","source":{"label":"Migrate an existing app to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-to-the-latest-platform-version"}},{"claim":"Private app work may require manual planning depending on current app state and features.","source":{"label":"Determine your migration path to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/overview"}}],"sections":[{"heading":"Why this needs caution","body":["Private app migration is not the same as public app migration. HubSpot's latest-platform migration documentation explicitly warns that migrating a legacy non-project-based private app to `2026.03` is not currently supported. That single sentence is enough to require cautious language in any checklist or client handoff.","Some private app modernization paths involve manually moving configuration, webhooks, UI extension code, app cards, backend logic, or token-handling assumptions. Treat the work as a technical discovery project before you describe a migration command.","If a private app includes serverless functions or backend behavior that is central to business logic, document the feature list before proposing a path. The correct output may be a manual plan, a net-new project-based app, or a deferred migration until official docs support the needed path."]},{"heading":"Private app intake checklist","body":["Capture the app's current auth model, token storage, backend services, webhooks, UI extensions, serverless functions, CRM cards, and any scheduled jobs. A private app that only uses an access token has a different risk profile from a private app with custom UI and backend logic.","Record whether the existing app is legacy non-project-based or already project-based. Then compare that state to the current private app and latest-platform migration docs. If the source docs do not support automatic migration for the case, say that plainly.","For agency handoff, mark private app work as 'manual planning/review' unless a developer has rechecked the current official docs and documented a supported path."]},{"heading":"Safe client wording","body":["Use: 'This private app needs source-checked migration planning before we choose a path.' Avoid: 'The CLI will migrate the private app.'","Use: 'The current official docs should be rechecked before any production upload or replacement.' Avoid: 'This checklist guarantees compatibility.'","Use: 'We can inventory configuration and identify a likely path to verify.' Avoid: 'This is an official HubSpot migration plan.'"]}],"executionContract":null,"checklist":["Confirm whether the app is private.","Check for serverless functions.","Document API token and backend implications.","Read private app docs before choosing a path."],"officialSources":[{"label":"Migrate an existing private app","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-an-existing-private-app"},{"label":"Migrate an existing app to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-to-the-latest-platform-version"},{"label":"Determine your migration path to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/overview"}],"faq":[{"question":"Can every private app be migrated automatically?","answer":"No. Private app cases need careful source-checked planning, and documented limitations may apply depending on the app state and target platform version."},{"question":"What should a private app handoff include?","answer":"Include auth model, token handling, backend services, webhooks, UI extensions, serverless functions, CRM cards, current app state, and current source links."}],"naturalLanguageQuestions":["HubSpot Private App Projects Migration","Can every private app be migrated automatically?","What should a private app handoff include?"]},{"title":"HubSpot Developer Platform 2026.03 Upgrade","url":"https://projectsappguide.com/hubspot-developer-platform-2026-03-upgrade","intent":"Plan version upgrade.","lastSourceCheck":"2026-08-29","summary":"The 2026.03 platform version is central to current migration docs. Check `hsproject.json`, current `platformVersion`, and supported migration path before making changes.","answerSnapshot":{"shortAnswer":"A 2026.03 upgrade starts with `hsproject.json`, current `platformVersion`, app type, and the supported migration path in current HubSpot docs.","appliesTo":"Teams maintaining existing project-based apps or evaluating migration to the latest HubSpot developer platform version.","verify":"Open the migration overview, latest-platform migration, and project command docs before changing platformVersion or uploading.","boundary":"Do not treat 2026.03 platform work as the same event as the May/June legacy public app creation sunset."},"claims":[{"claim":"`platformVersion` should be inspected in the project configuration before upgrade planning.","source":{"label":"Determine your migration path to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/overview"}},{"claim":"The current 2026.03 guide recommends CLI 8.4.0 or above and defines different routes for 2025.2, older project versions, and non-project legacy public apps.","source":{"label":"Migrate an existing app to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-to-the-latest-platform-version"}},{"claim":"Legacy `serverless.json` environment values are not migrated automatically and must be redefined as secrets with `hs secret add`.","source":{"label":"Migrate an existing app to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-to-the-latest-platform-version"}},{"claim":"Project command behavior should be checked against current CLI project command docs.","source":{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"}}],"sections":[{"heading":"What to inspect","body":["Look for `hsproject.json` and its `platformVersion` property before discussing a `2026.03` upgrade. The migration overview explains how existing platform versions relate to `2026.03`, including cases where no migration is necessary and cases where older versions need more careful review.","A platform-version upgrade is not the same as the May/June 2026 legacy public app creation sunset. The creation sunset affects new legacy public app creation. The `2026.03` workstream affects project structure, platform version, and supported feature migration paths.","If the project is already on `2026.03`, record that and check whether there is any separate Marketplace, CI, or CRM card work. If it is on an older version, open the latest-platform migration docs before changing files or running commands."]},{"heading":"Planning a version review","body":["Create a small inventory: current platform version, app type, serverless functions, app cards, static auth or OAuth, Marketplace status, and CI upload flow. This keeps version work tied to actual app features.","Use the documented route, not a generic upgrade command. For 2025.2, update the top-level `hsproject.json` value to 2026.03 and run `hs project upload`. For 2023.1, 2023.2, 2025.1, or a project that predates versioning, run `hs project migrate` from that project's working directory and review every feature confirmation prompt.","Do not apply public app assumptions to private app cases. The latest-platform docs include a private-app limitation for legacy non-project-based private apps, so those cases should be flagged for manual review."]},{"heading":"Pre-upload validation and post-upgrade proof","body":["Confirm the current CLI before starting; the current 2026.03 page recommends 8.4.0 or above, while the installation page identifies the latest recommended release. Commit or otherwise preserve the pre-upgrade source state. On the 2025.2 edit-and-upload route, run `hs project validate` after changing `platformVersion` and before upload. On 2023.1, 2023.2, 2025.1, or pre-version routes, run `hs project migrate` first, then validate the generated 2026.03 project before any follow-up upload; do not make a legacy project's pre-migration validate result a gate.","If the older project used serverless functions with `environment` values in `serverless.json`, inventory each name before migration and recreate those values through the documented `hs secret add` flow. Do not copy secret values into source control, the handoff, CI logs, or an agent prompt.","Completion means the project reports 2026.03, the new build succeeds, the intended deployment state is confirmed, and auth, installs, app cards, functions, webhooks, and other affected features pass a written test plan. Use `hs project open` for Builds & Deploys. If validation or build fails, stop deployment, repair the reported source/configuration issue, and create a new build rather than forcing a warning bypass."]},{"heading":"Handoff output","body":["A useful handoff states the current version, the target version to verify, the command or file change to review, and the official docs used. It also lists features that could change migration complexity, such as serverless functions or app cards.","Keep the recommendation reversible until a developer has run the current preflight. The language should be 'likely path to verify,' not 'guaranteed upgrade path.'","Add a source-check date. This repository's official source archive was captured on 2026-05-24, and production decisions should re-open current HubSpot docs."]}],"executionContract":null,"checklist":["Record `hs --version`; the current migration page recommends 8.4.0 or above.","Record current `platformVersion`, project status, app distribution, auth model, and affected features.","Choose the exact 2026.03 route for 2025.2, older project versions, non-project public apps, or unsupported non-project private apps.","Preserve the pre-upgrade source state and inventory serverless environment names without exposing values.","For 2025.2, validate after the version edit and before upload; for older projects, migrate first and validate the generated 2026.03 project before a follow-up upload.","Recreate legacy serverless environment values with the official `hs secret add` flow when applicable.","Use `hs project open` to record build/deploy state and execute the auth, install, and feature test plan."],"officialSources":[{"label":"Determine your migration path to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/overview"},{"label":"Migrate an existing app to 2026.03","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-to-the-latest-platform-version"},{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"}],"faq":[{"question":"Is platformVersion 2026.03 the same as the May/June creation sunset?","answer":"No. Platform-version migration is a separate workstream from the legacy public app creation sunset."},{"question":"What file should I inspect first for platform version?","answer":"Start with `hsproject.json`, then review app type, feature files, serverless functions, app cards, and current migration docs before changing files."}],"naturalLanguageQuestions":["HubSpot Developer Platform 2026.03 Upgrade","Is platformVersion 2026.03 the same as the May/June creation sunset?","What file should I inspect first for platform version?"]},{"title":"HubSpot app-hsmeta.json Structure Checklist","url":"https://projectsappguide.com/hubspot-app-hsmeta-json-structure","intent":"Build and validate app configuration safely.","lastSourceCheck":"2026-08-29","summary":"Put the top-level app schema at `src/app/app-hsmeta.json`, validate it before upload, and treat UID, OAuth, scope, and redirect choices as identity and security decisions—not formatting details.","answerSnapshot":{"shortAnswer":"For a Marketplace-oriented Projects app, start with a stable app UID, `type: app`, app name and description, `distribution: marketplace`, OAuth, at least one allowed redirect URL, and only the required scopes; then run `hs project validate` from the project root before any upload.","appliesTo":"Developers troubleshooting Projects-based app structure, identifiers, auth settings, redirect URLs, scopes, and upload readiness.","verify":"Check the current app-configuration schema, record `hs project validate` output, and verify the resulting HubSpot build and install flow separately.","boundary":"Validation is not an upload, install test, feature test, Marketplace eligibility decision, or approval guarantee."},"claims":[{"claim":"The top-level app schema is a file at `src/app/app-hsmeta.json`; its required core includes a unique UID, app type, description, name, distribution, and auth configuration.","source":{"label":"App configuration","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/app-configuration"}},{"claim":"Marketplace distribution uses OAuth; OAuth redirect URLs use HTTPS except that `http://localhost` is allowed for testing, and an app needs at least one required scope.","source":{"label":"App configuration","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/app-configuration"}},{"claim":"`hs project validate` checks whether `app-hsmeta.json` is valid and the project is ready to upload.","source":{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"}},{"claim":"Changing an app or feature UID after upload makes HubSpot recognize it as a different component, which may be unintended.","source":{"label":"Create a new app using the CLI","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"}}],"sections":[{"heading":"Minimum marketplace schema and file path","body":["HubSpot's app-configuration reference places the top-level schema at `src/app/app-hsmeta.json`. The surrounding project still needs its top-level `hsproject.json`, and feature schemas remain separate `*-hsmeta.json` files under their feature directories.","The smallest useful Marketplace teaching skeleton on this page includes `uid`, `type`, `config.description`, `config.name`, `config.distribution`, and `config.auth`. Marketplace distribution must pair `distribution: marketplace` with OAuth. OAuth needs at least one redirect URL and at least one required scope; the example contact-read scope must be replaced unless the app truly reads contacts.","Logo, permitted URLs, support fields, optional scopes, and conditionally required scopes are not added merely to make the file look complete. Add each only when the app's implemented behavior needs it. Marketplace listing support, privacy, setup, pricing, and review evidence remain a separate gate even if the schema validates."]},{"heading":"Validation ladder and evidence","body":["Run environment and account checks first, then run `hs project validate` from the directory containing the intended `hsproject.json`. A pass should be recorded with the command, exit status, CLI version, target account/profile, commit, and timestamp. A clean terminal with no captured evidence is not a handoff artifact.","Only after validation passes should the team consider `hs project upload`. HubSpot's project-command reference says upload creates a build and may auto-deploy when auto-deploy is enabled. Capture the build ID and status with `hs project list-builds`, open the project with `hs project open`, and separately test OAuth, installation, and each changed feature.","The acceptance ladder is therefore schema pass → build pass → deploy state observed → install/OAuth pass → feature smoke pass. Stopping at schema validation must be reported as `CONFIG_VALIDATED`, not `DEPLOYED`, `INSTALL_VERIFIED`, or `MARKETPLACE_READY`."]},{"heading":"Current official-doc discrepancies","body":["CLI version: the current create-app page still says to use CLI v7.6.0, while HubSpot's current CLI installation page lists 8.12.0 as the recommended release at this guide's 2026-08-29 check. The pages do not reconcile those statements. Use the current installation page as the version-of-record, update with its documented `npm install -g @hubspot/cli@latest` path when appropriate, and record the actual version used.","Local redirect scheme: the create-app JSON example shows `http://localhost:3000/oauth-callback`, while nearby prose calls the sample `https://localhost:3000/oauth-callback`. The app-configuration reference resolves the rule: redirects use HTTPS, with `http://localhost` allowed only for testing. Do not generalize that exception to non-localhost URLs.","File-tree typography: the app-configuration diagrams render `app-hsmeta.json/` with a trailing slash, but the same page repeatedly calls it a configuration file in the app directory. This guide therefore uses the file path `src/app/app-hsmeta.json` and relies on `hs project validate` rather than interpreting the slash as a directory."]},{"heading":"Identity and recovery boundary","body":["Freeze the intended app UID and feature UIDs before the first shared-account upload. HubSpot warns that changing an uploaded UID makes the platform recognize the item as different. Treat an unexpected UID diff as a stop condition, not as a harmless rename.","`hs project validate` is the safe pre-upload gate. `hs project upload` is state-changing because it creates a remote build and may auto-deploy. Before upload, record auto-deploy state, target account, commit, and recovery owner; after upload, do not claim that a Git revert, source backup, or previous build is a universal remote rollback.","Never place client secrets, personal access keys, refresh tokens, or account data in `app-hsmeta.json`, screenshots, verifier output, or the buyer handoff. The schema contains configuration, not runtime secrets."]}],"executionContract":{"prerequisites":["Use the project root that contains the intended `hsproject.json`; record the target account or profile before validation.","Re-open HubSpot's current CLI installation and app-configuration pages; record Node and HubSpot CLI versions instead of relying on a dated minimum.","Choose and peer-review stable app and feature UIDs before the first shared-account upload.","For Marketplace distribution, use OAuth, an HTTPS production redirect URL, and only scopes required by implemented behavior."],"configExample":{"path":"src/app/app-hsmeta.json","language":"json","content":"{\n  \"uid\": \"replace-with-stable-app-uid\",\n  \"type\": \"app\",\n  \"config\": {\n    \"description\": \"Explain the installed app behavior.\",\n    \"name\": \"Example app\",\n    \"distribution\": \"marketplace\",\n    \"auth\": {\n      \"type\": \"oauth\",\n      \"redirectUrls\": [\"https://example.com/oauth/callback\"],\n      \"requiredScopes\": [\"crm.objects.contacts.read\"]\n    }\n  }\n}","note":"This is a source-backed teaching skeleton, not a universal copy-paste config. Replace the UID, URLs, description, name, and example scope; keep the contact-read scope only when the app actually reads contacts. Add optional schema blocks only for implemented behavior."},"steps":[{"action":"Run `node --version`, `hs --version`, and `hs account list` before editing or validating.","expected":"Supported local tooling is recorded and the intended developer account/profile is visible.","verify":"Attach sanitized command output, project-root path, account alias/ID, and timestamp to the handoff.","onFailure":"Repair Node/CLI installation or HubSpot authentication against the current official CLI guide; do not continue to validation.","recoveryBoundary":"These checks are read-only, but never publish config files or output that contain credentials or private account data."},{"action":"From the project root, run `hs project validate`.","expected":"The CLI reports that the app schema is valid and the project is ready to upload.","verify":"Record exit status and output; diff `src/app/app-hsmeta.json` and all feature UIDs against the reviewed commit.","onFailure":"Route by the exact validation message: project discovery, JSON/schema field, auth/distribution, URL, scope, or UID; fix only that class and rerun validation.","recoveryBoundary":"Validation is non-uploading evidence. A pass does not prove remote build, install, OAuth callback, feature behavior, or Marketplace eligibility."},{"action":"After approval of the validated diff, run `hs project upload`, then `hs project list-builds --limit 5` and `hs project open`.","expected":"HubSpot creates a build; its build/deploy state and target project are observable.","verify":"Record build ID, target account/project, commit SHA, build status, deploy status, and whether auto-deploy was enabled.","onFailure":"Do not rerun blindly. Inspect the failed build and account/profile selection, correct the narrow cause, revalidate, then create a new traceable build.","recoveryBoundary":"Upload is state-changing and can auto-deploy. A local revert or previous source snapshot is not a universal remote rollback promise."},{"action":"Install in the intended test account and exercise OAuth callback plus each changed feature.","expected":"The exact redirect completes, requested scopes match behavior, and the changed features work in the target account.","verify":"Capture a sanitized install record, callback result, granted-scope comparison, and feature smoke-test outcomes.","onFailure":"Separate redirect mismatch, denied/missing scope, install permission, backend token exchange, and feature runtime failures; fix and rerun only the affected stage.","recoveryBoundary":"Do not label a test-account pass as Marketplace approval or production-account compatibility across all tiers and permissions."}],"errorRouter":[{"symptom":"CLI cannot find a project or `app-hsmeta.json`.","route":"Confirm the current directory contains the intended `hsproject.json`; confirm the file is `src/app/app-hsmeta.json`, not a directory or a feature-level substitute.","stopWhen":"Stop before upload until project identity and file placement are unambiguous."},{"symptom":"Schema validation rejects required fields or component type.","route":"Compare `uid`, `type`, `config.description`, `config.name`, `distribution`, and `auth` to the current app-configuration table; fix the named field only.","stopWhen":"Stop if the fix would change an already-uploaded UID without explicit identity-migration approval."},{"symptom":"Marketplace distribution is paired with static auth.","route":"Change the design to OAuth for Marketplace distribution or reclassify the app as private; do not patch around the mismatch.","stopWhen":"Stop Marketplace work until product distribution and auth architecture agree."},{"symptom":"Redirect URL is rejected or OAuth returns a redirect mismatch.","route":"Compare the exact configured and requested URL, including scheme, host, path, port, and environment; use HTTPS except the documented `http://localhost` test exception.","stopWhen":"Stop install testing until the exact redirect is reviewed and revalidated; never broaden redirects as a shortcut."},{"symptom":"Install succeeds but API calls fail with authorization or scope errors.","route":"Compare actual endpoint requirements, configured required/optional/conditional scopes, requested install URL scopes, and granted token scopes.","stopWhen":"Stop before adding broad scopes without a feature-level need and updated shared-data documentation."},{"symptom":"Validation passes but upload/build/deploy fails.","route":"Treat this as a later-stage failure: verify account/profile, inspect build output with `hs project list-builds`, and open the exact project; do not edit schema speculatively.","stopWhen":"Stop repeated uploads until one root cause and one recovery owner are recorded."}]},"checklist":["Current CLI install and app-configuration sources re-opened; actual Node/CLI versions recorded.","Project root matched to the intended `hsproject.json` and target account/profile.","Top-level schema stored as `src/app/app-hsmeta.json`.","App and feature UIDs are unique, stable, and peer-reviewed.","Marketplace distribution is paired with OAuth.","Production redirects use HTTPS; `http://localhost` is confined to local testing.","Every requested scope maps to implemented behavior; the example contact scope was removed if irrelevant.","`hs project validate` pass evidence captured before upload.","Build ID, deploy state, target account, and commit captured after any upload.","Install, OAuth callback, granted scopes, and changed features smoke-tested separately."],"officialSources":[{"label":"App configuration","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/app-configuration"},{"label":"Create a new app using the CLI","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"},{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"},{"label":"Install the HubSpot CLI","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/install-the-cli"}],"faq":[{"question":"What is the minimum app-hsmeta.json structure for a Marketplace app?","answer":"Use a stable `uid`, `type: app`, and `config` with description, name, `distribution: marketplace`, and OAuth containing at least one allowed redirect URL and one genuinely required scope. The example on this page is a teaching skeleton; verify the current official schema and add optional blocks only when the app needs them."},{"question":"Does `hs project validate` prove Marketplace readiness?","answer":"No. It checks app configuration and upload readiness. Build/deploy, OAuth/install, feature behavior, Marketplace eligibility, listing validation, and approval are separate evidence stages."},{"question":"Can I rename an uploaded app UID and roll back later?","answer":"Do not treat UID changes as ordinary renames. HubSpot warns that changing an uploaded app or feature UID makes the platform recognize it as different. Stop, review the identity impact, and define recovery before uploading the change."},{"question":"Which HubSpot CLI version should I use when official pages differ?","answer":"At the 2026-08-29 check, the create-app page mentions v7.6.0 while the current installation guide recommends 8.12.0. HubSpot does not reconcile the two on those pages; use the current installation guide as version-of-record, recheck it live, and record the actual version used."}],"naturalLanguageQuestions":["HubSpot app-hsmeta.json Structure Checklist","What is the minimum app-hsmeta.json structure for a Marketplace app?","Does `hs project validate` prove Marketplace readiness?","Can I rename an uploaded app UID and roll back later?","Which HubSpot CLI version should I use when official pages differ?"]},{"title":"HubSpot CLI, Node, and CI Preflight Checklist","url":"https://projectsappguide.com/hubspot-cli-node-ci-preflight","intent":"Prevent environment and CI issues.","lastSourceCheck":"2026-08-29","summary":"Before automating a HubSpot project upload, prove the supported Node/CLI environment, require a 2025.2-or-newer project for the official GitHub Action flow, store account credentials as repository secrets, and define how success and failure will be verified.","answerSnapshot":{"shortAnswer":"A HubSpot CLI CI preflight should record versions, target account strategy, secret handling, selected command path, and source-check date before upload automation.","appliesTo":"Teams adding HubSpot Projects CLI upload or migration steps to local development and CI/CD workflows.","verify":"Open the current CLI install, GitHub Actions, and project command docs before changing pipeline behavior.","boundary":"Do not expose HubSpot tokens, client secrets, private keys, or account credentials in logs or prompts."},"claims":[{"claim":"At the 2026-08-29 check, HubSpot supports Node.js 20 or higher for local tooling and recommends using the current CLI release.","source":{"label":"Install the HubSpot CLI","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/install-the-cli"}},{"claim":"HubSpot's official GitHub Actions setup requires a project on platform version 2025.2 or higher and repository secrets for the HubSpot account ID and personal access key.","source":{"label":"Set up GitHub Actions for HubSpot projects","url":"https://developers.hubspot.com/docs/developer-tooling/third-party-tools/set-up-github-actions"}},{"claim":"The official basic workflow uses `HubSpot/hubspot-project-actions@v1.1.0` and verifies success in both GitHub logs and HubSpot Builds & Deploys.","source":{"label":"Set up GitHub Actions for HubSpot projects","url":"https://developers.hubspot.com/docs/developer-tooling/third-party-tools/set-up-github-actions"}},{"claim":"For config-profile workflows, HubSpot requires the `project-upload@v1.1.0` sub-action with explicit `with` inputs because the basic workflow's environment-variable approach does not propagate correctly with profiles.","source":{"label":"Set up GitHub Actions for HubSpot projects","url":"https://developers.hubspot.com/docs/developer-tooling/third-party-tools/set-up-github-actions"}}],"sections":[{"heading":"CI preflight","body":["Record local and runner Node versions, the locally tested HubSpot CLI version, repository working directory, project path, `platformVersion`, target account, and config profile when used. At the 2026-08-29 live check, HubSpot's installation guide supports Node.js 20 or higher, and the official GitHub Actions guide requires an existing HubSpot project on platform version 2025.2 or higher.","Choose one of two official credential paths; do not mix them. The basic, single-account workflow creates repository secrets named exactly `HUBSPOT_ACCOUNT_ID` and `HUBSPOT_PERSONAL_ACCESS_KEY`, maps them to `DEFAULT_ACCOUNT_ID` and `DEFAULT_PERSONAL_ACCESS_KEY`, and runs `HubSpot/hubspot-project-actions@v1.1.0`. Never put either secret value directly in YAML, source, logs, tickets, or agent prompts.","A config-profile or multi-environment workflow is different. Commit the non-secret `hsprofile.*.json` files, create an account-ID and personal-access-key secret pair for each environment, and use `HubSpot/hubspot-project-actions/project-upload@v1.1.0` with explicit `with` inputs for `profile`, `account_id`, and `personal_access_key`. HubSpot warns that the basic workflow's `env` approach does not propagate correctly when profiles are used.","Place each workflow under `.github/workflows/`, quote branch values such as `\"main\"`, and match each profile, account ID, secret pair, branch, and workflow file deliberately. For the basic action only, optional `DEFAULT_CLI_VERSION` should be a fixed, tested release instead of `latest` or `next` when overriding the predetermined stable default."]},{"heading":"Secrets and logs","body":["Inventory the values CI needs, but do not paste tokens, client secrets, private keys, or account credentials into docs, tickets, or agent prompts. The handoff should say where secrets live, who owns them, and which environment uses them.","Review logs for accidental disclosure. A migration or upload workflow is not ready for client handoff if command output could expose OAuth secrets, tokens, or internal account IDs unnecessarily.","For agencies, separate client-facing evidence from internal build details. The client may need proof of version checks and source verification, not raw secret names or CI internals."]},{"heading":"Expected output and failure recovery","body":["The documented success path is: a push to the configured branch starts the workflow, the HubSpot action validates and uploads the project, the GitHub run completes, and HubSpot Builds & Deploys shows the resulting build. HubSpot attributes action-triggered builds with the commit message and SHA, so record that SHA, build result, deployment result, and the account/environment that received it.","If the workflow does not parse, quote branch values such as `\"main\"`. If profile support is missing, confirm the sub-action is at least `project-upload@v1.1.0`. If a profile targets the wrong account or authentication fails, verify the committed profile's `accountId`, its environment-specific secret pair, the explicit `with` inputs, and `${{ secrets.SECRET_NAME }}` references; do not switch back to the basic `env` pattern. If no run starts, check the branch, `.github/workflows/` path, extension, and whether Actions is disabled.","Triage before retrying: a Node or dependency-install error belongs to runner/toolchain setup; a lint or validation error belongs to project/configuration readiness; a wrong account/profile or project-directory result belongs to targeting; and missing or ambiguous command JSON belongs to observability. In the last case, inspect HubSpot Builds & Deploys and `hs project list-builds` instead of inferring that no build was created from one missing field.","A green GitHub job without a matching HubSpot build is not accepted, and a successful build is not automatically a successful deployment or install. Open `hs project open` or the Projects dashboard, review Builds & Deploys, and run the written install/feature smoke tests before promotion. Keep QA and production accounts on separate branch/profile/secret paths when you adopt HubSpot's multi-environment pattern."]}],"executionContract":null,"checklist":["Require Node.js 20 or higher unless current HubSpot guidance has changed; record runner and local versions.","Record the tested CLI version, project working directory, and `platformVersion`; require 2025.2 or higher for the official action flow.","Record and verify the repository working directory, target account, and config profile separately.","Choose a basic single-account workflow or a config-profile workflow; never combine their credential-passing patterns.","For the basic path, create `HUBSPOT_ACCOUNT_ID` and `HUBSPOT_PERSONAL_ACCESS_KEY` secrets, map them to `DEFAULT_ACCOUNT_ID` and `DEFAULT_PERSONAL_ACCESS_KEY`, and use `HubSpot/hubspot-project-actions@v1.1.0`.","For profiles, commit `hsprofile.*.json`, use an environment-specific account-ID/key secret pair, and pass `profile`, `account_id`, and `personal_access_key` through `HubSpot/hubspot-project-actions/project-upload@v1.1.0` `with` inputs.","Place workflows under `.github/workflows/`, quote branches, and pin a tested `DEFAULT_CLI_VERSION` only for a deliberate basic-action override.","Match the GitHub run and commit SHA to HubSpot Builds & Deploys, then record build, deploy, and smoke-test results.","Exercise the YAML, action-version, secret, branch, and workflow-path recovery checks before escalating."],"officialSources":[{"label":"Install the HubSpot CLI","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/install-the-cli"},{"label":"HubSpot CLI reference","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/reference"},{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"},{"label":"Set up GitHub Actions for HubSpot projects","url":"https://developers.hubspot.com/docs/developer-tooling/third-party-tools/set-up-github-actions"}],"faq":[{"question":"What should CI record before HubSpot CLI uploads?","answer":"Record CLI version, Node version, target account strategy, secret storage, selected command path, and a current source-check date."},{"question":"Should CI logs include HubSpot secrets?","answer":"No. Do not paste tokens, client secrets, private keys, or account credentials into docs, tickets, logs, or agent prompts."},{"question":"How do I prove a HubSpot GitHub Actions deployment succeeded?","answer":"Match the successful GitHub workflow and commit SHA to the build shown in HubSpot Builds & Deploys, then separately record deployment and install or feature smoke-test results."}],"naturalLanguageQuestions":["HubSpot CLI, Node, and CI Preflight Checklist","What should CI record before HubSpot CLI uploads?","Should CI logs include HubSpot secrets?","How do I prove a HubSpot GitHub Actions deployment succeeded?"]},{"title":"Legacy CRM Cards to App Cards: October 31, 2026 Planning","url":"https://projectsappguide.com/hubspot-legacy-crm-cards-to-app-cards","intent":"Plan adjacent app-card modernization deadline.","lastSourceCheck":"2026-08-29","summary":"Classic/legacy CRM cards have a separate October 31, 2026 migration deadline. Build and beta-test the replacement app card before starting the documented card-view migration, because HubSpot says that cutover cannot be stopped or reversed.","answerSnapshot":{"shortAnswer":"Legacy or classic CRM card modernization is a separate app-card workstream and should not be merged with the May/June legacy public app creation sunset.","appliesTo":"Apps using classic or legacy CRM cards that need app-card modernization planning.","verify":"Open HubSpot's current CRM-card migration guide, legacy guide, and deprecation changelog before building or starting replacement.","boundary":"Use October 31, 2026 only for CRM card modernization, and do not begin card-view migration until beta acceptance because the operation cannot be stopped or reversed."},"claims":[{"claim":"Legacy or classic CRM card work has separate official guidance from public app creation.","source":{"label":"Legacy CRM cards guide","url":"https://developers.hubspot.com/docs/api-reference/legacy/crm/extensions/crm-cards/guide"}},{"claim":"The October 31, 2026 date belongs to the classic CRM cards deprecation workstream.","source":{"label":"Classic CRM cards deprecation changelog","url":"https://developers.hubspot.com/changelog/deprecating-support-for-classic-crm-cards"}},{"claim":"HubSpot requires the app to use Projects on platform version 2025.2 or newer and says a started card-view migration cannot be stopped or reversed.","source":{"label":"Migrate a legacy CRM card to an app card","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-legacy-crm-cards-to-app-cards"}},{"claim":"The migration can be observed as `Migration Underway` and accepted only at `Migration Complete`; the API endpoint can be retried with the same body to check progress without duplicating work.","source":{"label":"Migrate a legacy CRM card to an app card","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-legacy-crm-cards-to-app-cards"}}],"sections":[{"heading":"Separate track","body":["The CRM card deadline is about card rendering and app-card modernization, not the May/June legacy public app creation sunset. HubSpot's CRM card sources describe an October 31, 2026 deadline for existing apps with classic or legacy CRM cards to migrate those cards.","Treat CRM cards as a second workstream if your app includes them. A team may need both a Projects CLI migration plan and a card modernization plan, but the evidence, deadlines, and acceptance criteria are different.","Do not tell stakeholders that the public app creation sunset itself is the CRM card migration deadline. Keep the two official notices separate in planning docs, client emails, and Gumroad copy."]},{"heading":"Prerequisites and no-return gate","body":["Before card replacement, require the latest HubSpot CLI, an app already on the Projects framework at platform version 2025.2 or newer, and an isolated developer or configurable test account. Inventory every legacy card, its card ID, CRM object locations, data source, scopes, backend owner, current installs, and the replacement app-card ID.","Treat the cutover approval as a no-return gate. HubSpot's current migration guide says that once card-view migration starts it cannot be stopped or reversed. Require written beta acceptance for data correctness, permissions, actions, empty/error/loading states, and all supported record locations before anyone can start the UI or API migration.","For legacy ticket cards, prepare two replacement app cards with different titles: one at `crm.record.sidebar` and one at `helpdesk.sidebar`. Record both app-card IDs. A single sidebar card does not complete the documented ticket migration requirement."]},{"heading":"Build and beta-test the replacement","body":["Create or convert the replacement app card, add it to the same app, upload the project, install it in the isolated account, and test the new card while the legacy card still exists. Do not use migration itself as the first end-to-end test.","If a migrated Marketplace app has the `hs-release-app-cards` feature flag, use it for limited beta visibility and delete it before the all-user migration. If `hs-hide-crm-cards` is present, delete that flag before migration too. Record flag deletion as a gate rather than assuming the migration UI or API will repair rollout configuration.","The pre-cutover packet should include the legacy and replacement card IDs, platform version, build/deploy result, install set, feature-flag state, beta evidence, ticket-location coverage, owner, maintenance window, and explicit approval acknowledging the irreversible operation."]},{"heading":"Run and observe migration","body":["Start replacement through the Projects UI or the documented migrate-views API only after the gate passes. In the UI, keep the migration panel open or return to it to monitor progress. With the API, preserve the exact request body used for the approved migration so progress checks target the same card mapping.","Accept `Migration Underway: X of X installs still processing...` as an in-progress state, not success. The API processes views asynchronously; HubSpot says the same request body can be sent again to check progress without duplicating work or causing adverse effects. High-install or custom-view apps can take longer and may return extended status information.","During processing, some users can still see the legacy card and some may briefly see both old and new cards. Keep support and monitoring active until the UI or API returns `Migration Complete`; do not delete the legacy card during this mixed state."]},{"heading":"Completion and deletion boundary","body":["Completion requires the exact `Migration Complete` state, confirmation that all customer views were migrated, smoke tests in representative installed accounts, and an incident/support check. Capture the final state, completion time, card IDs, install count, and approver in the handoff.","Because a started migration cannot be reversed, recovery focuses on observation and the already-tested replacement: safely recheck progress with the same API body, investigate extended status, and correct replacement-card behavior through a reviewed build. Do not describe this as rollback.","Delete the unused legacy card only after `Migration Complete` says it has been hidden from all customers and is ready for deletion. Keep the new app card and migration evidence under normal release controls after the deadline work is complete."]}],"executionContract":null,"checklist":["Require the latest CLI and Projects platform version 2025.2 or newer.","Inventory legacy card IDs, replacement app-card IDs, locations, installs, scopes, backend owner, and feature flags.","For ticket cards, create and test separate `crm.record.sidebar` and `helpdesk.sidebar` replacements with different titles.","Upload, install, and beta-test the replacement before cutover; record explicit approval for the irreversible migration.","Delete `hs-release-app-cards` and `hs-hide-crm-cards` before migration when present.","Monitor `Migration Underway`; recheck API progress only with the same approved request body.","Require `Migration Complete` plus representative-account smoke tests before deleting the legacy card."],"officialSources":[{"label":"Legacy CRM cards guide","url":"https://developers.hubspot.com/docs/api-reference/legacy/crm/extensions/crm-cards/guide"},{"label":"Migrate a legacy CRM card to an app card","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-legacy-crm-cards-to-app-cards"},{"label":"Classic CRM cards deprecation changelog","url":"https://developers.hubspot.com/changelog/deprecating-support-for-classic-crm-cards"}],"faq":[{"question":"Is the CRM card deadline part of the May/June public app creation sunset?","answer":"No. CRM card modernization is a separate app-card workstream with its own official sources and planning deadline."},{"question":"What should I inventory for CRM card modernization?","answer":"List each legacy or classic CRM card, object location, data source, UI behavior, scopes, backend owner, and test plan."},{"question":"Can I stop or roll back a CRM card view migration after it starts?","answer":"No. HubSpot's current migration guide says the operation cannot be stopped or reversed. Beta-test the replacement and approve the no-return gate first; after starting, monitor to `Migration Complete` and fix replacement behavior through reviewed builds rather than promising rollback."}],"naturalLanguageQuestions":["Legacy CRM Cards to App Cards: October 31, 2026 Planning","Is the CRM card deadline part of the May/June public app creation sunset?","What should I inventory for CRM card modernization?","Can I stop or roll back a CRM card view migration after it starts?"]},{"title":"HubSpot Marketplace Listing Checklist 2026","url":"https://projectsappguide.com/hubspot-marketplace-listing-checklist-2026","intent":"Prove Marketplace eligibility before submission.","lastSourceCheck":"2026-08-29","summary":"Do not start with listing copy. First prove every current eligibility gate, then complete the seven listing tabs, run validation, resolve every error, and only then submit one app for review.","answerSnapshot":{"shortAnswer":"A Marketplace app is not submission-ready until it clears HubSpot's minimum requirements—including OAuth, one matching public app ID, at least three active unique unaffiliated production installs with activity in the past 30 days, least-privilege scopes, policy gates, supported platform version, and any app-type-specific restrictions—plus complete listing validation.","appliesTo":"Teams preparing a HubSpot public or Marketplace app for review or client handoff.","verify":"Mark every eligibility item PASS/FAIL/UNKNOWN with dated evidence, then use Review info → Run validation and retain the resulting error-free state before submission.","boundary":"`distribution: marketplace`, a valid project, or an error-free listing form does not guarantee HubSpot approval."},"claims":[{"claim":"Marketplace eligibility requires OAuth as the sole authorization method, the listing's public app ID/client ID, and at least three active unique installs in unaffiliated production accounts with successful activity in the past 30 days.","source":{"label":"App Marketplace listing requirements","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/app-marketplace-listing-requirements"}},{"claim":"Other minimum gates include least-privilege scopes, terms and restricted-industry checks, no classic CRM cards, a supported developer-platform version, and special user-permission/MCP Server requirements for AI connectors.","source":{"label":"App Marketplace listing requirements","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/app-marketplace-listing-requirements"}},{"claim":"The listing workflow requires Super admin permission; Review info exposes listing errors and `Run validation` before submission.","source":{"label":"Listing your app","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/listing-your-app"}},{"claim":"Incomplete or inaccurate critical listing information can leave a listing in Draft mode only, and linked pages must be live, public, functional, and crawlable.","source":{"label":"App Marketplace listing requirements","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/app-marketplace-listing-requirements"}}],"sections":[{"heading":"Gate 0: prove eligibility before writing copy","body":["Use a three-state gate: PASS requires dated evidence, FAIL blocks submission, and UNKNOWN blocks this checklist's readiness decision until evidence is collected. UNKNOWN-as-stop is this guide's conservative process rule, not an additional HubSpot policy.","Prove the app is directly accessible, unique, and scoped to one use case; API calls use the same public app ID and OAuth client ID as the listing; OAuth is the sole authorization method; and at least three unique, active installs exist in unaffiliated production accounts. HubSpot defines activity as successful OAuth-authenticated API calls or qualifying signed requests during the past 30 days—not a test-account install count or an unverified dashboard total.","Also prove least-privilege scopes, Technology Partner Program Agreement acceptance, restricted-industry compliance, absence of classic CRM cards, and use of a currently supported developer-platform version. If the app is an AI connector, separately prove user-level permissions and that it is built with HubSpot's MCP Server. Any failed conditional gate is a product/architecture task, not a copy-edit task."]},{"heading":"Gate 1: build a reviewable evidence packet","body":["Make the listing integration-specific, not generic product copy. Prepare a public setup guide specific to the HubSpot integration, a working install-button URL, live support resources, current Terms and Privacy URLs, a scope-to-shared-data matrix, accurate pricing that matches the website, at least one support method, test instructions, contacts, screenshots with alt text, and implemented-feature evidence.","Crawl every submitted URL without authentication and keep each URL within HubSpot's 250-character limit. HubSpot says its SEO tools crawl associated pages and recommends allowing the `HubSpot Crawler` user agent before submission. A 200 response alone is insufficient: the page must be public, functional, current, and semantically match the field it fills.","If the app includes UI-extension app cards, add the card-specific brand, icon, sensitive-data, scope-use, browser-extension, asset-hosting, performance, usability, and accessibility checks from the current requirements page. Do not let a generic Marketplace packet conceal feature-specific gates."]},{"heading":"Gate 2: run the listing validator","body":["HubSpot's current listing guide says the editor must be a Super admin. The wizard contains Listing info, App details, Pricing, App features, Support info, Testing info, and Review info. Complete each tab and make the displayed app, redirect/install URL, shared data, pricing, assets, support details, test steps, and contacts match the evidence packet.","On Review info, expand all errors and use each error link to return to the responsible tab. If `Validate & submit` is gray, check Super admin permission and missing-field counts in tab headings, fill the missing data, then click `Run validation`. Do not interpret a gray control as a transient UI problem and repeatedly retry it.","The pass condition is an error-free validation state captured with app/listing identity, reviewer, timestamp, and source-check date. Submission is a separate state-changing action and should require owner approval after the evidence packet is frozen."]},{"heading":"Submission and recovery boundary","body":["HubSpot says only one app can be submitted at a time; additional apps submitted while the first is being processed are automatically rejected. Queue apps instead of parallel-submitting them. The same requirements page states an initial review target of 10 business days and says the feedback process should take no more than 60 days from feedback, but neither is an approval guarantee.","Different states require different responses: Draft-only means required listing information is incomplete or inaccurate; validation errors route to the named field/tab; rejection or reviewer feedback requires a tracked remediation response; a live listing edit must be resubmitted. Do not collapse these into one generic 'Marketplace failed' state.","Do not promise instant rollback after submission or publication. HubSpot documents a review workflow for edits and says an unpublish request is processed by the Marketplace team within 10 business days. Preserve the last approved listing evidence, but do not represent it as a guaranteed restore button."]}],"executionContract":{"prerequisites":["Eligibility ledger has PASS evidence for access, uniqueness/use-case, matching public app ID/client ID, OAuth-only auth, install threshold, scopes, terms, industry/functionality limits, platform version, and any AI-connector gate.","At least three active unique installs are evidenced as unaffiliated production accounts with successful app activity in the past 30 days—not test accounts or raw lifetime installs.","A Super admin owns the listing; a separate engineering owner owns OAuth/install/feature evidence and a content/legal owner owns public URLs and claims.","All public URLs, setup docs, install flow, shared-data table, pricing, support, privacy, terms, assets, and reviewer test instructions are complete and current."],"steps":[{"action":"In Development → App Listings, choose `Create listing` and select the eligible app.","expected":"The intended app is selectable and the primary listing language can be chosen.","verify":"Match app name, public app ID/client ID, distribution/auth configuration, owner, and listing language to the eligibility ledger.","onFailure":"If Create listing is unavailable or the app is absent, check Super admin access, whether a listing already exists, and whether all existing apps already have listings before changing code.","recoveryBoundary":"Do not create a replacement app to bypass uniqueness, access, or listing-state constraints."},{"action":"Complete all seven tabs: Listing info, App details, Pricing, App features, Support info, Testing info, and Review info.","expected":"Required fields are populated with integration-specific, internally consistent evidence and live URLs.","verify":"Cross-check install URL, scopes/shared data, pricing, support/privacy/terms, setup guide, screenshots/alt text, test instructions, and contacts against the frozen packet.","onFailure":"Route each mismatch to its named owner; do not soften a claim or widen a scope merely to make fields appear complete.","recoveryBoundary":"Saving a draft is not submission, eligibility, approval, or publication."},{"action":"On Review info, expand all errors and click `Run validation` after fixing every required field.","expected":"No unresolved listing errors remain and the submission control is available to the authorized owner.","verify":"Capture the error-free validation state, app/listing identity, reviewer, timestamp, and current-source check date.","onFailure":"Use the error name to return to the responsible tab; if the button is gray, check Super admin permission and missing-field counters before retrying.","recoveryBoundary":"An error-free form still does not prove the external URLs are semantically correct, the app works, or HubSpot will approve it."},{"action":"After owner sign-off, submit one app for review and log all HubSpot feedback.","expected":"The submission enters HubSpot's review workflow and the team has one remediation queue tied to the submitted evidence version.","verify":"Record submission timestamp, submitted app/listing identity, source commit/evidence version, owner, and subsequent review status or email.","onFailure":"Classify the outcome as draft-only, validation error, automatic rejection from parallel submission, reviewer feedback, or rejection; follow the matching route instead of resubmitting blindly.","recoveryBoundary":"Approval is discretionary; editing a live listing requires review, and unpublishing is a processed request rather than an instant rollback."}],"errorRouter":[{"symptom":"Fewer than three qualifying active installs or install evidence is ambiguous.","route":"Reconcile unique unaffiliated production accounts and successful qualifying activity in the past 30 days; exclude test accounts, affiliated accounts, duplicates, and inactive installs.","stopWhen":"Stop submission until three qualifying installs are evidenced; never manufacture activity or count test installs."},{"symptom":"App uses static auth, another app ID/client ID, classic CRM cards, or an unsupported platform version.","route":"Treat as an architecture hard block: correct OAuth/app identity, modernize cards, or upgrade the platform through the applicable official workflow before listing work resumes.","stopWhen":"Stop if the proposed fix changes app identity, existing installs, scopes, or production behavior without a reviewed migration plan."},{"symptom":"AI connector lacks user-level permissions or HubSpot MCP Server architecture.","route":"Route to product/security architecture and the current HubSpot AI-connector requirement; listing copy cannot remediate it.","stopWhen":"Stop submission until the conditional AI-connector gate is either proven not applicable or satisfied."},{"symptom":"Public setup, install, support, terms, privacy, or pricing URL fails review/crawl.","route":"Test unauthenticated access, redirects, freshness, semantic field match, URL length, robots/WAF behavior, and `HubSpot Crawler` allowlisting; retest the exact submitted URL.","stopWhen":"Stop while any required page is private, stale, broken, misleading, or accessible only after sign-in."},{"symptom":"Shared-data table and OAuth scopes disagree.","route":"Map every object scope to data direction and implemented behavior; remove unused scopes or correct the listing and product behavior together.","stopWhen":"Stop before describing read/write data as one-way or requesting scopes the app does not use."},{"symptom":"`Validate & submit` is gray or Review info lists errors.","route":"Verify Super admin permission, inspect missed-field counts in all seven tabs, expand all errors, open each error, correct it, and rerun `Run validation`.","stopWhen":"Stop submission until the validator is error-free and the evidence packet still matches the edited fields."},{"symptom":"Submission is automatically rejected while another app is under review.","route":"Place the app in an internal queue and wait for the active review to finish; do not create duplicate apps or repeatedly resubmit.","stopWhen":"Stop until the one-app-at-a-time constraint is clear and an owner schedules the next submission."}]},"checklist":["Access, uniqueness, and one-use-case gates marked PASS with evidence.","Public app ID and OAuth client ID match the listing and API authorization path.","OAuth is the sole authorization method; scopes are least-privilege and used.","At least three qualifying active unique installs evidenced for the past 30 days.","Terms, restricted-industry, classic-card, and supported-platform gates passed.","AI-connector user-permission and HubSpot MCP Server gate passed or marked not applicable with rationale.","Setup, install, support, Terms, Privacy, and pricing URLs are public, live, current, functional, and under 250 characters.","Shared-data objects and direction match requested OAuth scopes and implemented behavior.","Integration-specific copy, pricing, screenshots/alt text, feature descriptions, test steps, and contacts are complete.","App-card-specific brand, sensitive-data, extension, asset, performance, usability, and accessibility gates checked when applicable.","Super admin ownership confirmed and all seven tabs completed.","Review info expanded; every error resolved; `Run validation` passes.","Only one app is queued for HubSpot review at a time.","Submission evidence version, timestamp, owner, and feedback route recorded."],"officialSources":[{"label":"App Marketplace listing requirements","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/app-marketplace-listing-requirements"},{"label":"Listing your app","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/listing-your-app"},{"label":"App configuration","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/app-configuration"}],"faq":[{"question":"What are the Marketplace eligibility hard stops before listing work?","answer":"Stop for any failed or unknown access, uniqueness/use-case, matching app ID/client ID, OAuth-only, three-active-install, least-scope, terms, restricted-industry/functionality, supported-platform, or applicable AI-connector gate. This guide treats UNKNOWN as not ready until evidence exists."},{"question":"Do three developer test-account installs satisfy the install gate?","answer":"No. HubSpot defines qualifying active installs as unique production accounts unaffiliated with your organization that show successful qualifying app activity in the past 30 days."},{"question":"What should I do when Validate & submit is grayed out?","answer":"Confirm the editor is a Super admin, inspect missing-field counts on every tab, expand all Review info errors, fix each linked field, and click Run validation again. Do not submit or create a replacement app until the cause is known."},{"question":"Does error-free listing validation guarantee approval or provide instant rollback?","answer":"No. HubSpot manually reviews submissions and may reject or unpublish listings. Live listing edits require resubmission, and documented unpublish requests are processed rather than acting as an instant rollback switch."}],"naturalLanguageQuestions":["HubSpot Marketplace Listing Checklist 2026","What are the Marketplace eligibility hard stops before listing work?","Do three developer test-account installs satisfy the install gate?","What should I do when Validate & submit is grayed out?","Does error-free listing validation guarantee approval or provide instant rollback?"]},{"title":"HubSpot hs project upload Checklist","url":"https://projectsappguide.com/hubspot-project-upload-checklist","intent":"Prepare a safer project upload.","lastSourceCheck":"2026-08-29","summary":"`hs project upload` uploads a HubSpot project and creates a build. Teams should verify account targeting, auto-deploy behavior, UID stability, auth configuration, and Marketplace implications before using it for meaningful changes.","answerSnapshot":{"shortAnswer":"`hs project upload` uploads the current project to HubSpot and creates a build; if auto-deploy is enabled, a successful build may deploy automatically.","appliesTo":"Developers moving a Projects-based HubSpot app from local work toward a sandbox, test account, or main account upload.","verify":"Open the current HubSpot CLI project commands docs and create-app docs before uploading to a production-affecting account.","boundary":"This checklist does not guarantee a successful build, deployment, install flow, or Marketplace review."},"claims":[{"claim":"`hs project upload` uploads a project to HubSpot and creates a build.","source":{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"}},{"claim":"A project configured to auto-deploy can deploy automatically after a successful build, and new projects are documented as auto-deploy by default.","source":{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"}},{"claim":"Changing component UIDs after upload can cause HubSpot to recognize a component as different from previous builds.","source":{"label":"Create a new app using the CLI","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"}},{"claim":"`hs project validate` checks `app-hsmeta.json` upload readiness, while `hs project list-builds` and `hs project open` expose build history and project state.","source":{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"}}],"sections":[{"heading":"Before you upload","body":["Treat `hs project upload` as a change-management moment, not a casual sync command. The official project commands docs describe it as uploading a project to HubSpot and creating a build, with auto-deploy behavior depending on project settings. That means the checklist should start with the target account, the current project state, and whether a successful build can become a deployed change.","Run from the intended project root: record the working directory and confirm its top-level `hsproject.json` names the project you intend to upload. If the command cannot resolve a project, fix the directory or project structure rather than retrying from an arbitrary parent folder.","Confirm which account name in `~/.hscli/config.yml` is intended for the upload. HubSpot documents `--account=accountName` for targeting a specific account, including workflows that move from sandbox to main account. For agency work, make the account name explicit in the handoff so a developer is not relying on whichever account was last authenticated in a terminal.","If the team uses config profiles, record both the requested profile and the account it is expected to select. After upload, verify the actual project/account through build history and `hs project info --json`; do not assume that a syntactically accepted profile or account argument reached the intended environment.","Inspect `hsproject.json`, `app-hsmeta.json`, and feature configuration before upload. If you changed OAuth settings, redirect URLs, scopes, app cards, settings pages, or other JSON configuration, record exactly what changed and why. Keep UID changes especially visible because the create-app docs warn that changed UIDs can make the platform treat a component as different from previous builds."]},{"heading":"Upload vs deploy","body":["The most important SEO answer for searchers is simple: upload and deploy are related but not identical. `hs project upload` creates a build. If the project is configured to auto-deploy, that successful build can deploy automatically; if it is not, a manual deploy step may be needed. Always check current project settings and current docs before giving a stakeholder a go-live expectation.","For a sandbox-to-main workflow, use a written release note even if the code change is small. Include the command planned, account target, expected build behavior, rollback owner, and what to test after upload. This is especially useful when an AI agent or junior developer is preparing the command but a senior developer owns the account consequence.","Do not describe this guide as a deployment guarantee. A clean local project and a correct command can still fail because of account permissions, app configuration, platform validation, missing backend OAuth configuration, Marketplace requirements, or changes in HubSpot documentation after this source-check date."]},{"heading":"Production-minded checklist","body":["A useful pre-upload packet contains: source-check date, CLI version, target account, project directory, changed files, expected auth mode, redirect URLs, scopes, UID changes, auto-deploy setting, test plan, and owner. That packet is small enough to paste into a pull request, issue, or client delivery note.","For public or Marketplace apps, connect upload readiness to install-flow readiness. HubSpot's create-app docs describe post-upload work around installation and OAuth app credentials. If your backend OAuth server still lacks the correct client ID or client secret, an uploaded project is not the same as a tested app.","After upload, capture build result, deploy result if applicable, app install result, and any manual follow-up. Those notes help the next developer distinguish a command failure from an auth failure, a Marketplace readiness gap, or an unsupported assumption."]},{"heading":"Validate, observe, and recover","body":["Run `hs project validate` before upload and resolve every reported `app-hsmeta.json` readiness problem. After upload, run `hs project list-builds --limit 5` and use `hs project open` to confirm the new build ID, status, auto-deploy outcome, and target account. `hs project info --json` can provide machine-readable project and component metadata when a handoff or CI check needs it.","Split failures by layer. Validation failure means repair configuration and do not upload. Build failure means inspect Builds & Deploys and the reported source error before creating another build. A successful build with a failed install belongs in the OAuth, scope, permission, or static-auth path. For runtime or authorization behavior in an installed app, use the current `hs app logs` filters such as `--errors-only` and `--since 1h`; `hs project logs` is specifically for a project's function logs.","Do not use `--force` as generic recovery; HubSpot documents it as bypassing warnings for destructive actions. If auto-deploy is off, `hs project deploy --build <verified-build-id>` can deploy a specific successful build. If a deployed change regresses, first confirm an earlier known-good build ID and its compatibility in Builds & Deploys, assign the rollback owner, and only then use the documented specific-build deploy path. A previous build is not automatically safe for changed auth, data, or Marketplace state."]}],"executionContract":null,"checklist":["Record `hs --version` and source-check date.","Run from the intended project root and verify its top-level `hsproject.json` before upload.","Confirm the intended HubSpot account and use `--account=accountName` when appropriate.","When using a config profile, record the profile-to-account mapping and verify the actual target after upload.","Check whether the project is configured for auto-deploy.","Review changed JSON configuration files before upload.","Flag UID changes before upload.","Confirm OAuth redirect URLs, scopes, and backend credential readiness when applicable.","Run `hs project validate` and resolve findings before upload.","Write the post-upload test plan before running the command.","After upload, capture `hs project list-builds --limit 5`, `hs project open`, build ID, deploy state, and target account.","Route build, install/auth, and runtime/log failures separately; do not use `--force` as a generic retry.","Before a specific-build recovery deploy, verify the earlier successful build ID, compatibility, and rollback owner."],"officialSources":[{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"},{"label":"Create a new app using the CLI","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"},{"label":"App Marketplace listing requirements","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/app-marketplace-listing-requirements"}],"faq":[{"question":"Does hs project upload deploy automatically?","answer":"It can, depending on project auto-deploy settings. HubSpot's project command docs say an auto-deploy project deploys after a successful build, and new projects are documented as auto-deploy by default."},{"question":"How do I avoid uploading to the wrong HubSpot account?","answer":"Record the intended account before upload and review HubSpot's documented `--account=accountName` option for targeting a specific account from your CLI config."},{"question":"Should I change UIDs before upload?","answer":"Only with deliberate review. HubSpot's create-app docs note that changing a UID after upload may make the platform recognize the component as different from previous builds."}],"naturalLanguageQuestions":["HubSpot hs project upload Checklist","Does hs project upload deploy automatically?","How do I avoid uploading to the wrong HubSpot account?","Should I change UIDs before upload?"]},{"title":"HubSpot hs project dev Local Development Guide","url":"https://projectsappguide.com/hubspot-project-dev-local-development","intent":"Use local development without overtrusting it.","lastSourceCheck":"2026-08-29","summary":"`hs project dev` starts a local development server for supported HubSpot project extension work. It can refresh supported JSX UI changes, but JSON config changes still need manual upload.","answerSnapshot":{"shortAnswer":"`hs project dev` starts a local development server; supported JSX changes can refresh in the browser, while `.json` config changes need `hs project upload`.","appliesTo":"Developers building or testing HubSpot app cards, settings pages, and other Projects-based app work locally.","verify":"Open the current HubSpot project commands docs and create-app docs before relying on local development behavior.","boundary":"Local development preview is not production validation, Marketplace approval, or proof that all app configuration is uploaded."},"claims":[{"claim":"`hs project dev` starts a local development server for project work.","source":{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"}},{"claim":"Supported JSX changes for app cards or settings pages can refresh while the server is running.","source":{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"}},{"claim":"Changes to `.json` configuration files need manual upload with `hs project upload`.","source":{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"}}],"sections":[{"heading":"What hs project dev is for","body":["`hs project dev` is best understood as a local development loop for supported Projects app work. The project commands docs describe it as starting a local development server, and they call out supported browser refresh behavior for JSX changes when developing app cards or settings pages with UI components.","That makes it useful for fast iteration on interactive UI surfaces, copy tweaks, component behavior, and developer feedback loops. It is less useful as a final source of truth for account configuration, OAuth readiness, Marketplace listing quality, or build/deploy behavior.","Before starting local development, install or test the app according to the current create-app flow, confirm the target account, and write down which feature you are testing. A clear test scope keeps local dev from turning into a vague green light."]},{"heading":"What does not update automatically","body":["The official project commands docs make a critical distinction: changes to `.json` config files are not included in the local refresh behavior and need to be manually uploaded with `hs project upload`. This affects planning because many important app decisions live in configuration rather than JSX.","If you change `app-hsmeta.json`, feature schema, auth configuration, scopes, redirect URLs, or other JSON-driven configuration, add a separate upload and verification step. Do not tell a client or product owner that local dev has validated those changes just because a UI surface refreshed in the browser.","A clean workflow separates local UI confidence from project configuration confidence. Use `hs project dev` for the former, then use upload/build/install checks for the latter."]},{"heading":"QA workflow for teams","body":["For team handoff, create a short local-dev note: command used, target account, feature tested, files changed, browser behavior observed, JSON config changed or not changed, and next upload required or not required. That note gives a reviewer enough context to understand what was actually proven.","If browser permissions, local network settings, or enterprise device policies interfere with the local development server, document the environment rather than turning the issue into a platform claim. Browser behavior changes over time, so the official docs and the local machine state should both be checked.","For AI-assisted development, paste the local-dev note into the agent prompt and ask for separate next steps for JSX/UI issues, JSON config upload, OAuth install checks, and Marketplace readiness. This mirrors the source boundary and reduces overconfident output."]}],"executionContract":null,"checklist":["Confirm the app is installed or testable in the intended account.","Run local development from the correct HubSpot project directory.","Separate JSX/UI changes from `.json` configuration changes.","Use `hs project upload` for configuration changes that need to reach HubSpot.","Record browser, account, feature, and files tested in the handoff.","Do not treat local dev as Marketplace or production approval."],"officialSources":[{"label":"HubSpot CLI project commands","url":"https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands"},{"label":"Create a new app using the CLI","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"}],"faq":[{"question":"What changes refresh in hs project dev?","answer":"HubSpot's project command docs call out supported JSX changes for app cards or settings pages using UI components while the local development server is running."},{"question":"Do JSON config files update automatically in local development?","answer":"No. The project command docs state that `.json` config file changes need to be manually uploaded using `hs project upload`."},{"question":"Is hs project watch still the recommended local loop?","answer":"The archived HubSpot project commands docs mark `hs project watch` as deprecated in favor of `hs project dev`; verify the current docs before using older workflows."}],"naturalLanguageQuestions":["HubSpot hs project dev Local Development Guide","What changes refresh in hs project dev?","Do JSON config files update automatically in local development?","Is hs project watch still the recommended local loop?"]},{"title":"HubSpot OAuth Redirect URL and Scopes Checklist","url":"https://projectsappguide.com/hubspot-oauth-redirect-scopes-install-checklist","intent":"Prepare OAuth and install-flow review.","lastSourceCheck":"2026-08-29","summary":"For multi-account and Marketplace-oriented HubSpot apps, review OAuth redirect URLs, requested scopes, backend credentials, install testing, and shared-data claims before submission or client handoff.","answerSnapshot":{"shortAnswer":"For multi-account or Marketplace HubSpot apps, OAuth redirect URLs, scopes, backend credentials, and install testing should be reviewed together before listing or production handoff.","appliesTo":"Developers preparing public, Marketplace, or multi-account HubSpot apps on the Projects developer platform.","verify":"Open the current create-app docs and Marketplace listing requirements before finalizing OAuth configuration or listing copy.","boundary":"This checklist does not guarantee OAuth install success, Marketplace approval, or policy compliance."},"claims":[{"claim":"OAuth redirect URLs are configured in `app-hsmeta.json` for OAuth app setup.","source":{"label":"Create a new app using the CLI","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"}},{"claim":"For static auth in a privately distributed app, HubSpot's create-app docs say to remove the `redirectUrls` sub-property.","source":{"label":"Create a new app using the CLI","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"}},{"claim":"Marketplace apps must use OAuth and should only request scopes the app needs.","source":{"label":"App Marketplace listing requirements","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/app-marketplace-listing-requirements"}}],"sections":[{"heading":"OAuth configuration checklist","body":["Start by deciding whether the app is truly OAuth-based. HubSpot's create-app docs distinguish OAuth from static authentication, and the Marketplace requirements add an important boundary for Marketplace apps: OAuth is required and scopes should be limited to what the app needs.","For OAuth apps, inspect `app-hsmeta.json` for redirect URLs and auth configuration before upload. Redirect URLs should match the backend OAuth server and the environment being tested. If a URL points to local development, staging, or production, label that clearly so a reviewer does not confuse a test callback with a final callback.","For privately distributed static-auth apps, do not keep OAuth assumptions in the handoff. The create-app docs state that if static authentication is chosen for a privately distributed app, the `redirectUrls` sub-property should be removed from the `auth` field. That is a concrete source-linked distinction worth exposing in any agent prompt."]},{"heading":"Scopes and shared data","body":["Scopes are not just technical fields. They shape install consent, Marketplace review, and user trust. HubSpot's Marketplace requirements say to request only scopes the app needs, and they connect shared-data information to the scopes requested by the app.","Build a scope table with four columns: requested scope, app feature that uses it, read/write behavior, and where the user-facing listing explains the data flow. If a requested scope has no implemented feature or no listing explanation, either remove it or document why it is conditional or optional according to current requirements.","Avoid vague phrases such as 'full CRM access' unless the app truly needs and explains that scope pattern. The safer long-tail SEO answer is: make scopes least-privilege, implemented, and reflected in listing/shared-data claims."]},{"heading":"Install testing before handoff","body":["After upload, OAuth apps need backend credentials and an install flow that can be tested. The create-app docs describe configuring client ID and client secret in the backend OAuth server after project upload for OAuth apps. If that step is missing, the project can exist in HubSpot while the install flow is still incomplete.","Test the install in the right account type and record the result. A good install note includes redirect URL used, scopes displayed, account installed into, backend environment, success/failure result, and any error text. That note is valuable for debugging and for Marketplace readiness reviews.","Keep Marketplace submission separate from install success. A working install flow is necessary work, but Marketplace review also evaluates listing materials, policies, support, shared data, and other requirements. This guide is designed to organize the work, not certify the outcome."]}],"executionContract":null,"checklist":["Classify auth as OAuth or static auth before editing `app-hsmeta.json`.","For OAuth, verify redirect URLs against the backend environment.","For static auth private apps, remove OAuth redirect URL assumptions from the handoff.","Map every requested scope to an implemented feature.","Check Marketplace shared-data language against requested scopes.","Configure backend OAuth credentials after upload when applicable.","Record install test account, redirect URL, scopes, and result."],"officialSources":[{"label":"Create a new app using the CLI","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"},{"label":"App Marketplace listing requirements","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/app-marketplace-listing-requirements"},{"label":"Listing your app","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/listing-your-app"}],"faq":[{"question":"When do I need OAuth instead of static auth?","answer":"Marketplace apps must use OAuth according to HubSpot's Marketplace requirements. Static auth is a separate option for privately distributed app cases and should be checked against the current create-app docs."},{"question":"Where should OAuth redirect URLs be configured?","answer":"HubSpot's create-app docs show redirect URLs inside the `auth` configuration of `app-hsmeta.json` for OAuth app setup."},{"question":"Should scopes match listing and shared-data claims?","answer":"Yes. Marketplace requirements connect requested scopes with shared-data accuracy, so requested scopes should match implemented behavior and user-facing data-flow claims."}],"naturalLanguageQuestions":["HubSpot OAuth Redirect URL and Scopes Checklist","When do I need OAuth instead of static auth?","Where should OAuth redirect URLs be configured?","Should scopes match listing and shared-data claims?"]}]}