> ## 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.

# Create a top-up checkout

> Generate a hosted checkout URL to add credits to your personal balance or your team's shared credit pool.

Top up credits against the caller's personal balance or an organization's
shared team billing pool. Returns a hosted checkout URL your application
opens in a new tab or redirects the user to.

## Authentication

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

## Body

<ParamField body="amount_cents" type="integer" required>
  Amount to add, in cents. Minimum `500` ($5.00), maximum `100000` ($1,000.00).
</ParamField>

<ParamField body="scope" type="string">
  `"user"` (default when personal) or `"org"` (default when the caller is
  inside a team and holds `manageBilling`). When `"org"`, the top-up
  lands on the team's shared credit pool at
  `organizations.polar_customer_id` and all subsequent team-scoped API
  usage draws from that pool until it's depleted.
</ParamField>

<ParamField body="success_url" type="string">
  Optional. URL to redirect the user to after successful checkout.
  Defaults to `/dashboard/billing?topup=success` (or
  `/dashboard/billing?topup=success&scope=team` when `scope: "org"`).
</ParamField>

## Example: personal top-up

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

## Example: team top-up

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

```typescript SDK theme={null}
// Fund the team pool. Admins with `manageBilling` can call this; any
// other scope returns 403.
const { checkout_url } = await theo.billingCheckout({
  amount_cents: 10_000,
  scope: "org",
});
window.open(checkout_url, "_blank");
```

## Response

```json theme={null}
{
  "checkout_url": "https://checkout.hitheo.ai/...",
  "scope": "org"
}
```

## Errors

| Status | Code                           | Meaning                                                                         |
| ------ | ------------------------------ | ------------------------------------------------------------------------------- |
| 400    | `missing_amount`               | `amount_cents` missing or not an integer.                                       |
| 400    | `amount_too_low`               | Below the \$5.00 minimum.                                                       |
| 400    | `amount_too_high`              | Above the \$1,000.00 maximum.                                                   |
| 400    | `org_context_required`         | Requested `scope: "org"` without an active team.                                |
| 402    | `team_payment_method_required` | Team key creation blocked until the team funds billing. Retry after a checkout. |
| 403    | `permission_denied`            | Caller lacks `manageBilling` in the active team.                                |
| 503    | `billing_unavailable`          | Billing isn't configured on this deployment.                                    |

## Lifecycle

1. Client calls this endpoint with `amount_cents` and optional `scope`.
2. The billing service reserves the right customer (personal or team),
   creates a checkout session, and returns `checkout_url`.
3. The user completes checkout.
4. A background webhook routes the top-up to the correct credit pool
   (user vs team) and marks the customer as having a payment method on
   file.
5. Subsequent API usage drafts from the funded pool.