HubSpot Upgrade & Migration

Overview

Guide for upgrading @hubspot/api-client SDK versions and migrating from legacy HubSpot APIs to the current CRM v3 API.

Prerequisites

Current @hubspot/api-client installed
Git for version control
Test suite available
Staging environment for validation

Instructions

Step 1: Check Current Version and Available Updates

# Current version
npm list @hubspot/api-client

# Latest available
npm view @hubspot/api-client version

# See changelog
npm view @hubspot/api-client versions --json | tail -10

Step 2: Review Breaking Changes

Key breaking changes in @hubspot/api-client:

Version	Breaking Change	Migration
v11 -> v12	Association APIs moved to v4 namespace	`client.crm.associations.v4.basicApi`
v10 -> v11	Batch API input format changed	Wrap inputs in `{ inputs: [...] }`
v9 -> v10	`apiKey` auth removed (API keys deprecated)	Use `accessToken` only
v8 -> v9	TypeScript strict types on all methods	Update type imports

Step 3: Create Upgrade Branch and Update

git checkout -b chore/upgrade-hubspot-api-client
npm install @hubspot/api-client@latest
npm test

Step 4: Common Migration Patterns

API Key to Access Token (v9 -> v10+)

// BEFORE (deprecated -- API keys removed in v10)
const client = new hubspot.Client({ apiKey: 'your-api-key' });

// AFTER (use private app access token)
const client = new hubspot.Client({
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN!,
});

Associations v3 to v4 (v11 -> v12+)

// BEFORE (v3 associations)
await client.crm.contacts.associationsApi.create(
  contactId, 'companies', companyId, 'contact_to_company'
);

// AFTER (v4 associations)
await client.crm.associations.v4.basicApi.create(
  'contacts', contactId, 'companies', companyId,
  [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 1 }]
);

Legacy Contact API to CRM v3

// BEFORE (legacy /contacts/v1/)
const response = await fetch(
  `https://api.hubapi.com/contacts/v1/contact/email/${email}/profile`,
  { headers: { Authorization: `Bearer ${token}` } }
);

// AFTER (CRM v3 search)
const result = await client.crm.contacts.searchApi.doSearch({
  filterGroups: [{
    filters: [{ propertyName: 'email', operator: 'EQ', value: email }],
  }],
  properties: ['firstname', 'lastname', 'email'],
  limit: 1,
  after: 0,
  sorts: [],
});
const contact = result.results[0];

Legacy Deals API to CRM v3

// BEFORE (legacy /deals/v1/)
const response = await fetch(
  `https://api.hubapi.com/deals/v1/deal/${dealId}`,
  { headers: { Authorization: `Bearer ${token}` } }
);

// AFTER (CRM v3)
const deal = await client.crm.deals.basicApi.getById(
  dealId,
  ['dealname', 'amount', 'dealstage', 'pipeline', 'closedate']
);

Step 5: Validate and Deploy

# Run full test suite
npm test

# Run integration tests against test account
HUBSPOT_TEST=true npm run test:integration

# If tests pass, merge
git add package.json package-lock.json src/
git commit -m "chore: upgrade @hubspot/api-client to vX.Y.Z"

Output

Updated SDK version in package.json
Migrated breaking changes (auth, associations, types)
All tests passing
Documented rollback procedure

Error Handling

Issue	Cause	Solution
`apiKey is not a valid option`	SDK v10+ removed API keys	Switch to `accessToken`
`associationsApi is not a function`	Associations moved to v4	Use `associations.v4.basicApi`
Type errors after upgrade	Stricter TypeScript types	Update imports from `lib/codegen/crm/`
`Cannot find module`	SDK restructured exports	Check the npm package README for new imports

Examples

Rollback Procedure

# If upgrade causes issues
npm install @hubspot/api-client@PREVIOUS_VERSION --save-exact
npm test
git commit -am "revert: rollback @hubspot/api-client to vPREVIOUS"

Check for Deprecated API Usage

# Search for legacy API endpoints in codebase
grep -rn "contacts/v1\|deals/v1\|companies/v2\|engagements/v1" src/
grep -rn "apiKey:" src/  # deprecated auth method
grep -rn "associationsApi\." src/  # may need v4 migration

Resources

Next Steps

For CI integration during upgrades, see hubspot-ci-integration.

hubspot-upgrade-migration