Credits & Subscription - SMB Sales Boost API

All paid plans (Starter, Growth, Scale, Platinum, and Enterprise) use a credit-based system where each new lead queried or exported costs 1 credit. Charging is sticky: a lead you have already received through any channel (dashboard, API, MCP or email schedule) is never charged again, even if its data changed later, and a new lead that shares a primary phone or primary email with a lead you already received is also free. Lead searches and exports are always capped at your spendable balance (credit balance plus any overage-budget headroom) instead of failing, with the X-Credits-Capped: true header when the balance was the limit; for them, 402 insufficient_credits only happens if a concurrent request spends the balance between the check and the charge. Pushing a database lead to an integration (POST /api/v1/integrations/:id/push-lead with a leadId, or the MCP tool push_lead_to_integration) is not capped; the same sticky rules apply. A lead you already received is free, even at a 0 balance. A new lead costs 1 credit, taken from your balance or, when the balance is 0 and your overage budget is enabled with room left, billed as overage; if neither can cover it, the push returns 402 insufficient_credits and nothing is pushed. A pushed lead counts as received (exportMethod crm_push in Lead Export History), so it is never charged again. On all plans, unused credits roll over each billing cycle and never expire while your subscription is active - but the remaining balance is forfeited when your subscription ends (at once when you cancel during the free trial), and expires when a plan downgrade takes effect at renewal. Use these endpoints to purchase additional credits or manage your subscription.

Credit balance: Your current credit balance is always available via GET /api/v1/me - see the monthlyCredits, monthlyCreditsRemaining, permanentCredits, and totalCreditsRemaining fields.

Endpoints

POST /api/v1/purchase-credits: Purchase additional credits using your saved payment method (charged off-session via Stripe). Purchased credits roll over month to month while your subscription is active, but the remaining balance is forfeited when your subscription ends (at once when you cancel during the free trial) and expires when a plan downgrade takes effect at renewal. Minimum 100 credits. Pricing: Starter 10¢/credit, Growth 7.5¢/credit, Scale 5¢/credit, Platinum 3¢/credit, Enterprise 2¢/credit. Available on all paid plans.
GET /api/v1/overage-budget: Get your overage budget configuration and usage: an opt-in spending limit that lets lead usage continue past a zero credit balance. Extra credits accrue at your plan's overage rate and are charged to your card on file once per day. The budget applies per billing cycle and resets at renewal.
PATCH /api/v1/overage-budget: Enable, disable, or edit the overage budget. budgetType is 'dollars' (default) or 'credits'; budgetAmount is a whole number of dollars or credits per billing cycle (max half your plan's monthly credit allocation, or its dollar equivalent; for more, turn on auto top-up). Requires an active paid credit plan (not a free trial: turning it on during a trial returns 403 forbidden) and a payment method on file. While a cancellation is scheduled, turning it on returns 409 cancel_pending (reactivate first; a reactivation leaves overage off until you turn it on again); disabling is always allowed. Disabling clears the config; accrued unbilled overage is still collected by the daily billing runs once it reaches Stripe's $0.50 minimum (smaller remaining balances are written off).
POST /api/v1/subscription/change-plan: Upgrade or downgrade your plan (targetPlan: starter, growth or scale). An upgrade is charged now and restarts the billing cycle with the new plan's credits, and all unused credits carry over; a downgrade takes effect at renewal, when the remaining balance expires. During a free trial the default mode switch_trial changes the plan at no charge and keeps the trial end date (credits already used stay used); activate_now ends the trial and charges the target plan now. While a downgrade is pending, moving back to your original plan before renewal cancels the downgrade at no charge (changeType downgrade_cancelled): no new credits, your credits are kept and the renewal date does not change. An upgrade during a billing pause ends the pause. If your subscription is set to cancel, any plan change removes the cancellation: an upgrade is charged and starts now, a downgrade takes effect at renewal, and choosing your current plan reactivates it at no charge (changeType reactivated; every success carries cancellationRemoved). After a subscription has ended, start a new plan with POST /api/v1/purchase.
POST /api/v1/subscription/cancel: Cancel your subscription. A paid subscription is cancelled at the end of the current billing period: access and credits continue until then, and every remaining credit is deleted when it ends; automatic credit top-ups stop as soon as you cancel. Cancelling a paid plan also switches the overage budget off at once and charges any overage used but not yet billed to your card on file right away (under Stripe's $0.50 minimum it is written off; an amount an earlier failed charge is still retrying is collected by those retries); the response's overage block (switchedOff, chargingNowCents, collectedLater) shows what the call did. During the 14-day free trial, cancelling ends the trial immediately: access and all credits (including purchased credits) are removed at once and cannot be restored, nothing is charged, and the trial cannot be started again; send {"endTrialNow": true} to confirm, otherwise the call returns 409 trial_cancel_confirmation_required and changes nothing. Optional reasons (leads_quality, features_missing, too_expensive, technical_issues, found_alternative, other) and feedback (at most 2,000 characters) are stored only when the cancellation goes through. Pausing for one billing cycle, ending a pause early and extending a free trial are offered in the dashboard only.

Purchase Credits Parameters

creditCount (integer, minimum 100) or dollarAmount (number, minimum 1) - send one, not both. idempotencyKey (optional, 8-64 letters, digits, _ or -; also accepted as the Idempotency-Key header) - reuse it when retrying the same purchase so the card is not charged twice.

API Documentation Sections

Setting up a CRM, an automation tool or a webhook? See Tools & Integrations: providers, events, webhook payloads and signatures, Exported leads (batched) and the Zoho Flow scripts.

View Full API Documentation

Ready to Find Your Next Customers? Get access to growing local business leads updated every 5 minutes. See plans starting at $49/mo →