hubspot-upgrade-migration

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

• @hubspot/api-client Changelog
• HubSpot API Changelog
• CRM v3 Migration Guide

Next Steps

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