---
title: "Top up hosted credits through the configured Stripe rail"
method: POST
path: "/v1/billing/topup"
tags: ["billing"]
---

# Top up hosted credits through the configured Stripe rail

`POST /v1/billing/topup`

## Request

- Base URL: `https://api.runx.ai`
- URL: `https://api.runx.ai/v1/billing/topup`
- Auth: HTTP bearer

## Request body

- BillingTopupRequest
  - `amount` integer, required
  - `idempotency_key` string

## Response `200`

Idempotent topup replay.

- BillingTopupEnvelope
  - `status` 'applied' | 'already_applied', required
  - `balance` integer, required
  - `credited` integer, required
  - `debited` integer, required
  - `receipt_id` string, required

## Other responses

- `201`: Topup applied.
- `400`: Validation error.
- `401`: Unauthorized.
- `402`: Stripe charge refused.
- `503`: Topup is not configured.

---

[API](https://skmtc.dev/runx/apis/runx-hosted-api.md) · [All operations](https://skmtc.dev/runx/apis/runx-hosted-api/llms.txt) · [OpenAPI document](https://skmtc.dev/runx/apis/runx-hosted-api/revisions/6c940d8edacc?raw)