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

# Billing

> Organization billing. Korve is paid-only and usage-based — nothing provisions before payment.

Organization billing. Korve is paid-only and usage-based — nothing provisions before payment.

## billing.get

Billing status and the current rate card for an organization.

```text theme={null}
GET /v1/orgs/{orgId}/billing
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `read`

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/billing" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description    |
| ------ | -------------- |
| `200`  | Billing state. |

### Response body (200)

| Field      | Type   | Description                                         |
| ---------- | ------ | --------------------------------------------------- |
| `status`   | string | One of: `unpaid`, `active`, `past_due`, `canceled`. |
| `rateCard` | object | —                                                   |

## billing.createCheckout

Start checkout to activate the organization. Returns a hosted payment URL.

```text theme={null}
POST /v1/orgs/{orgId}/billing/checkout
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `owner`
* **Risk:** `write`

### Request body (optional)

| Field        | Type   | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `successUrl` | string | No       | —           |
| `cancelUrl`  | string | No       | —           |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/billing/checkout" \
  -b "$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "successUrl": "https://acme.com/billing/success",
  "cancelUrl": "https://acme.com/billing/canceled"
}'
```

### Responses

| Status | Description                     |
| ------ | ------------------------------- |
| `200`  | Checkout session.               |
| `409`  | Organization is already active. |

### Response body (200)

| Field | Type   | Description |
| ----- | ------ | ----------- |
| `url` | string | —           |

## billing.confirm

Re-check payment state after checkout returns and activate the organization.

```text theme={null}
POST /v1/orgs/{orgId}/billing/confirm
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `member`
* **Risk:** `write`

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/billing/confirm" \
  -b "$SESSION"
```

### Responses

| Status | Description              |
| ------ | ------------------------ |
| `200`  | Refreshed billing state. |

### Response body (200)

| Field    | Type   | Description                                         |
| -------- | ------ | --------------------------------------------------- |
| `status` | string | One of: `unpaid`, `active`, `past_due`, `canceled`. |

## billing.portal

Open the hosted billing portal (manage subscription, invoices, cancel).

```text theme={null}
POST /v1/orgs/{orgId}/billing/portal
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `owner`
* **Risk:** `write`

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/billing/portal" \
  -b "$SESSION"
```

### Responses

| Status | Description     |
| ------ | --------------- |
| `200`  | Portal session. |

### Response body (200)

| Field | Type   | Description |
| ----- | ------ | ----------- |
| `url` | string | —           |