Billing and auto-recharge

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

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.)
  • 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.

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.

curl --fail-with-body --silent --show-error \
  "$BLACKPEARL_API_BASE_URL/v1/pricing-estimates" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY" | jq .
{
  "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.

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.

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.

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 .
{
  "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.

EmailWhen it is sent
Low balanceAfter 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 zeroWhen 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 refusedThe first time in a UTC calendar month that a job is refused with insufficient_credits.
Payment receiptEach time bought credit or an auto-recharge is added to the balance.
Auto-recharge failed, suspended, or needs confirmationSee If a card payment fails.
Card expiringOnce per card, about 30 days before a saved card expires.
Refund issuedWhen a refund to your card completes.
Monthly statementEarly each month, for the previous month, if your balance changed during it.
Budget alertWhen a budget's charges pass one of its alert thresholds.
Project allowance low or used upSee Managing your clients with projects.
Usage tierWhen 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.

See Errors for insufficient_credits and budget_exceeded.