Skip to main content
PATCH
Reallocate Credit Balances
Use it to distribute a top-up made on the primary across clients or teams, or to pull unused balance back from one Ringg Space to fund another.

Rules

  • The net amount moving out of the primary’s pot cannot exceed what the pot holds. Top up on the primary first, then allocate.
  • A Ringg Space with a 0 balance cannot place calls; Ringg Spaces have no overdraft.
  • Every move is recorded in the workspace ledgers as a transfer, never as a charge.
  • In a common-billing family the wallet is shared on the primary and Ringg Spaces hold nothing, so this endpoint returns 400. Allocate concurrency instead.

Notes

  • Read the current wallets and family.available_pot from Get Ringg Spaces first, then send the full map.
  • Amounts in the request can be JSON numbers (200000) or numeric strings ("200000.00"); they are rounded to two decimals.
  • Amounts in the response are decimal strings ("5000.00"), unlike the read endpoints.

Errors

  • 400: Balance allocation applies to prepaid families only.
  • 400: This family uses a shared balance; per-sub wallets do not exist.
  • 400: allocations name workspaces that are not active sub-workspaces of this family: [...]
  • 400: allocations must cover every active sub-workspace; missing: [...]
  • 400: These allocations need 9000.00 from the primary's pot, which only holds 4000.00. Lower the allocations or add balance to the primary workspace first.
  • 401: Invalid or missing API key.
  • 403: Sub-workspaces are not enabled for this workspace. — Ringg Spaces are not enabled on the primary, or the key belongs to a Ringg Space.
  • 404: Workspace is not a sub-workspace family parent. — the primary has no Ringg Spaces yet.
  • 422: Empty map, negative value, or a key that is not a UUID.

Authorizations

X-API-KEY
string
header
required

Headers

X-API-KEY
string
required

(Required) The API key of the PRIMARY workspace. A Ringg Space's own key is refused (403, or 400 if Ringg Spaces are enabled on it).

Example:

"rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Body

application/json
allocations
object
required

(Required) sub_workspace_id -> the Ringg Space's NEW absolute balance (not a delta). Must include every active Ringg Space exactly once. Values >= 0, two decimals. Values may be JSON numbers (200000) or numeric strings ("200000.00").

Response

Successful Response: The applied balances. Amounts are decimal strings.

parent_workspace_id
string
Example:

"00000000-0000-4000-8000-000000000107"

parent_available_balance
string

The primary's unallocated pot after the move, as a decimal string.

Example:

"12000.00"

allocations
object
Example:
primary
object