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

# credits

> Balance, top-ups, ledger, and the plan — client.credits. Integer micro-USD, always.

Six methods. Every monetary value is **integer micro-USD** — the client never exposes a float and never converts to dollars; formatting is your presentation decision. API detail: [Credits](/docs/api/credits).

## show

```ts theme={"system"}
client.credits.show(): Promise<Balance>
```

`GET /v1/credits/balance`:

```json theme={"system"}
{ "object": "credit_balance", "balance_micro_usd": 79416537, "mode": "test" }
```

`79416537` micro-USD is \$79.416537.

## topup

```ts theme={"system"}
client.credits.topup(amountMicroUsd: number): Promise<Topup>
```

`POST /v1/credits/topups`, body `{ amount_micro_usd }`. Opens a hosted checkout and credits **nothing** — only the verified provider callback moves the balance. Send the person to the returned URL.

## ledger

```ts theme={"system"}
client.credits.ledger(query?: LedgerFilter): Promise<Page<LedgerEntry>>
```

`GET /v1/credits/ledger`. `LedgerFilter` extends the [page query](/docs/sdk/pagination) with `type` (`"debit" | "credit"`), `session_id`, `agent_id`, `deployment_id`, `from`, and `to` — every movement, attributable to what spent it.

## subscription

```ts theme={"system"}
client.credits.subscription(): Promise<Subscription>
```

`GET /v1/credits/subscription` — the plan, which is the right to use the organization at all:

```json theme={"system"}
{ "object": "subscription", "status": "none", "current_period_end": null, "grace_until": null, "cancel_at_period_end": false, "action_url": null }
```

`status` is `none | active | past_due | canceled`. Every route outside billing answers `402 subscription_required` until it reads `active`. While `past_due`, `grace_until` is the moment the organization stops working. `action_url` is `null` on a read.

## subscribe

```ts theme={"system"}
client.credits.subscribe(): Promise<Subscription>
```

`POST /v1/credits/subscription`. Opens the hosted checkout for the plan — send the person to `action_url`; nothing changes until the signed callback lands.

```ts theme={"system"}
const plan = await client.credits.subscription();
if (plan.status !== "active") {
  const { action_url } = await client.credits.subscribe();
}
```

## cancelSubscription

```ts theme={"system"}
client.credits.cancelSubscription(): Promise<Subscription>
```

`DELETE /v1/credits/subscription`. Stops the plan **at the end of the period already paid for** — never immediately. The state follows the provider's callback, so the answer reports the request, not a completed change (`cancel_at_period_end: true`).

## billingPortal

```ts theme={"system"}
client.credits.billingPortal(): Promise<{ object: "billing_portal_session"; action_url: string }>
```

`POST /v1/credits/billing_portal`. Returns a link to the payment provider's own hosted account page — change the card, download invoices, cancel. Send the person to `action_url`; it is single-use and expires, so mint one per visit rather than caching it.

```ts theme={"system"}
const { action_url } = await client.credits.billingPortal();
```

An organization that has never held a plan has no account to manage: the call throws `ApiError` with `code` `not_found`. Catch it and offer `subscribe()` instead.