# API: Billing

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/billing` | The organization's plan, subscription, seats and this month's usage against the plan's allowance (recording hours, AI credits) | `billing:read` |
| POST | `/v1/billing/checkout` | Start a Paddle checkout for a paid plan (owners). Returns the checkout URL to open; the plan applies when Paddle confirms payment (web app only) | `billing:write` |
| GET | `/v1/billing/invoices` | Invoices from Paddle, newest first, with tax shown separately (owners) | `billing:write` |
| GET | `/v1/billing/invoices/:id/pdf` | A short-lived link to one invoice's PDF (owners) | `billing:write` |
| POST | `/v1/billing/plan` | Change to another paid plan or billing interval now, prorated (owners) (web app only) | `billing:write` |
| POST | `/v1/billing/portal` | A short-lived link to Paddle's customer portal: update the payment method, cancel, billing details (owners) (web app only) | `billing:write` |
| GET | `/v1/billing/prices` | Plan prices for a location with the sales tax or VAT Paddle collects (tax-inclusive totals when billing is on) | `billing:read` |
| POST | `/v1/billing/seats/sync` | Set the subscription's seats to the current member count, prorated (owners; also runs daily) | `billing:write` |
| POST | `/v1/billing/upgrade-link` | For agents: suggest a paid plan to the organization's owners. Returns a link to the billing page with the plan filled in, for an owner to review and pay; nothing is bought here, and the owners are notified (naming the key or app that asked) | `agents:write` |
| GET | `/v1/billing/upgrade-link/check` | Whether an agent suggested this plan to the organization in the last 7 days (the billing page checks before showing it) | `billing:read` |

## Examples

### GET /v1/billing

The organization's plan, subscription, seats and this month's usage against the plan's allowance (recording hours, AI credits)

```bash
curl -s "https://api.closefinch.com/v1/billing" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/billing`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/billing/invoices

Invoices from Paddle, newest first, with tax shown separately (owners)

```bash
curl -s "https://api.closefinch.com/v1/billing/invoices" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/billing/invoices`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/billing/invoices/$ID/pdf

A short-lived link to one invoice's PDF (owners)

```bash
curl -s "https://api.closefinch.com/v1/billing/invoices/$ID/pdf" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/billing/invoices/${id}/pdf`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/billing/prices

Plan prices for a location with the sales tax or VAT Paddle collects (tax-inclusive totals when billing is on)

```bash
curl -s "https://api.closefinch.com/v1/billing/prices" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/billing/prices`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### POST /v1/billing/seats/sync

Set the subscription's seats to the current member count, prorated (owners; also runs daily)

```bash
curl -s -X POST "https://api.closefinch.com/v1/billing/seats/sync" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/billing/seats/sync`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### POST /v1/billing/upgrade-link

For agents: suggest a paid plan to the organization's owners. Returns a link to the billing page with the plan filled in, for an owner to review and pay; nothing is bought here, and the owners are notified (naming the key or app that asked)

```bash
curl -s -X POST "https://api.closefinch.com/v1/billing/upgrade-link" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/billing/upgrade-link`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### GET /v1/billing/upgrade-link/check

Whether an agent suggested this plan to the organization in the last 7 days (the billing page checks before showing it)

```bash
curl -s "https://api.closefinch.com/v1/billing/upgrade-link/check" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/billing/upgrade-link/check`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

Request and response schemas: [https://www.closefinch.com/openapi.json](https://www.closefinch.com/openapi.json). All resources: [API reference](https://www.closefinch.com/docs/api).