---
id: platform/billing-setup
title: Billing setup
description: Complete hosted payment readiness, recover from PAYMENT_REQUIRED refusals, and know who can bind a payment method.
keywords: [bex, billing, payment, checkout, portal, PAYMENT_REQUIRED, onboarding]
last_updated: 2026-09-23
---

Hosted Bex ([dashboard.bex.co](https://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](/pricing) page; this guide does not invent rates, credits, or
exemptions.

For account creation, invitations, and workspace selection, start with
[Hosted setup](./hosted-setup.md).

## 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](./members.md).

## Payment wall after sign-up {#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.

1. Stay signed in. Open Checkout from the wall (same browser tab).
2. Complete Stripe Checkout in setup mode to bind a payment method, or cancel.
3. On return, the URL may include `billing=success` or `billing=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 on `billing=success`.
4. When readiness clears, the wall continues to the guarded `next` destination
   (or the overview if none was set).
5. If you will not bind a card, use **Self-host bex instead** on the wall
   ([GitHub repository](https://github.com/bex-co/bex)). 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](#payment-wall-after-sign-up), then retry your create. See
[API errors](./api.md#errors-and-compatibility).

## 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=success` alone 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](./web-services.md) (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](./usage.md) before the
invoice arrives to reconcile consumed meters against the billing projection.