Credits

Credits are used for enrichment operations. All other API operations (search, lists, etc.) are free.

What Uses Credits

Operation	Credits
Business enrichment	1 per business
Search	Free
Maps extraction	Free
List management	Free
View contacts	Free

Already-enriched businesses are free

If you try to enrich a business that's already been enriched in your workspace, it won't consume additional credits. The API skips duplicates automatically.

Checking Your Balance

Use the /api/v1/credits endpoint to check your current balance and usage:

Request

GET /api/v1/credits

Response

{
  "data": {
    "credits": {
      "balance": 850
    },
    "usage": {
      "period_start": "2024-01-01T00:00:00Z",
      "api_requests": 1240,
      "searches": 380,
      "enrichments": 150
    },
    "plan": {
      "name": "Growth",
      "credits": 1000
    }
  }
}

Credits in Response Headers

Every API response includes an X-Credits-Remaining header so you can monitor your balance without making extra requests:

text

HTTP/1.1 200 OK
Content-Type: application/json
X-Credits-Remaining: 850
X-RateLimit-Remaining: 58

Insufficient Credits

If you try to enrich more businesses than your credit balance allows, you'll receive a 402 Payment Required response:

json

{
  "error": "insufficient_credits",
  "message": "Not enough credits. Required: 50, Available: 25"
}

Handling Credit Checks

Here's a pattern for checking credits before enrichment:

javascript

400">"text-purple-400">async 400">"text-purple-400">function enrichWithCreditCheck(businessIds) {
  // First, check available credits
  400">"text-purple-400">const creditsRes = 400">"text-purple-400">await fetch(400">'https://localstitch.co/api/v1/credits', {
    headers: { 400">'Authorization': 400">`Bearer ${API_KEY}` }
  });
  400">"text-purple-400">const { data } = 400">"text-purple-400">await creditsRes.json();
  
  400">"text-purple-400">const required = businessIds.length;
  400">"text-purple-400">const available = data.credits.balance;
  
  400">"text-purple-400">if (required > available) {
    console.error(400">`Need ${required} credits, only have ${available}`);
    400">"text-purple-400">return null;
  }
  
  // Proceed with enrichment
  400">"text-purple-400">const enrichRes = 400">"text-purple-400">await fetch(400">'https://localstitch.co/api/v1/enrich', {
    method: 400">'POST',
    headers: {
      400">'Authorization': 400">`Bearer ${API_KEY}`,
      400">'Content-Type': 400">'application/json'
    },
    body: JSON.stringify({ business_ids: businessIds })
  });
  
  400">"text-purple-400">return enrichRes.json();
}

Credit Lifecycle

Allocation

Credits are allocated based on your plan at the start of each billing period.

Usage

Credits are deducted when enrichment completes successfully.

Rollover

Unused credits do not roll over to the next billing period.

Getting More Credits

If you need more credits:

→

Upgrade your plan for higher monthly allocations

→

Purchase additional credits in your workspace settings

PreviousError Handling

NextMCP Integration