Skip to main content
POST
/
api
/
v1
/
billing
/
portal
Open the billing portal
curl --request POST \
  --url https://api.example.com/api/v1/billing/portal \
  --header 'Content-Type: application/json' \
  --data '
{
  "scope": "<string>"
}
'
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.

​
Body

​
scope
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.

​
Example

curl
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" }'
SDK
const { portal_url } = await theo.billingPortal({ scope: "org" });
window.open(portal_url, "_blank");

​
Response

{
  "portal_url": "https://portal.hitheo.ai/session/...",
  "scope": "org"
}

​
Errors

StatusCodeMeaning
400org_context_requiredRequested scope: "org" without an active team.
403permission_deniedCaller lacks manageBilling in the active team.
409team_billing_setup_requiredTeam has no payment method on file — run a checkout first.
503billing_unavailableBilling isn’t configured on this deployment.