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

# Create Topup

`POST /billing/topup`

Create a credit top-up checkout for a user-chosen whole-dollar amount.

The amount is validated by ``TopupRequest`` (1–500). The top-up product is
$1/unit so we pass ``quantity = amount_dollars``; the ``payment.succeeded``
webhook credits ``topup_cents`` to the local balance.

## Request body

- TopupRequest — Body for POST /billing/topup. ``amount_dollars`` is the whole-dollar credit amount the user chose. Dodo charges by product×quantity (there is no arbitrary-price field on a checkout session), so the top-up product is priced at $1 and we pass ``quantity = amount_dollars``. Bounded 1–500 to keep a single payment sane; the UI offers presets ($5/$10/$25/$50) plus a custom field. Defaults to 5 so a body that omits the field preserves the historical "$5 top-up" behaviour for any un-migrated caller.
  - `return_url` string, required
  - `amount_dollars` integer
  - `cancel_url` string, nullable

## Response `200`

Successful Response

- BillingCheckoutResponse
  - `checkout_url` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/repowise/apis/repowise-hosted-api.md) · [All operations](https://skmtc.dev/repowise/apis/repowise-hosted-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/repowise/repowise-hosted-api/revisions/1e57283a9737/schema)