# Billing and auto-recharge

> How prepaid credit is charged, how to cap spend, and how to keep the balance topped up automatically.

Canonical guide: <https://engine.neraperla.com/docs/billing>

Raw Markdown: <https://engine.neraperla.com/docs/raw/billing.md>

OpenAPI: <https://engine.neraperla.com/v1/openapi.json>

Billing is prepaid. Your organization has one credit balance, shared by every project and API key. Every amount on this page is what your balance is charged.

## How charging works

- A job starts only when the balance is above zero. Nothing is estimated or reserved from the balance up front. (A project's allowance can also require a minimum to start; see [Managing your clients with projects](https://engine.neraperla.com/docs/projects).)
- When the job finishes, its actual price is deducted from the balance.
- If the price is more than the remaining balance, the job still finishes and keeps its result. It is charged in full, so the balance goes below zero.
- While the balance is zero or below, new jobs are rejected with `402 insufficient_credits`. Your next top-up clears the amount owed first; new jobs start again once the balance is back above zero.
- Your billing contacts are emailed when a job takes the balance below zero, with the amount charged and a top-up link.

A failed job is never charged. A job you cancel in the console is charged for the work done before you cancelled it. A canceled Playbooks job is the exception: its generation keeps running, and it is charged in full when the generation finishes, without a result. See [Jobs and polling](https://engine.neraperla.com/docs/jobs).

## See typical prices before you run

`GET /v1/pricing-estimates` returns what one unit of each capability is typically charged at your organization's rates, so you can show your own users a price before you submit work. Any API key can call it, and a company-level key needs no `Blackpearl-Project` header.

```bash
curl --fail-with-body --silent --show-error \
  "$BLACKPEARL_API_BASE_URL/v1/pricing-estimates" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY" | jq .
```

```json
{
  "capabilities": [
    {
      "capability_key": "playbooks",
      "name": "Playbooks",
      "docs_slug": "playbooks",
      "units": [
        {"unit": "per_playbook", "label": "per playbook", "approx_usd": 4.9, "low_usd": 2.3, "high_usd": 7.9}
      ]
    }
  ]
}
```

- `approx_usd` is the typical charge for one unit, rounded to two significant figures: the recency-weighted median of what recent runs would be charged at your rates, including any data-record fee.
- `low_usd` and `high_usd` are the typical range: about 80% of recent runs were charged between them, at your rates.
- It is a guide, not a quote, and `high_usd` is not a cap. Each run is charged for the work it actually does, and about one run in ten is charged more than `high_usd`. To bound what one client can spend, give their project an allowance and limits.
- Units depend on the capability: `per_run` for prospecting, `per_playbook` for playbooks, and `per_setup`, `per_cycle` and `per_record` for Audiences, for example.
- Only capabilities that `GET /v1/capabilities` lists for your organization appear. A capability or unit without enough recent runs to price is left out rather than shown as free, so `capabilities` can be an empty list.
- Connected Claude clients get the same figures from the `get_pricing_estimates` tool.

This is OpenAPI operation `pricing_estimates_v1_pricing_estimates_get` with schema `PublicPricingEstimatesResponse`.

## Cap your spend

Budgets cap what you're charged per UTC day or per UTC month, for the whole organization, one project, or one capability. Every budget emails your billing contacts as its period's charges pass its alert thresholds: 50%, 80%, and 100% by default, or the percentages you choose. Each threshold is emailed at most once per period. A soft budget only alerts. A hard budget also rejects new jobs with `429 budget_exceeded` once its period's charges reach the limit. A job that has already started is never cut off: jobs in progress when the limit is reached all finish and are charged, so they can take the total past the limit.

Owners, admins, and billing members manage budgets on the console **Costs** page. Over the API you can set the hard daily and monthly limits of each project (`set_project_limits`) and of the whole company (`set_company_limits`). These limits are budgets too, so they also appear on the **Costs** page. Soft budgets, custom alert thresholds, and budgets for one capability are set in the console only. See [Limits, budgets, and usage](https://engine.neraperla.com/docs/usage-quotas).

If you resell to your own clients, give each client a project with its own allowance and daily and monthly limits, so one client running out never stops the others. See [Managing your clients with projects](https://engine.neraperla.com/docs/projects).

## Add credits

Credit is bought in the console; there is no API for it. Owners, admins, and billing members can buy it.

1. Go to **Settings → Billing → Payment methods** and choose **Add a card**. Card details are entered on our payment processor's secure page.
2. On **Settings → Billing**, choose **Add credits** and pick an amount: $100 to $10,000, in $100 steps. It is charged to your default card.
3. The credit is added to your balance once the payment is confirmed, and a receipt is emailed. If the balance was below zero, the purchase clears the amount owed first.

Credits never expire. Each payment, with its receipt and invoice, is listed under **Settings → Billing → Invoices & receipts**.

## Turn on auto-recharge

Auto-recharge charges your saved card whenever the balance falls below a threshold you set.

1. Sign in to the console as an owner, admin, or billing member.
2. Add a card under **Settings → Billing → Payment methods**, as above. Auto-recharge can't be turned on without a default card.
3. Go to **Settings → Billing → Auto-recharge** and turn on **Enable auto-recharge**.
4. Set **When balance falls below (USD)**, up to $10,000, and **Recharge amount (USD)**. Recharges start at $100 and go up in $100 steps, to a maximum of $10,000. The defaults are a $50 threshold and a $100 recharge.
5. Choose **Save settings**.

The balance is checked each time a job is charged, and every few minutes. Set the threshold above the price of your largest single job, so the balance rarely dips below zero. If a job leaves the balance further below the threshold than one recharge covers, auto-recharge charges again on the next check until the balance is back above the threshold.

## If a card payment fails

- Jobs keep running on the remaining balance.
- After the first failure the charge is retried 1 hour later, and after the second failure 6 hours later, if the balance is still below the threshold. You are emailed after each failure.
- After the third failure in a row, auto-recharge is suspended and you are emailed. Update the card in **Payment methods**, then choose **Retry now** on the **Auto-recharge** page.
- If your bank asks for extra verification, choose **Confirm payment** on the **Auto-recharge** page. This does not count as a failure.
- When the balance reaches zero or below, new jobs are rejected with `insufficient_credits` until credit is added.

## Check your balance

- Console: **Settings → Billing**. When the balance is below zero, the page shows the amount owed and the top-up that brings it back above zero.
- API: `GET /v1/usage` returns `credits.balance_usd`, which can be negative. It reports on one project, so a company-level key without a default project names any project with the `Blackpearl-Project` header (the balance is the company's), or reads `balance_after_usd` on the newest `GET /v1/charges` entry.
- A refund to your card that hasn't completed yet can't be spent, so a job can be refused with `402 insufficient_credits` while `credits.balance_usd` still includes that amount.
- Per-client charges: `GET /v1/projects/{project_ref}/charges` lists what each of a project's jobs was charged, in the same shape and with the same signs as `GET /v1/charges` below.

## Read your charge history

`GET /v1/charges` lists every change to your balance, newest first: what each job was charged (`debit`), credit you bought (`topup`), promotional credit (`gift`), corrections (`adjustment`), refunds to your card (`refund`), and refunds that failed and came back (`refund_reversal`). `amount_usd` is signed, negative for money out of the balance, and `balance_after_usd` is the balance right after the entry, so the newest entry's balance matches `credits.balance_usd`.

```bash
curl --fail-with-body --silent --show-error \
  "$BLACKPEARL_API_BASE_URL/v1/charges?type=debit&from=2026-10-01T00:00:00Z" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY" | jq .
```

```json
{
  "charges": [
    {
      "id": "ctx_5a8b2c9d1e0f3a4b",
      "type": "debit",
      "amount_usd": -2.43,
      "balance_after_usd": 412.57,
      "job_id": "job_0b1c2d3e4f5a6b7c",
      "capability": "prospecting",
      "project_id": "proj_3f9c1a7d2b8e4c11",
      "project_slug": "client-a",
      "project_name": "Client A",
      "created_at": "2026-10-08T12:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

- Filter with `type` (repeatable), `from` and `to` (UTC; `to` is exclusive), and `project` (id or slug). Page with `limit` (50 by default, up to 200) and `cursor`; a cursor that isn't a `next_cursor` from this listing returns `400 invalid_cursor`.
- A company-level key sees the whole company, or one project with `project` or the `Blackpearl-Project` header. Naming two different projects that way returns `400 invalid_request`, and an unknown project `404 project_not_found`. A key's default project never narrows the listing. A project key sees only its own project's job charges; naming another project returns `403 forbidden`.
- Every amount is what you were charged or credited: a job's `debit` is its `usage.cost_usd`, as a negative amount.
- Connected Claude clients get the connected project's charges from the `list_charges` tool.

This is OpenAPI operation `list_charges` with schema `PublicChargeList`.

## Statements and refunds

- **Settings → Billing → Invoices & receipts** shows a statement for each UTC calendar month: opening balance, credit purchased, promotional credit, refunds, corrections, what jobs were charged by capability, and closing balance, with a CSV download.
- Refunds to your card are made by Blackpearl support; the console and API don't offer them. A refund leaves your balance and appears as a `refund` entry. Until it completes, its amount can't be spent.

## Billing emails

Billing emails go to the **Billing email override** on **Settings → Billing**, if you set one, and otherwise to every active owner, admin, and billing member.

| Email | When it is sent |
|---|---|
| Low balance | After a job is charged, if auto-recharge is off and the balance is at or above $0 but below $25. At most once per UTC calendar month. |
| Balance below zero | When a job's charge takes the balance from $0 or above to below zero. Further jobs that deepen the same overdraft don't send another. |
| New runs refused | The first time in a UTC calendar month that a job is refused with `insufficient_credits`. |
| Payment receipt | Each time bought credit or an auto-recharge is added to the balance. |
| Auto-recharge failed, suspended, or needs confirmation | See [If a card payment fails](#if-a-card-payment-fails). |
| Card expiring | Once per card, about 30 days before a saved card expires. |
| Refund issued | When a refund to your card completes. |
| Monthly statement | Early each month, for the previous month, if your balance changed during it. |
| Budget alert | When a budget's charges pass one of its alert thresholds. |
| Project allowance low or used up | See [Managing your clients with projects](https://engine.neraperla.com/docs/projects#alerts). |
| Usage tier | When your organization moves up a usage tier, and the first time in a month its tier's spend cap stops a job. See [Rate limits](https://engine.neraperla.com/docs/rate-limits#usage-tiers). |

See [Errors](https://engine.neraperla.com/docs/errors) for `insufficient_credits` and `budget_exceeded`.
