# Credits

4 operations on the Logion v1 API.

- [Get credit balance](#get-credit-balance) — `GET /v1/credits/balance`
- [List credit ledger](#list-credit-ledger) — `GET /v1/credits/ledger`
- [Create credit top-up](#create-credit-top-up) — `POST /v1/credits/top-ups`
- [Get credit top-up](#get-credit-top-up) — `GET /v1/credits/top-ups/{top_up_id}`

## Get credit balance

```http
GET /v1/credits/balance
```

Operation id: `get_credit_balance`

Takes an [`Authorization`](/docs/api/overview#authentication) header.

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful response | `GetCreditBalanceResponse` |
| `401` | Unauthorized | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `GetCreditBalanceResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `balance_cents` | integer | yes |  |
| `currency_code` | string | no | default `"USD_CREDIT"` |

## List credit ledger

```http
GET /v1/credits/ledger
```

Operation id: `list_credit_ledger`

Takes an [`Authorization`](/docs/api/overview#authentication) header.

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful response | — |
| `401` | Unauthorized | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `ListCreditLedgerResponse[]`.

## Create credit top-up

```http
POST /v1/credits/top-ups
```

Operation id: `create_credit_top_up`

Takes an [`Authorization`](/docs/api/overview#authentication) header.

**Request body**

Body `CreateCreditTopUpRequest`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `amount_cents` | integer | yes |  |
| `currency` | string | no | default `"usd"` |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `201` | Credit top-up checkout created | `CreateCreditTopUpResponse` |
| `400` | Unsupported currency | `ErrorResponse` |
| `401` | Unauthorized | `ErrorResponse` |
| `404` | User not found | `ErrorResponse` |
| `422` | Invalid top-up amount | `ErrorResponse` |
| `503` | Payment configuration unavailable | `ErrorResponse` |

Returns `CreateCreditTopUpResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `amount_cents` | integer | yes |  |
| `charge_amount_minor` | integer | yes |  |
| `charge_currency` | string | yes |  |
| `checkout_url` | string, optional | no |  |
| `credit_cents_granted` | integer | yes |  |
| `status` | enum("pending", "paid", "failed", "expired", "cancelled", "disputed", "reversed") | yes |  |
| `stripe_checkout_session_id` | string, optional | no |  |
| `top_up_id` | string(uuid) | yes |  |

**From the CLI**

- [`logion credits top-up`](/docs/cli/credits#logion-credits-top-up)

## Get credit top-up

```http
GET /v1/credits/top-ups/{top_up_id}
```

Operation id: `get_credit_top_up`

Takes an [`Authorization`](/docs/api/overview#authentication) header.

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `top_up_id` | path | string(uuid) | yes |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful response | `GetCreditTopUpResponse` |
| `401` | Unauthorized | `ErrorResponse` |
| `404` | Top-up not found | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `GetCreditTopUpResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `amount_cents` | integer | yes |  |
| `charge_amount_minor` | integer | yes |  |
| `charge_currency` | string | yes |  |
| `checkout_url` | string, optional | no |  |
| `credit_cents_granted` | integer | yes |  |
| `status` | enum("pending", "paid", "failed", "expired", "cancelled", "disputed", "reversed") | yes |  |
| `stripe_checkout_session_id` | string, optional | no |  |
| `top_up_id` | string(uuid) | yes |  |

**From the CLI**

- [`logion credits top-up`](/docs/cli/credits#logion-credits-top-up)
- [`logion credits top-ups get`](/docs/cli/credits#logion-credits-top-ups-get)
- [`logion credits top-ups wait`](/docs/cli/credits#logion-credits-top-ups-wait)