Billing

Billing is the organization-level place for setup, usage mode, spend control, invoices, payment recovery, and endpoint charge explanations.

Pharaoh pricing uses Pilot, Production, and Enterprise / MSP packages. A new organization must complete billing setup before billable Pharaoh work can run.

For a new or invited organization that has not completed mandatory onboarding, billing setup appears inside Organization Onboarding. The billing service remains authoritative, but onboarding controls the full-page route and checks whether billing is active before the organization can enter the main console.

What Billing Covers

Production organizations pay the fixed subscription and endpoint overage fees:

Pilot: guided 30-day pilot for up to 10 active endpoints, unlimited users, standard onboarding, and either BYO key or a capped managed-AI trial credit.
Production base subscription: $49/month per organization with 20 active endpoints included.
Additional Production endpoints: $2/month per active endpoint above the included 20, prorated by active intervals in the billing month.
Enterprise / MSP: custom terms for larger fleets, annual commitments, invoicing, priority support, optional hardware bundles, and procurement reviews.
Billing currency is selected from the currencies enabled for the environment before Stripe setup starts. The local test configuration supports USD, CAD, and EUR; live production currency lists and amounts are approved before release.

LLM usage depends on the selected usage mode:

BYO Anthropic key: Pharaoh charges base and endpoint fees only. Provider usage is paid through your Anthropic account. Pharaoh still tracks usage where available so you can understand cost and spend-limit impact.
Managed usage: Pharaoh provides provider access, tracks actual provider usage, and bills usage through Stripe as actual provider cost plus the package management fee unless a signed order says otherwise.

Hardware is separate from the software subscription. It is handled as a one-time purchase for standard needs or as an Enterprise / MSP procurement add-on for larger programs.

The billing page is also the recovery page. If setup, payment, subscription, spend limit, or provider credential state blocks work, the web console stays available so an authorized billing operator can resolve the problem.

After Stripe setup starts, currency changes require support so subscription items, endpoint invoice lines, and managed usage records do not mix currencies.

Setup And Recovery States

Billing status can show:

setup_required: complete billing setup before billable work starts.
payment_action_required: update payment in the Stripe-hosted recovery flow.
subscription_blocked: review the billing page and follow the recovery action.
spend_limit_reached: raise or adjust the monthly usage limit before more expensive LLM work runs.
active: billing is ready, subject to provider credential and spend checks.
billing_state_unknown_fail_closed: Pharaoh cannot prove eligibility, so expensive work stays blocked until status is available again.

Frontend warnings are guidance only. Backend billing checks remain authoritative before expensive work runs.

During onboarding, active billing is mandatory. Operators with billing permission can continue to setup and then return to onboarding to check status. Operators without billing permission see an owner or billing-manager handoff and remain blocked from main-console access until an authorized operator completes billing.

Analytics, Invoices, And Payment

Use billing analytics to compare base fees, endpoint fees, and usage charges. The current web UI reads live billing APIs for usage analytics, invoice summaries, endpoint charges, spend-limit updates, provider credential metadata, and Stripe reconciliation diagnostics. Usage rows should preserve provider-native units such as input tokens, output tokens, cached tokens, model, provider, feature, session, prompt, endpoint, mode at request time, and currency cost.

Use invoices to review Stripe-backed billing periods, invoice status, and line-item explanations. Use payment recovery to update payment details through Stripe-hosted flows. Pharaoh documentation should not ask you to paste card details into screenshots, support tickets, traces, or chat.

Endpoint Charges

An endpoint charge is based on when a deployed Pharaoh agent instance was active, not on API calls, heartbeat count, or total runtime hours. In Production, the first 20 active endpoint-months are included before additional active endpoint charges apply.

An endpoint becomes or remains active after a successful heartbeat. If it has no successful heartbeat for 14 days, billing can close the active interval as inactive. Deleting or explicitly deactivating an endpoint stops future active intervals. Pharaoh does not automatically delete old endpoints just because they are inactive.

Endpoint charge views should show human-readable endpoint names, active intervals, proration, charge amount, and the reason an endpoint was charged or not charged.

Usage Mode Switching

Switching between BYO and managed usage changes future provider usage billing only:

Base and endpoint fees do not change.
Managed usage before the switch remains billable through Pharaoh.
BYO usage after the switch is not billed by Pharaoh as managed provider usage.
Usage history preserves the mode that was active at request time, so old rows may not match the current mode.

Known Proof Boundaries

Current billing UI screenshots in trace artifacts use deterministic Playwright state for analytics, invoices, endpoint charges, and payment recovery. Round 3 proves the UI renders the live-data-backed API contracts where those backend APIs exist, but those trace screenshots are still visual proof, not mock-free E2E proof. The committed end-user screenshot manifest now has seeded billing capture routes for setup-required and active-dashboard states with focused capture and verify proof from 2026-05-04. Onboarding-specific billing screenshots are blocked until the docs capture helper has seeded onboarding route states.

Clean Stripe sandbox lifecycle proof now exists for subscription setup, webhook forwarding, test-clock advance, and internal subscription/payment projection. Stripe-hosted browser checkout, customer portal, invoice viewing, and payment method screens remain external Stripe surfaces; Pharaoh docs may describe the handoff, but should not claim committed browser screenshot replay for those hosted pages until a secret-safe capture lane exists.