Sign in
Space Balance

Top up the balance

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 returns the ids to charge.

Permissions

Authenticate with a Personal access token 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.

post/api/space/balance/top_ups

Headers

Idempotency-Keystring required

A key you generate that makes the top-up safe to retry. Reusing it with the same body replays the original top-up; reusing it with a different body is rejected.

Request body

amount_in_microdollarsinteger 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_idstring uuid required

Universal Unique Identifier.

Example request

{
  "amount_in_microdollars": 25000000
}

Response

The request has succeeded.

type'balance_adjustment' required

The object type. Always balance_adjustment.

idstring uuid required

Universal Unique Identifier.

kindstring 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_microdollarsinteger required

The signed amount in microdollars. Credits and debits carry the sign they were recorded with.

amountnumber double required

The same amount in US dollars.

created_atstring date-time required

The date and time when the adjustment was recorded.

payment_method_last4string nullable required

The last four digits of the card that was charged, or null when the adjustment was not charged to a card.

Example response

{
  "type": "balance_adjustment",
  "kind": "balance_top_up",
  "amount_in_microdollars": 25000000,
  "amount": 25,
  "created_at": "2026-08-20T14:19:00Z",
  "payment_method_last4": "4242"
}

Changes

Changed in 1 of the 161 revisions of this API.1

Of the 161 revisions, 3 have a changelog that could not be searched.