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_usdis 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_usdandhigh_usdare the typical range: about 80% of recent runs were charged between them, at your rates.- It is a guide, not a quote, and
high_usdis not a cap. Each run is charged for the work it actually does, and about one run in ten is charged more thanhigh_usd. To bound what one client can spend, give their project an allowance and limits. - Units depend on the capability:
per_runfor prospecting,per_playbookfor playbooks, andper_setup,per_cycleandper_recordfor Audiences, for example. - Only capabilities that
GET /v1/capabilitieslists for your organization appear. A capability or unit without enough recent runs to price is left out rather than shown as free, socapabilitiescan be an empty list. - Connected Claude clients get the same figures from the
get_pricing_estimatestool.
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.
- Go to Settings → Billing → Payment methods and choose Add a card. Card details are entered on our payment processor's secure page.
- On Settings → Billing, choose Add credits and pick an amount: $100 to $10,000, in $100 steps. It is charged to your default card.
- 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.
- Sign in to the console as an owner, admin, or billing member.
- Add a card under Settings → Billing → Payment methods, as above. Auto-recharge can't be turned on without a default card.
- Go to Settings → Billing → Auto-recharge and turn on Enable auto-recharge.
- 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.
- 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_creditsuntil 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/usagereturnscredits.balance_usd, which can be negative. It reports on one project, so a company-level key without a default project names any project with theBlackpearl-Projectheader (the balance is the company's), or readsbalance_after_usdon the newestGET /v1/chargesentry. - A refund to your card that hasn't completed yet can't be spent, so a job can be refused with
402 insufficient_creditswhilecredits.balance_usdstill includes that amount. - Per-client charges:
GET /v1/projects/{project_ref}/chargeslists what each of a project's jobs was charged, in the same shape and with the same signs asGET /v1/chargesbelow.
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),fromandto(UTC;tois exclusive), andproject(id or slug). Page withlimit(50 by default, up to 200) andcursor; a cursor that isn't anext_cursorfrom this listing returns400 invalid_cursor. - A company-level key sees the whole company, or one project with
projector theBlackpearl-Projectheader. Naming two different projects that way returns400 invalid_request, and an unknown project404 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 returns403 forbidden. - Every amount is what you were charged or credited: a job's
debitis itsusage.cost_usd, as a negative amount. - Connected Claude clients get the connected project's charges from the
list_chargestool.
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
refundentry. 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.
| 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. |
| 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. |
| 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. |
See Errors for insufficient_credits and budget_exceeded.