Wallet balance
Read a workspace's wallet balance, for example before buying a domain.
Every workspace pays from one wallet. Read its balance to check that a purchase will go through before you make it, or to alert someone when it runs low.
GET https://api.cloud.simplifyd.com/v1/workspaces/{workspace}/balanceCall it with a workspace token (sk_ws_…). Any workspace token can read the balance of its own workspace, whatever its scopes. A project token (sk_proj_…) is refused.
The balance can be read, not changed: a token cannot fund the wallet. Top it up in the console, under Settings → Billing.
Path parameters
| Parameter | Description | |
|---|---|---|
workspace | Required | The workspace's id. See how resources are addressed. A script holding only the token can get it from GET /v1/auth/scope. |
curl https://api.cloud.simplifyd.com/v1/workspaces/$WORKSPACE/balance \
-H "Authorization: Bearer $SIMPLIFYD_WORKSPACE_TOKEN"const response = await fetch(
`https://api.cloud.simplifyd.com/v1/workspaces/${workspace}/balance`,
{ headers: { Authorization: `Bearer ${process.env.SIMPLIFYD_WORKSPACE_TOKEN}` } },
);
const { balance, currency, suspended } = await response.json();req, _ := http.NewRequestWithContext(ctx, http.MethodGet,
"https://api.cloud.simplifyd.com/v1/workspaces/"+workspace+"/balance", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SIMPLIFYD_WORKSPACE_TOKEN"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
return err
}
defer resp.Body.Close()
var wallet struct {
Balance int64 `json:"balance"`
Currency string `json:"currency"`
Suspended bool `json:"suspended"`
}
err = json.NewDecoder(resp.Body).Decode(&wallet)Response
200 OK
{
"workspace": "0192e7a0-55c1-7b3e-8f2d-4a1b6c9d0e12",
"balance": 125005000,
"currency": "NGN",
"suspended": false,
"negative_balance_allowed": false
}| Field | Description |
|---|---|
workspace | The workspace's id. |
balance | What is in the wallet, as an integer in ten-thousandths of the currency: for NGN that is centiKobo, ₦1 = 10,000. 125005000 is ₦12,500.50. It can be negative. |
currency | The wallet's currency, NGN or USD. |
suspended | true when billing has stopped the workspace's services for an unpaid balance. While it is, deploys and other paid actions answer 402. |
negative_balance_allowed | true when the workspace has been allowed to keep running below zero instead of being suspended. |
balance is in the same unit as domain prices, so the two compare directly. A purchase goes through when balance is at least the quote's total:
if (balance < quote.total) {
throw new Error(`top up the wallet: it is short by ₦${(quote.total - balance) / 10_000}`);
}The balance moves as running services are billed, so it can fall between reading it and spending it. When a purchase finds the wallet short, it charges nothing and answers 400.
Errors
| Status | Meaning |
|---|---|
401 | The token is missing, malformed or deleted. |
403 | The token is a project token, or a workspace token made for a different workspace. |
404 | The token's creator is no longer a member of the workspace. Signed in to the console, it also means no workspace you belong to has that id. |
