> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://gtm-tools.sh/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://gtm-tools.sh/_mcp/server.

# Billing Tools

> The Billing category gets API keys, tracks credit balances, charges cards, exposes invoice history, and manages seats, usage, and top-up requests. Every paid tool consults this layer to authorize requests and meter usage.

The Billing category is the auth and wallet layer behind every paid tool. It gets you an API key, tracks your credit balance, tops up via card, and lists invoice history. Every paid tool consults this layer to authorize requests and meter usage.

> **Note**
>
> All Billing tools are free: the wallet itself never consumes credits. New accounts start with 100 free credits (\$1 = 100 credits).

## Tools

| Tool                  | Credits | Description                                                                       |
| --------------------- | ------- | --------------------------------------------------------------------------------- |
| `get_api_key`         | 0       | Get an API key (sends a verification code to email)                               |
| `get_credit_balance`  | 0       | Get your credit balance and per-tool costs                                        |
| `buy_credits`         | 0       | Buy credits via card (\$1 = 100 credits, min \$5)                                 |
| `set_auto_reload`     | 0       | Set auto-reload to top up the saved card when balance is low                      |
| `get_billing_portal`  | 0       | Get a Stripe billing-portal link to manage cards and receipts                     |
| `list_invoices`       | 0       | List purchase and charge history                                                  |
| `list_api_keys`       | 0       | List the workspace's API keys (values obfuscated)                                 |
| `revoke_api_key`      | 0       | Revoke a specific API key by ID                                                   |
| `get_usage`           | 0       | Get workspace credit usage for the current cycle                                  |
| `get_usage_limits`    | 0       | Every limit that applies right now, what is left of each, and what to do about it |
| `get_org_usage`       | 0       | Every member's share of the pool, and who is at the wall                          |
| `get_spend_controls`  | 0       | Your monthly ceiling and alert thresholds                                         |
| `set_spend_controls`  | 0       | Set or raise that ceiling                                                         |
| `get_plan`            | 0       | The current plan, what it can move to, and any pending request                    |
| `preview_plan_change` | 0       | What a plan change would cost, before committing                                  |
| `change_plan`         | 0       | Move up, down, or off                                                             |
| `request_plan_change` | 0       | Ask an owner to move the workspace up a plan                                      |

## get_api_key

Get a new API key. A verification email is sent to the address you provide; calling `get_api_key` again with the code finalizes the key.

| Parameter | Type   | Required | Description                                   |
| --------- | ------ | -------- | --------------------------------------------- |
| `email`   | string | Yes      | Destination address for the verification link |

```bash
curl -X POST https://api.gtm-tools.sh/api/v0/get_api_key \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourcompany.com"}'
```

```json
{
  "status": "verification_sent",
  "email": "you@yourcompany.com"
}
```

After verification, the key (prefixed `sk_`) is returned. New accounts receive 100 free credits.

## get_credit_balance

Returns the current balance and the cost of every tool, grouped by server.

```bash
curl https://api.gtm-tools.sh/api/v0/get_credit_balance \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY"
```

```json
{
  "balance": 412,
  "tools": {
    "socials": {
      "get_linkedin_company_url": { "cost": 2 },
      "list_linkedin_company_employees": { "cost": 30 }
    },
    "data": {
      "get_email": { "cost": 5 }
    },
    "signals": {
      "signal_socials_spike": { "cost": 5 }
    }
  }
}
```

## buy_credits

Charge a saved card and credit credits.

| Parameter           | Type   | Required | Description                                       |
| ------------------- | ------ | -------- | ------------------------------------------------- |
| `amount`            | number | Yes      | Dollar amount (min 5)                             |
| `payment_method_id` | string | No       | Saved payment method ID (uses default if omitted) |

```bash
curl -X POST https://api.gtm-tools.sh/api/v0/buy_credits \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 25}'
```

## set_auto_reload

Configure automatic top-ups when the balance falls below a threshold.

| Parameter   | Type    | Required | Description                                            |
| ----------- | ------- | -------- | ------------------------------------------------------ |
| `enabled`   | boolean | Yes      | Turn auto-reload on or off                             |
| `threshold` | number  | No       | Trigger when the balance falls below this many credits |
| `reload_to` | number  | No       | Top the balance back up to this many credits           |

