Credits

Each operation has a canonical credit price from 5 to 20 credits. Free calls display that price for transparency but consume exactly one Free call when successful.

The $0.01 figure is the nominal operation-credit value and the metered overage rate. Prepaid packs use published volume pricing: $0.010, $0.009 or $0.008 per acquired credit depending on pack size. Pack discounts do not change operation tariffs.

Balance components

free_calls_remaining: monthly no-card allowance.
gifted credits: claimed Preview invitations available to the user.
included_credits - included_used: paid-plan cycle balance.
purchased_credits - purchased_used: prepaid balance.
overage: metered credits beyond available balances for eligible subscriptions.

Failure safety

Clawdbase temporarily reserves the eligible amount while an operation runs. Success commits the charge. Failure reverses it and settles the receipt with zero charged units. A 502 from inVerus therefore includes "no credits charged."

Balance state is read from /api/clawdbase/usage, not recomputed in the browser.

Consumption sequence

Clawdbase chooses the first eligible source atomically:

Remaining monthly Free calls, charged as one call.
Gifted credits, charged at the operation credit price.
Included plan credits.
Purchased prepaid credits.
Metered overage for an active eligible paid subscription.

The operation request cannot choose a source. This prevents clients from preserving one balance by forcing another.

Example balance reading

const response = await fetch('/api/clawdbase/usage', {
  headers: { Authorization: `Bearer ${session.access_token}` },
})

if (!response.ok) throw new Error(`Usage unavailable: ${response.status}`)
const { balance, ledger } = await response.json()

Render a missing balance as unavailable, not as zero or unlimited credits. Calculate remaining values from the server-returned counters; do not maintain a second client-side balance.

Free calls versus credits

A successful Free allowance request consumes one call even for a 20-credit lineage operation. Once the allowance is exhausted, paid balance sources consume the operation's canonical price. Keep “calls” and “credits” labeled separately in the Console.

Settlement

Every accepted operation creates or reuses a ledger identity. pending holds the selected source. success commits it. failed reverses the exact counter and settles with zero charged credits. A retry with the same idempotency key does not create another settled charge.

Get support

To investigate a balance change, provide support with the ledger ID, operation, safe subject reference and timestamp. Do not send your Access Key or payment details.