---
title: "Create a top-up checkout"
description: "Returns a hosted checkout URL with `amountCents` prefilled (editable there, $20 to $5,000). The balance is credited when the payment lands, within a minute, and tracking the wallet had paused resumes at once. Nothing is charged by this call itself. `successUrl` must be on an origin this deployment trusts; omit it for the dashboard's billing page."
canonical: https://docs.mentio.dev/api/billing/create-top-up
markdown: https://docs.mentio.dev/api/billing/create-top-up.mdx
---

# Create a top-up checkout

`POST /v1/billing/top-ups`

Returns a hosted checkout URL with `amountCents` prefilled (editable there, $20 to $5,000). The balance is credited when the payment lands, within a minute, and tracking the wallet had paused resumes at once. Nothing is charged by this call itself. `successUrl` must be on an origin this deployment trusts; omit it for the dashboard's billing page.

## Body

- `amountCents` (required): Amount to add, in USD cents (2000 to 500000). Prefilled at checkout, editable there.
- `successUrl`: Where the customer lands after paying: a page on an origin this deployment trusts (the dashboard). Omit it and the dashboard's billing page is used.

## Responses

- 200: Hosted checkout URL with the amount prefilled
- 400: Invalid amount or disallowed successUrl
- 401: Missing or invalid credentials
- 404: Workspace has no owner to bill
- 429: More than a few checkouts a minute for one workspace
- 503: Billing is not configured on this deployment

Full schemas: https://api.mentio.dev/v1/openapi.json. Conventions: https://docs.mentio.dev/conventions.mdx