Legacy CRM Cards to App Cards: October 31, 2026 Planning

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.

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.

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.

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.

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.