Your card renders.
Does the action work?

1. Plan around customer visibility

HubSpot removes legacy CRM cards from customer views on October 31, 2026. The migration APIs and UI remain available until December 1, 2026. For uninterrupted access, finish the customer-view replacement before the October cutoff. Official migration timeline.

Pick a beta date with room to inspect backend logs and fix one failed acceptance cycle. Record separate milestones for the replacement build, installed-card acceptance, and customer-view migration.

2. Watch one query parameter swallow another

In the converter version we inspected, the data-fetch helper appends a question mark before its context parameters. An existing query changes the outcome:

Target:   /card?tenant=alpha
Context:  userId=7&portalId=42
Combined: /card?tenant=alpha?userId=7&portalId=42

Backend sees:
  tenant   → "alpha?userId=7"
  portalId → "42"
  userId   → absent

A tenant-based lookup can now fail even though the URL is syntactically valid. A fragment introduces another case: appended text after # belongs to the fragment, outside the HTTP query.

Enable JavaScript to run the local comparison.

Enable JavaScript to run the local comparison.

Our PR #125 builds a URL and appends each context entry through searchParams. Eight added cases cover existing queries, empty queries, fragments, and the URL passed to the mocked SDK; the submitted suite passed all 256 tests. The PR is open as of this article’s date.

The playground models that URL-building boundary. Its small executable module and seven local tests are MIT-licensed. Run node --test url-model.test.mjs with both files in one directory. For an installed card, also inspect the request received by your backend after HubSpot adds its metadata.

Keep duplicate parameter names visible. The proposed change preserves existing entries and appends new ones. If your target already defines portalId or another context name, agree which values your backend accepts and add that case to your contract tests.

3. Follow the action into the business state

The converter sends POST, PUT, and PATCH action bodies as JSON. Classic cards used form-encoded bodies. During coexistence, support both formats and check that each reaches the same validated business operation. Converter backend instructions.

Here is a useful acceptance matrix for a hypothetical “create report” action. Substitute your own required fields and persistent result:

Those are suggested checks for your application. The executed result in this guide is the converter URL regression.

hubspot.fetch() routes through HubSpot’s fetch service, adds identity metadata, and signs requests. It may retry once for connection trouble or a 5XX response within the timeout window. That makes a lost-response case particularly useful for actions with side effects. Validate signatures against the received request and test the backend’s duplicate-handling policy. Fetch metadata and limits.

Local proxy development has its own request-signing setup. Use a deployed test installation to inspect the platform-mediated path as part of acceptance. Local proxy signature behavior.

4. Ten checks before the view swap

1. Inventory the app. Confirm Projects 2025.2+; map each legacy ID to its replacement.
2. Freeze a baseline. Save the definition, representative data response, and one action’s intended effect.
3. Exercise existing queries. Check the data URL with tenant/routing parameters and a fragment case.
4. Accept both action formats. Run legacy form and replacement JSON through the same business assertions.
5. Require business identifiers. Exercise missing properties and two distinct records.
6. Inspect the received request. Check signing, platform metadata, and duplicate policy in the test backend.
7. Check URL permissions. Include data and action endpoints in permittedUrls.fetch; configure iframe URLs where used.
8. Cover ticket locations. Ticket replacements need distinct CRM-sidebar and Helpdesk-sidebar cards, with separate titles and IDs.
9. Run a beta. Verify read, write, refresh, and error paths. Remove hs-release-app-cards and, if used, hs-hide-crm-cards before migration.
10. Finish the customer-view change. Start the one-way view swap after acceptance; follow its asynchronous progress through completion.

Platform steps follow HubSpot’s migration guide and converter setup. The baseline and business assertions are our recommended release practice.

5. Leave the next person one small packet

Keep the code patch, executable contract checks, card-ID/location map, beta observations, and view-migration result together. Assign an owner to the production action and to the view swap. This gives the release reviewer a clear route from an old card to a working replacement.

For a link-only company card, our MIT reference implementation passes viewer and company context into a report URL and includes nine SDK-renderer checks.