---
title: "Create a balance group"
method: POST
path: "/v1/budgets"
tags: ["Budget"]
---

# Create a balance group

`POST /v1/budgets`

Creates a balance group under the company from the `company-id` header. Requires
admin or the `budgets_manage` permission.

All fields are nested under a `budget` key. The name must be unique per company
among active (non-dissolved) groups.

## Parameters

- `#/paths/~1v1~1bills/get/parameters/0` — unresolved $ref

## Request body

- BudgetCreate — Body to create a balance group. All create params are nested under a `budget` key (`{ "budget": { ... } }`).
  - `budget` object, required
    - `name` string, required — Group name; must be unique per company among active groups.
    - `description` string
    - `currency` string
    - `allocated_amount_cents` integer — Initial funds to reserve into the pool, in the smallest currency unit.
    - `manager_id` string — User id to designate as the group's manager ("Encargado").

## Response `201`

The created balance group.

- Budget — A balance group ("grupo de saldo" / budget): a named pool of company funds with an assigned manager ("Encargado") and a set of bound cards. Amounts are in the smallest currency unit (v1 is CLP-only, so cents == pesos).
  - `id` string, uuid, required
  - `company_id` string, uuid, required
  - `name` string, required
  - `description` string, nullable
  - `currency` string, required
  - `allocated_amount_cents` integer, required — Funds reserved into this group's pool from the company's global pool.
  - `manager_id` string, nullable — User id of the group's manager ("Encargado").
  - `committable_cents` integer — Manager-facing "what's left to commit/spend": nets out funds already loaded onto prepaid (PLH) cards, so it matches what new charges and card loads will actually allow. Added via serializer method.
  - `available_cents` integer — Company-reservation view of what's left in the pool (`allocated + consumed_balance`). Added via serializer method.
  - `consumed_balance_cents` integer — Net amount consumed from the pool (<= 0 for net spend), summed from the balance-affecting ledger. Added via serializer method.
  - `manager` object, nullable — The assigned manager, embedded (only id, name, email).
    - `id` string
    - `name` string
    - `email` string, email
  - `vendor_cards` object[] — Cards bound to this group, embedded with per-card funding data.
    - `id` string, uuid
    - `name` string
    - `last4` string
    - `user_id` string
    - `spending_control_strategy` 'allocation_based' | 'limit_based'
    - `limit_currency` string
    - `allocated_amount_cents` integer
    - `limit_amount_preference_cents` integer, nullable
    - `limit_interval_preference` string, nullable
    - `recurring_allocation_amount_cents` integer, nullable
    - `allocation_interval_preference` string, nullable
  - `dissolved_at` string, date-time, nullable — When the group was soft-deleted ("deshacer"). `null` for active groups; a timestamp for dissolved ones. Active listings only return active groups, but the field is present on the record.
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `401` — Unauthorized - missing or invalid authentication token.
- `412` — Precondition failed - the request body is missing the required `budget` wrapper key (the params are read with `params.expect(budget: ...)`).
- `422` — Validation failed (e.g. duplicate name).

---

[API](https://skmtc.dev/cardda/apis/banking-api.md) · [All operations](https://skmtc.dev/cardda/apis/banking-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cardda/banking-api/revisions/ff1aeb3fda8b/schema)