Manage Billing Issues

Use this guide when billable work is blocked by setup, payment, subscription, spend, provider credential, or unknown billing state.

First Checks

Open Billing.
Confirm the current organization in the user menu.
Read the recovery banner and recovery route.
Check whether the issue is payment, spend limit, provider credential validation, or a subscription state.

The web console should keep billing recovery available even when billable work is blocked.

Common States

setup_required
- Means: Billing setup is not complete.
- Action: Open /billing/setup and complete setup.
payment_action_required
- Means: Stripe-derived state requires payment attention.
- Action: Open payment recovery and update payment through Stripe-hosted flow.
subscription_blocked
- Means: Subscription state does not allow billable work.
- Action: Review Billing and follow the recovery action; contact support if no self-service action is available.
spend_limit_reached
- Means: Monthly usage spend limit has been reached.
- Action: Raise the limit or wait for the next billing month.
billing_state_unknown_fail_closed
- Means: Pharaoh cannot prove billing eligibility.
- Action: Retry status, then use Billing or support diagnostics if it persists.
provider credential invalid
- Means: BYO key validation failed or needs attention.
- Action: Replace or rotate the BYO Anthropic key.

If the issue is a locked billing currency, do not retry setup with another currency. Currency changes after Stripe setup require support so existing subscription and invoice state can be migrated intentionally.

Payment And Invoice Recovery

Use Stripe-hosted payment and portal flows for payment methods, billing details, invoice review, and payment recovery. Do not paste card details into Pharaoh support channels or docs artifacts.

Invoice screens should explain base subscription fees, endpoint charges, and managed usage separately. BYO provider usage should not appear as Pharaoh-managed usage.

Endpoint Charge Questions

Endpoint fees are based on active intervals. They are not based on API call count, heartbeat count, or total runtime hours.

If an endpoint charge looks surprising, check:

the endpoint display name
the active interval dates
whether the endpoint registered mid-month
whether it was deleted or deactivated mid-month
whether inactivity closed the interval after 14 days without successful heartbeat
the prorated amount for the billing month

Support diagnostics can combine invoice lines, endpoint charges, usage analytics, Stripe reconciliation, and monitoring signals for failed usage reporting or unusual managed-usage spikes. These diagnostics use sanitized IDs and summaries; do not request or paste API keys, card data, raw Stripe payloads, or raw provider responses in support channels.

Known Fixture Boundaries

Current billing analytics, invoice rows, endpoint charge rows, and payment recovery states in trace screenshots are deterministic visual states. Round 3 proved that the UI reads the live billing API contracts for analytics, invoices, endpoint charges, spend-limit updates, provider credential metadata, and Stripe reconciliation diagnostics, but the screenshot replay still uses route fulfillment rather than a mock-free seeded backend journey. Treat trace screenshots as layout and contract-rendering proof, not live customer billing proof or committed end-user screenshot assets.

Clean Stripe sandbox proof exists for subscription setup, webhook forwarding, test-clock advance, endpoint invoice item sync, managed usage outbox drain, and internal payment/subscription projection. Stripe-hosted invoice viewing, customer portal, and payment method recovery remain external hosted flows; docs should describe the handoff and security boundary without claiming committed browser screenshot replay.