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):

New Plans (March 2026+):

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:

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:

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

Output

Create a migration receipt with source and target plan/features, affected tables and integrations, projected and observed credit use, staging evidence, production approval, and rollback result. Pricing or feature documentation is not a deployment guarantee; retain the old working configuration until the new path is proven against the intended workspace.

Examples

Test a plan-related webhook change against a staging table with a synthetic row, confirm authentication, idempotency, and downstream delivery, then compare credit consumption to the documented baseline. If a required feature is absent or a callback fails, restore the former integration and delay the cutover rather than attempting a live workaround.

Resources

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

Next Steps

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