clay-upgrade-migration

Clay Upgrade & Migration

Overview

Guide for navigating Clay plan upgrades and the March 2026 pricing overhaul. Clay restructured from Starter/Explorer/Pro to Launch/Growth tiers, split credits into Data Credits + Actions, and cut data costs 50-90%. This skill covers migration decisions, integration impact, and adaptation strategies.

Prerequisites

• Active Clay account
• Understanding of current credit consumption
• Access to Clay billing dashboard

Instructions

Step 1: Understand the 2026 Pricing Change

Old Plans (Legacy -- available until April 10, 2026):

Plan	Price	Credits	Key Limits
Starter	$149/mo	Limited	No HTTP API, no webhooks
Explorer	$349/mo	25K	400 records/hour throttle
Pro	$800/mo	50K	HTTP API, webhooks, priority support

New Plans (March 2026+):

Plan	Price	Data Credits	Actions	Key Features
Launch	$185/mo	2,500	15,000	Phone enrichment, signal tracking
Growth	$495/mo	6,000	40,000	CRM sync, HTTP API, web intent, ads

Key changes:

• Credits split into Data Credits (buying enrichment data) and Actions (using the platform)
• Data costs cut 50-90% (each enrichment is cheaper)
• No enrichment charges on failed lookups (no data = no charge)
• Credit rollover capped at 2x monthly limit

Step 2: Audit Your Current Usage

# Check current plan and credit usage from Clay dashboard
# Navigate to Settings > Plans & Billing
# Record:
# - Current plan tier
# - Monthly credits used (average over 3 months)
# - Which enrichment providers consume most credits
# - Whether you use HTTP API columns
# - Whether you use webhook sources

Decision matrix for migration:

If you currently...	Recommended new plan
Use < 2,500 data credits/mo	Launch ($185)
Need HTTP API columns	Growth ($495)
Need CRM sync	Growth ($495)
Use webhooks + high volume	Growth ($495)
Stay on legacy Explorer	Keep legacy if 400/hr limit works
Have Enterprise contract	Contact Clay sales

Step 3: Adapt Integration Code for New Credit Model

// src/clay/credit-tracker.ts — track new split credit model
interface CreditUsage {
  dataCredits: { used: number; limit: number; rolloverMax: number };
  actions: { used: number; limit: number };
}

class CreditTracker {
  private usage: CreditUsage;

  constructor(plan: 'launch' | 'growth') {
    this.usage = plan === 'launch'
      ? { dataCredits: { used: 0, limit: 2500, rolloverMax: 5000 }, actions: { used: 0, limit: 15000 } }
      : { dataCredits: { used: 0, limit: 6000, rolloverMax: 12000 }, actions: { used: 0, limit: 40000 } };
  }

  recordEnrichment(dataCreditsUsed: number) {
    this.usage.dataCredits.used += dataCreditsUsed;
    this.usage.actions.used += 1; // Each enrichment = 1 action

    if (this.usage.dataCredits.used > this.usage.dataCredits.limit * 0.8) {
      console.warn(`Data credits at ${((this.usage.dataCredits.used / this.usage.dataCredits.limit) * 100).toFixed(0)}% of monthly limit`);
    }
  }

  canAfford(estimatedCredits: number): boolean {
    return (
      this.usage.dataCredits.used + estimatedCredits <= this.usage.dataCredits.limit &&
      this.usage.actions.used + 1 <= this.usage.actions.limit
    );
  }
}

Step 4: Optimize for the New Model

No-charge on failed lookups changes the cost equation:

// Old model: every enrichment attempt cost credits, even if no data returned
// New model: only charged when data is actually returned

// This makes wider waterfall enrichments cheaper:
// Before: 5-provider waterfall = 5 charges even if only 1 finds data
// After: 5-provider waterfall = 1 charge if only 1 finds data
// Strategy: wider waterfalls are now more cost-effective

Connect your own API keys for maximum savings:

Provider	Clay Credits (managed)	Own Key
Apollo	2 data credits	0 credits
Clearbit	2-5 data credits	0 credits
Hunter	2 data credits	0 credits
ZoomInfo	5-13 data credits	0 credits

Step 5: Migrate Webhook Integrations

If moving from a plan without webhooks to one with them (or vice versa):

# Test webhook availability on new plan
curl -X POST "$CLAY_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"migration_test": true, "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}'

# Verify HTTP API columns still work after plan change
# HTTP API columns are only available on Growth plan

Error Handling

Issue	Cause	Solution
Features disappeared	Downgraded plan	Check feature availability per tier
HTTP API columns disabled	Moved to Launch (no HTTP API)	Upgrade to Growth or use webhooks only
Higher credit usage than expected	Actions now counted separately	Monitor both Data Credits and Actions
Webhook stopped working	Plan change affected access	Verify webhook feature on current plan

Resources

• Clay Pricing Change 2026
• Clay Plans & Billing
• Clay Community -- Pricing Discussion

Next Steps

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