---
title: "Create Topup Session"
method: POST
path: "/v1/billing/topup-session"
tags: ["billing"]
---

# Create Topup Session

`POST /v1/billing/topup-session`

## Request

- Base URL: `https://api.evidenso.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.evidenso.com/v1/billing/topup-session`
- Auth: HTTP bearer

Open Stripe Checkout to buy a one-off bundle of credits. Admin-only.

Same shape as create_portal_session above, and for the same reasons:
org-admin via org_api's require_org_admin (billing is an admin surface,
with one definition of "org admin"), and every lookup keyed on
`admin["organization_id"]` rather than the caller's uid — the user-keyed
billing query answers "this user's first organization", so for a user with
two membership rows it would sell credits into the wrong org's balance.

THREE refusals, and the third is a product rule rather than a technical
one:

  * EXEMPT -> 409. An exempt organization is outside credits entirely; it
    has no balance to top up, and `grant` would refuse the money on
    arrival anyway.
  * NOT CONFIGURED -> 503. No secret key, or no STRIPE_TOPUP_PRICE_ID:
    this environment cannot sell credits, which is a deployment fact and
    not the customer's fault.
  * BLOCKED -> 409. A lapsed organization cannot buy credits. Credits
    never substitute for a subscription, so an admin whose access the gate
    is refusing would be paying real money for credits they cannot spend.
    Taking that payment is worse than refusing it: they must fix the
    subscription first, which "Manage billing" (unblocked, deliberately)
    is right there to do. This is a settled decision, not a convenience
    check.

## Response `200`

Successful Response

- TopupSessionResponse
  - `url` string, required

---

[API](https://skmtc.dev/evidenso/apis/persona-rag-api.md) - [All operations](https://skmtc.dev/evidenso/apis/persona-rag-api/llms.txt) - [OpenAPI document](https://skmtc.dev/evidenso/apis/persona-rag-api/revisions/86408c178d4f?raw)