> ## Documentation index
> Fetch the complete documentation index at: https://docs.leadity.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Spending credits safely

> Price first, cap every purchase with maxCredits, and retry with the same Idempotency-Key.

Some operations take credits from the account's balance. Each one follows the same four rules, on the HTTP API and the MCP server alike, so code that handles one handles them all.

## The four rules

**1. Price it first, for free**

Every spending operation has a free operation that prices it, named in the first sentences of its description. An order is priced by [`estimate_scrape`](https://docs.leadity.io/api-reference/scrapes/estimate-scrape), a validation list by [`preview_validation`](https://docs.leadity.io/api-reference/validations/preview-validation), and every upgrade to a finished scrape by [`list_scrape_offers`](https://docs.leadity.io/api-reference/scrapes/list-scrape-offers).

**2. Cap it with maxCredits**

Every spending call requires `maxCredits`, the most it may take. It is a ceiling, never a price: at or under it you are charged Leadity's own number. If the price is above it, nothing is charged and the call answers `quote_exceeded`.

**3. Make it retry-safe**

Every spending call requires an `Idempotency-Key`, so a retry replays the first answer instead of buying twice, and the same key on a different request is refused with `idempotency_conflict`. See [Idempotency](https://docs.leadity.io/idempotency).

**4. Use a key with the spend scope**

A key without `spend` can price everything and buy nothing. Give `spend` only to the integration that places orders. See [API keys and scopes](https://docs.leadity.io/api-keys).

## What takes credits

| Spends credits | Price it first with | What it buys |
| --- | --- | --- |
| [`create_scrape`](https://docs.leadity.io/api-reference/scrapes/create-scrape) | [`estimate_scrape`](https://docs.leadity.io/api-reference/scrapes/estimate-scrape) | Order a scrape: find businesses live on Google Maps and deliver them as leads. |
| [`purchase_residuals`](https://docs.leadity.io/api-reference/scrapes/purchase-residuals) | [`list_scrape_offers`](https://docs.leadity.io/api-reference/scrapes/list-scrape-offers) | Buy one cell of a finished scrape's held-back businesses. |
| [`purchase_phone_reveal`](https://docs.leadity.io/api-reference/scrapes/purchase-phone-reveal) | [`list_scrape_offers`](https://docs.leadity.io/api-reference/scrapes/list-scrape-offers) | Buy the phone line types of a finished scrape's delivered leads. |
| [`purchase_email_find`](https://docs.leadity.io/api-reference/scrapes/purchase-email-find) | [`list_scrape_offers`](https://docs.leadity.io/api-reference/scrapes/list-scrape-offers) | Buy email addresses for a finished scrape's delivered leads. |
| [`purchase_email_verify`](https://docs.leadity.io/api-reference/scrapes/purchase-email-verify) | [`list_scrape_offers`](https://docs.leadity.io/api-reference/scrapes/list-scrape-offers) | Buy deliverability verdicts for a finished scrape's email addresses. |
| [`purchase_owner_names`](https://docs.leadity.io/api-reference/scrapes/purchase-owner-names) | [`list_scrape_offers`](https://docs.leadity.io/api-reference/scrapes/list-scrape-offers) | Buy owner names for a finished scrape's delivered leads. |
| [`create_validation`](https://docs.leadity.io/api-reference/validations/create-validation) | [`preview_validation`](https://docs.leadity.io/api-reference/validations/preview-validation) | Validate a list of phone numbers or email addresses you supply. |

## How an order is charged

[`create_scrape`](https://docs.leadity.io/api-reference/scrapes/create-scrape) holds the price of the whole order when it is placed: `targetLeads` at the per-lead rate, `ceil(targetLeads x leadRateMilli / 1000)` credits, plus, when review scraping is ordered, the reviews ceiling, `ceil(targetLeads x maxReviews x review)` credits with `review` the per-review rate [`get_pricing`](https://docs.leadity.io/api-reference/catalog/get-pricing) names. Each part is rounded up to a whole credit on its own, so `maxCredits` must cover the two together. [`estimate_scrape`](https://docs.leadity.io/api-reference/scrapes/estimate-scrape) answers the per-lead rate and never the reviews part. The scrape then charges each lead it delivers. When it settles, whatever was not delivered comes back to the balance, so a run that delivers 600 of the 1,000 leads ordered is charged for 600.

Two things are never charged: a business your account already holds, in any niche, and a lead the filters refused. Stopping a scrape with [`stop_scrape`](https://docs.leadity.io/api-reference/scrapes/stop-scrape) keeps what it delivered and refunds the rest.

The upgrades do not all charge alike. Two take their price outright, because what they buy is counted before the call: [`purchase_residuals`](https://docs.leadity.io/api-reference/scrapes/purchase-residuals) buys a cell of held-back businesses and [`purchase_phone_reveal`](https://docs.leadity.io/api-reference/scrapes/purchase-phone-reveal) the line types of the numbers already delivered, and neither refunds anything. The other three, [`purchase_email_find`](https://docs.leadity.io/api-reference/scrapes/purchase-email-find), [`purchase_email_verify`](https://docs.leadity.io/api-reference/scrapes/purchase-email-verify) and [`purchase_owner_names`](https://docs.leadity.io/api-reference/scrapes/purchase-owner-names), hold the price of the whole target up front and refund the part that found nothing when the run ends, and so does [`create_validation`](https://docs.leadity.io/api-reference/validations/create-validation) for its list. Credits are whole numbers, so a price per item in fractions of a credit is rounded up once over the whole quantity, never per item: 21 owner names at 2.5 credits each hold 53, and 1,152 phone numbers at 0.2 hold 231.

> **Tip:** Pricing an order is free and safe to repeat. An agent should always show a person the price from [`estimate_scrape`](https://docs.leadity.io/api-reference/scrapes/estimate-scrape) and pass a `maxCredits` no higher than what they agreed to.

## When the balance is short

A purchase the balance cannot cover is refused with `402 insufficient_credits` before anything is taken. To add credits, [`list_plans`](https://docs.leadity.io/api-reference/billing/list-plans) lists the plans and packs, and [`create_checkout`](https://docs.leadity.io/api-reference/billing/create-checkout) answers a checkout link for a person to open and pay at. An account with a monthly plan can also top it up: [`create_top_up_checkout`](https://docs.leadity.io/api-reference/billing/create-top-up-checkout) answers a link for any amount `list_plans` names under `topUp`, at the plan's own rate. No key can pay for anything itself: the credits land when the person pays.