<!-- Source: https://docs.geopera.com/api-reference/operations/billing · Markdown for LLMs -->

<!-- AUTO-GENERATED by scripts/generate-api-reference.cjs from the committed OpenAPI spec. Do not edit by hand. -->

# Billing operations

Credits, top-ups, invoices, and payment.

Each operation below is reachable at `POST /v1/op/{operation_id}` or the resource path `POST /v1/{resource}/{action}`, with a Bearer token (a `gpra_` API key or a session token). Back to the [Operations Reference](/api-reference/operations) index.

## `billing.approvals.approve`

Approve a credit purchase and charge the saved card (human approver only).

| | |
|---|---|
| **Scope** | `billing:write` |
| **Side-effect** | spend — accepts an `Idempotency-Key` header |
| **HTTP** | `POST /v1/op/billing.approvals.approve`  ·  `POST /v1/billing/approvals/approve` |
| **Python / TypeScript** | `client.billing.approvals.approve(…)` |
| **CLI** | `geopera billing approvals approve …` |

**Request** — `ApprovalRefInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `approval_id` | string | yes |  |

**Response** — `ApprovalOutput`.

## `billing.approvals.get`

Get one credit-purchase approval (org-scoped).

| | |
|---|---|
| **Scope** | `billing:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/billing.approvals.get`  ·  `POST /v1/billing/approvals/get` |
| **Python / TypeScript** | `client.billing.approvals.get(…)` |
| **CLI** | `geopera billing approvals get …` |

**Request** — `ApprovalGetInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `approval_id` | string | yes |  |

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `billing.approvals.list`

List the org's credit-purchase approvals (optionally by status).

| | |
|---|---|
| **Scope** | `billing:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/billing.approvals.list`  ·  `POST /v1/billing/approvals/list` |
| **Python / TypeScript** | `client.billing.approvals.list(…)` |
| **CLI** | `geopera billing approvals list …` |

**Request** — `ApprovalsListInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | — |  |

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `billing.approvals.reject`

Reject a pending credit-purchase approval.

| | |
|---|---|
| **Scope** | `billing:write` |
| **Side-effect** | compute |
| **HTTP** | `POST /v1/op/billing.approvals.reject`  ·  `POST /v1/billing/approvals/reject` |
| **Python / TypeScript** | `client.billing.approvals.reject(…)` |
| **CLI** | `geopera billing approvals reject …` |

**Request** — `RejectApprovalInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `approval_id` | string | yes |  |
| `reason` | string | — |  |

**Response** — `ApprovalOutput`.

## `billing.approvals.request`

Request approval for a large credit purchase.

| | |
|---|---|
| **Scope** | `billing:write` |
| **Side-effect** | compute |
| **HTTP** | `POST /v1/op/billing.approvals.request`  ·  `POST /v1/billing/approvals/request` |
| **Python / TypeScript** | `client.billing.approvals.request(…)` |
| **CLI** | `geopera billing approvals request …` |

**Request** — `RequestApprovalInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `credits` | integer | yes |  |
| `expiry_hours` | integer | — |  |

**Response** — `ApprovalOutput`.

## `billing.auto_topup.get`

Read the org's auto-topup settings (enabled=false if unset).

| | |
|---|---|
| **Scope** | `billing:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/billing.auto_topup.get`  ·  `POST /v1/billing/auto_topup/get` |
| **Python / TypeScript** | `client.billing.auto_topup.get(…)` |
| **CLI** | `geopera billing auto-topup get …` |

**Request** — `_Empty` _(see the OpenAPI schema for fields)_.

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `billing.credits.balance`

The org's current credit balance.

| | |
|---|---|
| **Scope** | `billing:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/billing.credits.balance`  ·  `POST /v1/billing/credits/balance` |
| **Python / TypeScript** | `client.billing.credits.balance(…)` |
| **CLI** | `geopera billing credits balance …` |

**Request** — `_Empty` _(see the OpenAPI schema for fields)_.

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `billing.credits.transactions`

The org's credit ledger (paged, optionally filtered by reason).

| | |
|---|---|
| **Scope** | `billing:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/billing.credits.transactions`  ·  `POST /v1/billing/credits/transactions` |
| **Python / TypeScript** | `client.billing.credits.transactions(…)` |
| **CLI** | `geopera billing credits transactions …` |

**Request** — `TransactionsInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `limit` | integer | — |  |
| `offset` | integer | — |  |
| `reason` | string | — |  |

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `billing.invoices.list`