```bash
curl -X POST https://api.gtm-tools.sh/api/v0/set_auto_reload \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "threshold": 200, "reload_to": 5000}'
```

## list_invoices

Returns purchase and charge history.

```bash
curl https://api.gtm-tools.sh/api/v0/list_invoices \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY"
```

```json
{
  "invoices": [
    {
      "id": "in_1NkX...",
      "created_at": "2026-04-21T10:14:00Z",
      "amount_usd": 25,
      "tokens_credited": 2500,
      "status": "paid"
    }
  ]
}
```

## get_billing_portal

Returns a short-lived Stripe billing-portal URL where you can update the saved card, download receipts, and manage payment details in Stripe's hosted UI.

```bash
curl -X POST https://api.gtm-tools.sh/api/v0/get_billing_portal \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY"
```

```json
{ "url": "https://billing.stripe.com/p/session/..." }
```

## Managing API keys

`list_api_keys` shows every key in the workspace with its value obfuscated, so you can audit what exists without exposing secrets. `revoke_api_key` deletes a specific key by `api_key_id`, with a belongs-to check so a key can only revoke keys in its own workspace. The CLI wraps these as `gtm-tools admin keys list` and `gtm-tools admin keys revoke <id>`.

```bash
# List keys (values obfuscated)
curl https://api.gtm-tools.sh/api/v0/list_api_keys \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY"

# Revoke a specific key by ID
curl -X POST https://api.gtm-tools.sh/api/v0/revoke_api_key \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api_key_id": "key_..."}'
```

## Usage, and what to do when it runs out

**There are no seats here.** Every plan is a flat subscription over ONE shared pool of
credits — a workspace's members and its API keys all draw on the same balance — so there is
no per-member pack to size, no seat to assign, and no per-member top-up to request. The
billing engine reads that from the plan catalogue and simply does not register the tools
that would only ever refuse: `list_seats`, `assign_seat_type`, `request_seat_change` and the
whole `*_top_up` group are absent from `GET /api/v0` on this deployment. If you have seen
them in another product built on the same engine, that product sells seats and this one
does not.

`get_usage` returns what the workspace has spent this cycle, optionally filtered by caller.
`get_usage_limits` answers the more useful question — every limit that applies to you right
now, what is left of each, when it resets, and a `next_step` naming what to do if something
is refusing you. `get_org_usage` breaks the pool down by member: each row is that person's
share, `limit_shared: true` because the ceiling is the workspace's rather than theirs, and
`shared_pool` carries the pool once so nothing invites you to add the rows up.

```bash
# Usage this cycle (optionally filter by caller kind, or look back N days)
curl -X POST https://api.gtm-tools.sh/api/v0/get_usage \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"caller_kind": "api"}'

# What is left, and what to do about it
curl -X POST https://api.gtm-tools.sh/api/v0/get_usage_limits \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
  -H "Content-Type: application/json" -d '{}'
```

When the pool is spent, the overage draws the prepaid wallet rather than stopping an agent
mid-run — so the answer is credits, and `get_usage_limits` says so in `next_step`:

```json
{ "next_step": { "rung": "credits", "actor": "admin", "action": "buy_credits" } }
```

`action` is the name of the tool to call next. On a plan with nothing above it the rung
becomes `plan`, and a member without the standing to buy gets `request_plan_change` instead
— the same answer, addressed to whoever can act on it.

The CLI wraps these as `gtm-tools admin usage`, `admin limits` and `admin team-usage`.

## The wallet model

|                          | Value                                                                    |
| ------------------------ | ------------------------------------------------------------------------ |
| **Free starter balance** | 100 credits                                                              |
| **Exchange rate**        | \$1 = 100 credits                                                        |
| **Minimum top-up**       | \$5 (500 credits)                                                        |
| **Auto-reload**          | Optional: charges the saved card when balance drops below your threshold |

Every paid tool publishes its cost. When a tool is called, the cost is debited up front, before the tool runs.

## Next steps

#### [Pricing](/pricing)

Plans, and the credit cost of every tool.

#### [LinkedIn Tools](/linkedin-tools)

Spend your credits on LinkedIn automation.