> ## Documentation Index > Fetch the complete documentation index at: https://docs.ringg.ai/llms.txt > Use this file to discover all available pages before exploring further. # Reallocate Credit Balances > Prepaid, individual-billing families only. Sets every active sub-workspace's wallet to an absolute balance; the net difference moves from or to the primary's unallocated pot, which must be able to cover it. Top up on the primary first, then allocate. Not applicable to common-billing families, where the wallet is shared on the primary. Set every sub-workspace's wallet to an absolute balance. The net difference moves from or to the primary's unallocated pot. Prepaid families in **individual** billing mode only. ## When to use * Distributing a top-up made on the primary across clients or teams. * Pulling unused balance back from one sub-workspace to fund another. ## Request parameters | Parameter | Type | Required | Description | | ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `allocations` | object | Yes | Map of `sub_workspace_id` to its **new absolute balance**, not a delta. Must include **every active sub-workspace exactly once**. Values are `0` or more, two decimals. | ## 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 sub-workspace with a `0` balance cannot place calls; sub-workspaces have no overdraft. * Every move is recorded in the workspace ledgers as a transfer, never as a charge. ## Integration notes * Authenticate with the primary workspace's API key. * Read the current wallets and `family.available_pot` from [Get Sub-workspaces](/api-reference/endpoint/sub-workspace/get-sub-workspaces) first, then send the full map. * Amounts in the response are **decimal strings** (`"5000.00"`), unlike the read endpoints. In a **common-billing** family the wallet is shared on the primary and sub-workspaces hold nothing. This endpoint returns `400 This family uses a shared balance; per-sub wallets do not exist.` Allocate [concurrency](/api-reference/endpoint/sub-workspace/allocate-concurrency) instead. ## Error responses * **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.` * **404**: `Workspace is not a sub-workspace family parent.` — the primary has no sub-workspaces yet. * **422**: Empty map, negative value, or a key that is not a UUID. ## Example ```bash theme={null} curl --request PATCH "https://prod-api.ringg.ai/ca/api/v0/workspace/sub/credit-balances" \ --header "X-API-KEY: $RINGG_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "allocations": { "b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30": 5000.00, "d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88": 3000.00 } }' ``` ## OpenAPI ````yaml patch /workspace/sub/credit-balances openapi: 3.0.0 info: title: Ringg AI API Documentation description: >- This is the documentation for the Ringg AI APIs. The Ringg AI API follows RESTful principles, making it intuitive and easy to integrate with your applications. All API requests should be made to the base URL. The API accepts and returns data in JSON format. Ensure your requests include the appropriate Content-Type header for POST and PATCH requests. version: 2.0.0 servers: - url: https://prod-api.ringg.ai/ca/api/v0 security: [] tags: - name: workspace description: Endpoints for managing your workspace. - name: agent description: Endpoints for managing assistants (agents). - name: calling description: Endpoints for making and managing calls. - name: campaign description: Endpoints for managing campaigns. - name: analytics description: Endpoints for accessing call analytics and performance metrics. - name: termination description: Endpoints for terminating active calls using different methods. - name: knowledgebase description: Endpoints for managing knowledge bases. paths: /workspace/sub/credit-balances: patch: tags: - workspace summary: Reallocate Credit Balances description: >- Prepaid, individual-billing families only. Sets every active sub-workspace's wallet to an absolute balance; the net difference moves from or to the primary's unallocated pot, which must be able to cover it. Top up on the primary first, then allocate. Not applicable to common-billing families, where the wallet is shared on the primary. operationId: reallocateSubWorkspaceCreditBalances parameters: - name: X-API-KEY in: header description: >- (Required) The API key of the PRIMARY workspace. A sub-workspace's key is refused with 400. required: true schema: type: string example: 7251cb4b-3373-43a4-844c-b27a1d45e0c9 requestBody: required: true content: application/json: schema: type: object required: - allocations properties: allocations: type: object description: >- (Required) sub_workspace_id -> the sub-workspace's NEW absolute balance (not a delta). Must include every active sub-workspace exactly once. Values >= 0, two decimals. additionalProperties: type: number example: allocations: b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30: 5000 d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88: 3000 responses: '200': description: >- Successful Response: The applied balances. Amounts are decimal strings. content: application/json: schema: type: object properties: parent_workspace_id: type: string example: 2f9a1c44-7e88-4bb1-9a01-5d3c2e7f6a11 parent_available_balance: type: string description: >- The primary's unallocated pot after the move, as a decimal string. example: '12000.00' allocations: type: object additionalProperties: type: string example: b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30: '5000.00' d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88: '3000.00' primary: type: object properties: id: type: string example: 2f9a1c44-7e88-4bb1-9a01-5d3c2e7f6a11 name: type: string example: Acme Collections HQ example: parent_workspace_id: 2f9a1c44-7e88-4bb1-9a01-5d3c2e7f6a11 parent_available_balance: '12000.00' allocations: b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30: '5000.00' d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88: '3000.00' primary: id: 2f9a1c44-7e88-4bb1-9a01-5d3c2e7f6a11 name: Acme Collections HQ '400': description: >- Bad Request - Wrong billing mode, an incomplete map, or more than the primary's pot can cover. content: application/json: schema: type: object properties: detail: type: string example: >- 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': description: Unauthorized - Invalid or missing API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: 401 Unauthorized message: type: string example: Invalid credentials '403': description: >- Forbidden - Sub-workspaces are not enabled for this workspace, or the caller is not an active member of the primary. content: application/json: schema: type: object properties: detail: type: string example: Sub-workspaces are not enabled for this workspace. '404': description: Not Found - The primary has no sub-workspaces yet. content: application/json: schema: type: object properties: detail: type: string example: Workspace is not a sub-workspace family parent. '500': description: Internal Server Error - Something went wrong on our end. content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: 500 Internal Server Error message: type: string example: An unexpected error occurred on the server. ````