Start a credit top-up Checkout flow

POST

/api/v1/billing/topup

curl --request POST \
  --url https://api.ultimateteam.ai/api/v1/billing/topup \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "credit_pack_size": 1 }'

• Production
• Local development

Create a Stripe Checkout Session for the per-plan credit top-up price ($40/1K Starter, $30/1K Professional, $20/1K Business). Enterprise tenants receive 403 – Enterprise top-ups are custom-negotiated.

Authorizations

• ApiKeyAuth

Request Body^required

Media typeapplication/json

TopupRequest

Request body for POST /api/v1/billing/topup (FIN-04).

Attributes: credit_pack_size: Total credits to purchase. Must be a positive multiple of 1000 – the Stripe Product is priced per-1000 and quantity is derived as credit_pack_size // 1000.

object

credit_pack_size

required

Credit Pack Size

Total credits to purchase (must be a positive multiple of 1000)

integer

> 0

Example^generated

{
  "credit_pack_size": 1
}

Responses

200

Successful Response

Media typeapplication/json

TopupResponse

Response for POST /api/v1/billing/topup.

Attributes: checkout_url: The hosted Stripe Checkout URL – frontend redirects the tenant here to complete payment. session_id: The Stripe Checkout Session ID. Primary idempotency key for the checkout.session.completed webhook handler.

object

checkout_url

required

Checkout Url

string

session_id

required

Session Id

string

Example^generated

{
  "checkout_url": "example",
  "session_id": "example"
}

422

Validation Error

Media typeapplication/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

ctx

Context

object

input

Input

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

Example^generated

{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}