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 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
`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
`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.