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

# Billing

> Subscriptions, invoices, credits, model costs, and external costs.

## `paygent billing overview`

The dashboard's headline numbers, in a terminal.

```bash
paygent billing overview
```

## `paygent billing subscription`

Create and manage subscriptions. The API calls these orders.

```bash
paygent billing subscription list
paygent billing subscription get "Acme 2026"
```

```bash
paygent billing subscription create --customer acme --name "Acme 2026" \
  --billing-day 1 --start-date 2026-08-01 \
  --line-item "agent=support-bot,plan=Starter,seats=10" --no-end-date
```

| Flag                                           | Description                                          |
| ---------------------------------------------- | ---------------------------------------------------- |
| `--customer <c>`                               | Who is subscribing. Required.                        |
| `--name <name>`                                | Subscription name. Required.                         |
| `--start-date <date>`                          | First billing date, `YYYY-MM-DD`. Required.          |
| `--billing-day <n>`                            | Day of month to bill on, 1–31.                       |
| `--line-item <spec>`                           | `agent=<ref>[,plan=<name>][,seats=<n>]`. Repeatable. |
| `--end-date`, `--term-months`, `--no-end-date` | Exactly one is required.                             |

Cancel by setting an end date. Nothing is deleted.

```bash
paygent billing subscription cancel "Acme 2026" --end-date 2026-12-31
```

> **Info**
>
> `--billing-day` values of 29–31 are normalized for short months, so 31 bills on 28 February.

## `paygent billing invoice`

Invoices are generated nightly and are read-only.

```bash
paygent billing invoice list
paygent billing invoice get <invoice-id>
paygent billing invoice lines <invoice-id>
paygent billing invoice download <invoice-id> --out invoice.pdf
```

`download` returns binary and will not write to a terminal, so `--out` is required.

## `paygent billing credit`

Credit currencies — your own unit of account that wallets are denominated in.

```bash
paygent billing credit list
paygent billing credit create --name "Tokens" --key tokens --rate 0.001
```

| Flag            | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| `--name <name>` | Display name. Required.                                          |
| `--key <key>`   | Stable handle. Lowercase letters, digits, underscores. Required. |
| `--rate <n>`    | Suggested USD value of one unit.                                 |
| `--type <type>` | `credit` (default) or `entitlement`. A grouping label only.      |

Also `get`, `update`, and `delete`.

## `paygent billing model`

Custom model **cost** rates — what the provider charges you, not what you charge a customer.

```bash
paygent billing model list
paygent billing model metadata
paygent billing model create --provider anthropic --model claude-opus-5 \
  --type llm --input-per-1k 0.005 --output-per-1k 0.025
```

> **Warning**
>
> `create` is an upsert. An existing provider/model pair is replaced. The CLI checks first and asks; `--upsert` skips the check.

Use `bulk --from-file` to load many at once, and `delete` to revert to the built-in registry.

## `paygent billing external-cost`

Cost streams that originate outside Paygent — a third-party API, a human review step, a licence fee.

```bash
paygent billing external-cost list
paygent billing external-cost create --name "Translation API" --external-id deepl
paygent billing external-cost usage
```

Also `get`, `update`, and `delete`.

## `paygent billing external-config`

Prices an external cost stream.

```bash
paygent billing external-config create --cost deepl --name "Per character" \
  --billing-type PER_UNIT --unit-field characters --price 0.00002
```

| Flag                    | Description                                                      |
| ----------------------- | ---------------------------------------------------------------- |
| `--cost <cost>`         | The external cost to price. Required.                            |
| `--name <name>`         | Config name. Required.                                           |
| `--billing-type <type>` | `FLAT` charges once per event; `PER_UNIT` multiplies by a field. |
| `--unit-field <field>`  | The event field to multiply by. Required for `PER_UNIT`.         |
| `--price <n>`           | Charge per event, or per unit.                                   |

An external cost with no config is tracked but never billed.