---
title: "Top up the balance"
method: POST
path: "/api/space/balance/top_ups"
tags: ["Space Balance"]
---

# Top up the balance

`POST /api/space/balance/top_ups`

Charges one of the space's payment methods and deposits the amount to the balance. The
minimum is 5,000,000 microdollars (5.00 USD), and the amount must be a whole number of
cents.

Every top-up needs an `Idempotency-Key` header, a key you generate, so the request is
safe to retry. Repeating a request with the same key and the same body replays the
original top-up and returns `200` with the same balance adjustment instead of charging
the card again; the first successful request returns `201`. The same key with a
different body is rejected with `400`, and a top-up still in flight for that key
returns `409`.

A declined card returns `422` with the processor's `decline_code` rather than the
standard validation body. Cards are added in the Dashboard;
[List payment methods](/docs/apis/rest/space/billing/list-payment-methods) returns the
ids to charge.

#### Permissions

Authenticate with a [Personal access token](/docs/apis/authorization#personal-access-tokens) whose holder is an owner or admin of the space. A project API token is not accepted on this endpoint, and a Personal access token has no scopes: the holder's role in the space is the whole authorization decision.

## Headers

- `Idempotency-Key` string, required

## Request body

- SpaceCreateTopUpRequest — Request body for charging a payment method and depositing the amount to the balance.
  - `amount_in_microdollars` integer, required — The amount to charge and deposit, in microdollars. At least 5,000,000 (5.00 USD) and a whole number of cents, so a multiple of 10,000.
  - `payment_method_id` string, uuid, required — Universal Unique Identifier.

## Response `200`

The request has succeeded.

- SpaceBalanceAdjustment — A change to the space balance: a top-up, an auto top-up, or a credit or debit applied by SignalWire.
  - `type` 'balance_adjustment', required — The object type. Always `balance_adjustment`.
  - `id` string, uuid, required — Universal Unique Identifier.
  - `kind` string, required — The kind of adjustment, for example `balance_top_up`, `auto_balance_top_up`, `balance_credit_by_signalwire`, `balance_debit_by_signalwire`, `coupon_code_credit`, or `sign_up_free_credit`.
  - `amount_in_microdollars` integer, required — The signed amount in microdollars. Credits and debits carry the sign they were recorded with.
  - `amount` number, double, required — The same amount in US dollars.
  - `created_at` string, date-time, required — The date and time when the adjustment was recorded.
  - `payment_method_last4` string, nullable, required — The last four digits of the card that was charged, or `null` when the adjustment was not charged to a card.

## Other responses

- `201` — The request has succeeded and a new resource has been created as a result.
- `400` — The `Idempotency-Key` header is missing (`Idempotency-Key header is required.`), the key was reused with a different body (`This Idempotency-Key was already used with different request parameters.`), or the request body is not valid JSON (`not_a_valid_json`).
- `401` — The credential is missing, unknown, or revoked; its holder is not a member of the space in the subdomain; or the member is not an owner or admin. The body is the plain text `Unauthorized`. An unverified space instead receives the JSON body `{"message": "Please validate a phone number to access your account."}` on every endpoint under `/api/space`.
- `409` — A top-up with the same `Idempotency-Key` is still in progress. Wait for it to finish, then replay the request with the same key to read its result.
- `422` — A validation failure, or a declined card. Validation codes: `amount_not_a_whole_number`, `amount_not_whole_cents`, `amount_below_minimum`, and `payment_method_invalid`. A decline returns the decline body instead, with the processor's `decline_code`.
- `500` — An internal server error occurred.
- `502` — An upstream billing service was unavailable and the deposit to the space balance could not be completed.

## Changes

> 161 revisions in range; 3 could not be searched.

- **2026-09-15** `45bac4fd93ab` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/signalwire/apis/signalwire-rest-api/changes/api/space/balance/top_ups/post.md)

---

[API](https://skmtc.dev/signalwire/apis/signalwire-rest-api.md) · [All operations](https://skmtc.dev/signalwire/apis/signalwire-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signalwire/apis/signalwire-rest-api/revisions/20ee0f568ece?raw)