---
title: "Start a top-up"
description: "Returns a hosted checkout link with `amountCents` filled in. The buyer can change it there, from $20 to $5,000. The balance is credited within a minute of payment, and tracking paused for balance resumes right away. This call charges nothing by itself. `successUrl` must be on an origin this deployment trusts. Leave it out to return to the dashboard's billing page."
canonical: https://docs.rumoro.dev/api/billing/create-top-up
markdown: https://docs.rumoro.dev/api/billing/create-top-up.mdx
---

# Start a top-up

`POST /v1/billing/top-ups`

Returns a hosted checkout link with `amountCents` filled in. The buyer can change it there, from $20 to $5,000. The balance is credited within a minute of payment, and tracking paused for balance resumes right away. This call charges nothing by itself. `successUrl` must be on an origin this deployment trusts. Leave it out to return to the dashboard's billing page.

## Body

| Field | Required | Description |
| --- | --- | --- |
| `amountCents` | yes | The amount to add in US cents, from 2000 to 500000. Checkout starts with it and the buyer can change it. |
| `successUrl` |  | Page to return to after payment. It must be on an origin this deployment trusts, like the dashboard, and defaults to the dashboard's billing page. |

## Responses

| Status | Meaning |
| --- | --- |
| 200 | A checkout link with the amount filled in |
| 400 | The amount is not valid, or successUrl is not allowed |
| 401 | The credential is missing or not valid |
| 404 | There is no workspace owner to bill |
| 429 | The workspace started too many checkouts in this minute |
| 503 | This deployment has no billing set up |

The [OpenAPI document](https://api.rumoro.dev/v1/openapi.json) has every schema. Rules shared by all endpoints are in [Conventions](https://docs.rumoro.dev/conventions.mdx).