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.
Authentication
Personal access token authentication for space-wide administration.
Send HTTP Basic auth with an empty username and the Personal access token as
the password. A Personal access token carries your own authority rather than a
project's: it is created from your user menu in the Dashboard, is prefixed
pat_, and has no scopes. The holder must be an owner or admin of the space
named by the subdomain, and the token acts only on that space.
Example:
Authorization: Basic base64(:pat_...)
Headers
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
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.
The payment method to charge. Must name a payment method on this space (payment_method_invalid). List them with List payment methods.
Response
The object type. Always balance_adjustment.
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.
The last four digits of the card that was charged, or null when the adjustment was not charged to a card.