Billing and platform supply

Start without a provider key, bring your own later, and understand which gate refused a request.

Platform supply is model capacity routed through a provider account Checkfu owns when commercial supply is admitted for the Workspace.

Commercial billing and platform supply are preview / rollout_fenced in the source registry. This page defines their admitted contract and failure behavior; it is not a promise that checkout, portal, entitlement, or Checkfu-funded model capacity is enabled. Check the live capability status before building an onboarding path around them.

The contract exists so an eligible Workspace can receive a credential-free starter ModelRoutingProfile after the live support projection proves commercial and provider-supply prerequisites.

Provider keys stay inside the platform vault and the model adapter boundary. They never enter a Sandbox, Harness input, execution release, event, log, usage record, or API response.

Platform supply is an onboarding default and a metered pass-through, not a standalone token product.

Bringing your own key

A Workspace can create a stable ModelCredential at any time. Credential identity alone changes no route: publish a new ModelRoutingProfile revision whose candidate explicitly selects workspace_credential and that credential’s ID. To select platform supply again, publish another revision with platform_provider and eligible_at_admission. Rotation changes the active credential generation for future admissions without rewriting the profile revision.

A revision that selects a Workspace credential fails closed with model.credential_rejected when its active generation is rejected or revoked. It never silently changes to Checkfu’s provider account, because that would replace the authority a human explicitly published.

Four gates, none of which substitutes for another

A request that consumes model capacity passes several independent checks. Distinguishing them matters, because they need different people to resolve them.

Gate	Question	Error	Who resolves it
Budget	Has this Workspace, Agent, Principal, SurfaceScope, or Automation crossed a limit you set?	budget.exceeded	You
Entitlement	May this Organization consume paid Checkfu capability?	billing.usage_limit_reached	An Organization administrator
Payment	Is the account in good standing?	billing.payment_required	An Organization administrator
Platform supply ceiling	Is Checkfu’s own provider capacity available?	model.platform_capacity_reached	Wait, or add your own key

All applicable gates must allow the request. An entitlement grant is not a budget, and raising a budget does not extend entitlement.

What you pay for model usage

Customer-facing usage is two lines:

• Session runtime — $0.08 USD per hour while a Run (and, when several SessionThreads run, each thread’s Run) is running. Fractional hours are billed. Idle, waiting on approval, requires_action, rescheduling, terminated, and settled time is not billed. A Checkfu-hosted sandbox and your own Runner use the same rate. There is no separate sandbox fee.
• Models. Bring your own key: $0 Checkfu model fee. Checkfu credits (platform supply): upstream cost × 1.05. Credits are money, not a fake token unit. A Workspace credential never silently falls back to platform supply.

Sandbox CPU/RAM, snapshot retention, and Connection usage are recorded in the usage ledger for unit economics and are not invoiced. Builder seats stay in the membership model and are free during private alpha.

The append-only usage ledger is the billing record; see Attribute usage per end user to read it.

Seats

A billable builder seat is one accepted, active human membership with effective configuration authority. The same human counts once across every Workspace. Seats stay in that model for later GA and are not invoiced or used as an admission block during private alpha.

Not builder seats: viewers, pending invitations, Principals, API keys, service accounts, and service actors. An agent acting on behalf of ten thousand end users consumes no seats.

Failure behavior

Situation	What still works
Entitlement service unavailable	Login, reads, exports, and member removal continue. New Checkfu-funded work fails closed with billing.entitlement_unavailable.
Payment past due	Credentials and history are preserved. New Checkfu-funded work and paid-seat activation are blocked.
Platform supply exhausted	Platform supply blocks; your own provider key remains independently usable.

Checkfu’s own usage ledger is the authoritative record of what was consumed. Usage is never inferred from a provider dashboard, a trace, or response timing. A meter stays dark until it has both an immutable per-unit receipt and a reviewed, published rate, and the catalog names which of the two is missing. See Attribute usage per end user.

Endpoints

Endpoint	Purpose
GET /v1/billing/status	Current entitlement, platform capacity, and the selected model source
GET /v1/billing/logs	Sanitized billing state transitions
POST /v1/billing/portal	Open the hosted payment-recovery surface
POST /v1/billing/checkout/preview	Price a plan change before committing to it
POST /v1/billing/checkout	Start the checkout you previewed

Checkout is a two-step flow on purpose: the preview step binds the exact catalog version, amount, and currency, and starting checkout must confirm that exact preview. A price cannot change between what a customer was shown and what they are charged. Checkout, cancellation, and portal idempotency are Organization-level rather than Workspace-level. An exact checkout replay re-reads the durable attempt and current provider-backed commercial state; it returns a redirect only while that hosted checkout is live, and returns confirmed once Team is verified. A keyed portal retry returns the same encrypted-at-rest provider URL for a five-minute receipt window, so a retry does not open a second portal session. After that window, the key can issue a fresh identity-checked session.

Next steps

Harnesses and models

How a ModelRoutingProfile names candidates and routes between them.

Attribute usage per end user

Read the ledger and cap spend per Principal.