> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Open the billing portal

> Generate a short-lived customer portal URL for a user's personal billing or an organization's team billing.

Open the hosted billing portal so a user can update a saved card, view
invoices, or download receipts. Scope the portal to a personal billing
customer or to a team (organization) billing customer.

## Authentication

Requires a Bearer token with the `billing` scope. See
[Authentication](/api-reference/authentication).

## Body

<ParamField body="scope" type="string">
  `"user"` (default when personal) or `"org"` (default when the caller is
  inside a team and holds `manageBilling`). Team scope additionally
  requires the team to have a payment method already on file — callers
  who try the team portal before funding billing get a 409
  `team_billing_setup_required` error instead.
</ParamField>

## Example

```bash curl theme={null}
curl -X POST "https://api.hitheo.ai/api/v1/billing/portal" \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "org" }'
```

```typescript SDK theme={null}
const { portal_url } = await theo.billingPortal({ scope: "org" });
window.open(portal_url, "_blank");
```

## Response

```json theme={null}
{
  "portal_url": "https://portal.hitheo.ai/session/...",
  "scope": "org"
}
```

## Errors

| Status | Code                          | Meaning                                                    |
| ------ | ----------------------------- | ---------------------------------------------------------- |
| 400    | `org_context_required`        | Requested `scope: "org"` without an active team.           |
| 403    | `permission_denied`           | Caller lacks `manageBilling` in the active team.           |
| 409    | `team_billing_setup_required` | Team has no payment method on file — run a checkout first. |
| 503    | `billing_unavailable`         | Billing isn't configured on this deployment.               |