Hosted Bex (dashboard.bex.co) requires a bound
payment method before you can create resources, including on a free instance
plan. This guide covers the payment wall, readiness signals, checkout and
portal sessions, and what to do when a create is refused with
PAYMENT_REQUIRED.
Self-hosted installations may disable payment collection entirely. If your dashboard never asks for a card, follow your operator's billing configuration instead of this hosted path. Pricing amounts live on the pricing page; this guide does not invent rates, credits, or exemptions.
For account creation, invitations, and workspace selection, start with Hosted setup.
Who can complete payment setup
Only workspace members with billing administration can open Checkout or the
Customer Portal and read billing readiness for that workspace. In practice that
is the admin or billing role (can_manage_billing). Developers and
other roles keep using the product; when a create is refused, they need an
admin or billing member to finish this guide, then retry.
See Workspaces, members, & roles.
Payment wall after sign-up
When hosted billing still requires a method for the current workspace, the
dashboard sends a billing manager to Add a payment method at
/setup/payment. The page uses the same chrome as sign-up and verification.
- Stay signed in. Open Checkout from the wall (same browser tab).
- Complete Stripe Checkout in setup mode to bind a payment method, or cancel.
- On return, the URL may include
billing=successorbilling=cancelled. Those query values are progress signals only. The gate opens when the backend records the bound method (after the signed webhook), not when the browser lands onbilling=success. - When readiness clears, the wall continues to the guarded
nextdestination (or the overview if none was set). - If you will not bind a card, use Self-host bex instead on the wall (GitHub repository). That exit is on the payment wall; the create-refusal dialog may not offer the same link.
If billing readiness cannot be loaded, the wall offers retry. Non-managers who land on the page are forwarded through; they cannot bind a card themselves.
Readiness fields (hosted)
Workspace billing readiness (dashboard Billing settings, REST
GET /v1/workspaces/{workspaceId}/billing, GraphQL, or MCP) exposes three
related signals. Names vary slightly by surface; the meanings are:
| Signal | Meaning |
|---|---|
| Payment method required | This installation has a payment gate enabled for the caller. |
| Payment method ready | A payment method is bound for the workspace (local marker after Checkout completion). |
| Payment method onboarding required | Hosted all-mode gate would refuse a create right now for this workspace — the same question the create path asks. When false, the sign-up wall does not hold you. |
Do not infer readiness from plan names. A free instance plan is not a hosted
billing exemption under the hosted all gate.
Checkout vs Customer Portal
| Action | Use |
|---|---|
| Bind or replace the default payment method | Checkout (setup mode). Used by the payment wall and by the create-refusal dialog. |
| Manage payment methods and invoices later | Customer Portal, from Billing settings, once the workspace already has a Stripe customer and subscription. |
Both actions require can_manage_billing. Minting a session without that role
fails with 403.
Create refused with PAYMENT_REQUIRED
Creates (services, databases, Key Value, Blueprint apply, and related agent
session admission under the hosted gate) return HTTP 402 with code
PAYMENT_REQUIRED when the gate refuses the workspace.
In the dashboard, the interception dialog opens Checkout in a new tab for a billing manager, then retries the pending mutation after readiness becomes true. API, CLI, and MCP callers must create a billing Checkout session (or ask a billing manager to use the dashboard) and retry the original operation after the method is bound.
If you cannot manage billing, ask an admin or billing member to complete payment setup, then retry your create. See API errors.
Cancelled Checkout and pending confirmation
- Cancelled Checkout on the wall shows an in-page alert. Bind again when ready, or leave through self-hosting.
- Successful return with readiness still pending is normal for a short
interval: wait for the wall to finish confirming (it polls). Do not treat
billing=successalone as permission to create. - Billing service unavailable should be retried; if it persists, the installation's Stripe configuration may be down (hosted operators: check the billing Secret and control-plane database). Creates stay refused until readiness recovers.
After the gate opens
Select the workspace that should own the service, then follow Web services (or another service type). Payment readiness is per workspace: joining an already-ready team workspace does not require you to bind a card on your personal workspace first.
Once resources are running, read Month-to-date usage before the invoice arrives to reconcile consumed meters against the billing projection.