The org's enterprise invoices (grouped from settled orders).

| | |
|---|---|
| **Scope** | `billing:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/billing.invoices.list`  ·  `POST /v1/billing/invoices/list` |
| **Python / TypeScript** | `client.billing.invoices.list(…)` |
| **CLI** | `geopera billing invoices list …` |

**Request** — `InvoicesInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `limit` | integer | — |  |

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `billing.plans.list`

List all available plans with their quota/feature limits (public catalog).

| | |
|---|---|
| **Scope** | `billing:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/billing.plans.list`  ·  `POST /v1/billing/plans/list` |
| **Python / TypeScript** | `client.billing.plans.list(…)` |
| **CLI** | `geopera billing plans list …` |

**Request** — `_Empty` _(see the OpenAPI schema for fields)_.

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `billing.run_monthly_for_org`

Run monthly billing for one org (manual; org admin).

| | |
|---|---|
| **Scope** | `billing:write` |
| **Side-effect** | spend — accepts an `Idempotency-Key` header |
| **HTTP** | `POST /v1/op/billing.run_monthly_for_org`  ·  `POST /v1/billing/run_monthly_for_org` |
| **Python / TypeScript** | `client.billing.run_monthly_for_org(…)` |
| **CLI** | `geopera billing run-monthly-for-org …` |

**Request** — `OrgInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `organization_id` | string | yes |  |

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `billing.set_auto_topup`

Configure automatic top-up (requires a default card when enabling).

| | |
|---|---|
| **Scope** | `billing:write` |
| **Side-effect** | compute |
| **HTTP** | `POST /v1/op/billing.set_auto_topup`  ·  `POST /v1/billing/set_auto_topup` |
| **Python / TypeScript** | `client.billing.set_auto_topup(…)` |
| **CLI** | `geopera billing set-auto-topup …` |

**Request** — `SetAutoTopupInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `enabled` | boolean | yes |  |
| `threshold_credits` | integer | yes |  |
| `topup_amount_credits` | integer | yes |  |
| `daily_charge_cap_aud` | number | — |  |

**Response** — `SetAutoTopupOutput`.

## `billing.status.get`

An org's billing status + current usage (org membership required).

| | |
|---|---|
| **Scope** | `billing:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/billing.status.get`  ·  `POST /v1/billing/status/get` |
| **Python / TypeScript** | `client.billing.status.get(…)` |
| **CLI** | `geopera billing status get …` |

**Request** — `OrgStatusInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `organization_id` | string | yes |  |

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `billing.stripe_invoices.list`

List the org's Stripe invoices (never 500s — empty on a Stripe hiccup).

| | |
|---|---|
| **Scope** | `billing:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/billing.stripe_invoices.list`  ·  `POST /v1/billing/stripe_invoices/list` |
| **Python / TypeScript** | `client.billing.stripe_invoices.list(…)` |
| **CLI** | `geopera billing stripe-invoices list …` |

**Request** — `InvoicesInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `limit` | integer | — |  |

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `billing.topup`

Invoke Billing Topup.

| | |
|---|---|
| **Scope** | `billing:write` |
| **Side-effect** | spend — accepts an `Idempotency-Key` header |
| **HTTP** | `POST /v1/op/billing.topup`  ·  `POST /v1/billing/topup` |
| **Python / TypeScript** | `client.billing.topup(…)` |
| **CLI** | `geopera billing topup …` |

**Request** — a free-form JSON object.