---
title: "List balance groups"
method: GET
path: "/v1/budgets"
tags: ["Budget"]
---

# List balance groups

`GET /v1/budgets`

## Request

- Base URL: `https://api.cardda.com`
- URL: `https://api.cardda.com/v1/budgets`
- Auth: HTTP bearer

Returns the company's active balance groups ("grupos de saldo" / budgets), each with
its computed totals (`committable_cents`, `available_cents`, `consumed_balance_cents`),
its embedded `manager`, and its bound `vendor_cards`.

## Access
- Admin / finance users (permission `budgets_manage`) see every group in the company.
- Other users only see the groups they manage (`manager_id` == their user id).

The company is taken from the `company-id` header. This endpoint is not paginated —
it returns all active groups in scope.

## Parameters

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

## Response `200`

Active balance groups in scope.

- Budget[]
  - union: 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).
    - object: `mode` is `funded`. `allocated_amount_cents` can be 0.
      - `id` string, uuid, required
      - `company_id` string, uuid, required
      - `name` string, required
      - `description` string, nullable
      - `currency` string, required
      - `mode` 'funded': How the budget works. Set on creation and never changed afterwards. - `funded` ("Con saldo"): reserves company balance into the budget's pool. Card purchases and transfers that exceed it are declined. - `tracking` ("Solo control"): only measures spend against a planned amount. It reserves no company balance, and going over the planned amount declines nothing: its cards and the transfers imputed to it use the company's general balance, and their spend is still attributed to the budget. The card's own limit and the company's available balance still apply.
      - `allocated_amount_cents` integer, required: For a `funded` budget, the funds reserved into its pool from the company's global pool. For a `tracking` budget, the planned amount spend is measured against (always greater than 0).
      - `manager_id` string, nullable: User id of the group's manager ("Encargado").
      - `committable_cents` integer: For a `funded` budget, 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. A `tracking` budget has no pool to commit from: here the value is informational, `remaining_cents` floored at 0, and it limits neither the cards nor the transfers, which use the company's general balance. Use `remaining_cents` and `exceeded_cents` for that mode.
      - `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.
      - `used_cents` integer: What the budget's alerts measure: net spend plus the transfers imputed to it that are still in flight. Added via serializer method.
      - `remaining_cents` integer: What is left of the amount (`allocated_amount_cents - used_cents`). Negative once the budget is exceeded, which only a `tracking` budget can be. Added via serializer method.
      - `exceeded_cents` integer: By how much the budget was exceeded (`used_cents - allocated_amount_cents`, floored at 0). 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` 'per_transaction' | 'daily' | 'weekly' | 'monthly' | 'yearly', nullable: Auto-reload frequency of a prepaid (`allocation_based`) card. `per_transaction` reloads it after each purchase. In a `funded` budget each reload is capped at the budget's `committable_cents`; in a `tracking` budget the card reloads from the company's balance.
      - `recurrence_unit` 'week' | 'month' | 'year' | 'null', nullable: How often the budget renews, together with `recurrence_every`. `null` if it doesn't renew. Periods are counted from the budget's creation date, in America/Santiago. Each period starts with `base_amount_cents`, without carrying what was left of the previous one. While a budget renews, `allocated_amount_cents` and every consumption figure are those of the period in progress (`current_period`).
      - `recurrence_every` integer, nullable: How many `recurrence_unit` each period spans: 1 to 52 weeks, 1 to 24 months or 1 to 5 years. `null` if it doesn't renew.
      - `base_amount_cents` integer, nullable: What each new period starts with. A `funded` budget renews only if the company's free balance covers it (plus what's still in flight) and its prepaid cards don't hold more than it; otherwise the period in progress goes on with what it had, and the renewal is retried daily (`renewal_blocked_since`).
      - `period_ends_on` string, date, nullable: Scheduled renewal boundary: the day (America/Santiago) the next period is due to start. It is not a spending cutoff: the period in progress stays usable until the renewal actually runs (daily, after midnight). If a `funded` budget's renewal is blocked (`renewal_blocked_since`), this date stays in the past and the period in progress goes on with what it has. Unrelated to `ends_on`, the budget's closing date. `null` if it doesn't renew.
      - `ends_on` string, date, nullable: Closing date: the first day the budget can no longer be used (date in America/Santiago). From 00:00 that day it takes no new purchases or transfers, and it closes with the same rules as closing it by hand. `null` if it has none.
      - `closing` boolean: Whether its closing date came. It takes no new spend (`committable_cents` is 0 or less) until it closes. Added via serializer method.
      - `closing_since` string, date, nullable: Its closing date came but transfers or approved documents still in flight keep it open. It closes once they settle.
      - `renewal_blocked_since` string, date, nullable: Since when its renewal is pending (only a `funded` budget's renewal blocks), for either reason: - its prepaid cards hold more than `base_amount_cents`: what they hold stays loaded on them, inside the new period, so renewing would free money still on the cards; - the company's free balance doesn't cover `base_amount_cents` plus what's still in flight. The period in progress goes on with what it had, and the renewal is retried daily.
      - `current_period` object, nullable: The period in progress of a renewing budget (or one that renewed before), `null` otherwise. Added via serializer method.
        - `starts_at` string, date-time
        - `ends_on` string, date, nullable: Scheduled renewal boundary of this period, same as the budget's `period_ends_on`: not a spending cutoff, and it stays in the past while the renewal is blocked (`renewal_blocked_since`). The budget-level closing date is `ends_on`.
        - `refunds_cents` integer: Refunds of the period, which can leave it above its base amount.
        - `carried_commitments_cents` integer: Transfers and approved documents of earlier periods still in flight: reserved apart, outside this period's figures.
      - `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
      - `viewer` object: What the caller can do with this budget, so the client offers only that. Added via serializer method.
        - `role` string, nullable: The caller's role in the budget.
        - `can` object: One boolean per action. Only `request_funds` and `view_fund_movements` are documented here.
          - `request_funds` boolean: Whether the caller can ask for more funds (`POST /v1/budget_requests` with `kind: more_funds`): they're in the budget, don't have `budgets_manage` and the budget isn't closed.
          - `view_fund_movements` boolean: Whether the caller can read the budget's funds history (`GET /v1/budgets/{id}/fund_movements`): admin / `budgets_manage` users, Cardda staff and members of the budget. `false` for someone who sees it only because it's open to the company.
      - `own_pending_request` object, nullable: Only on `GET /v1/budgets/{id}`: the caller's own pending `more_funds` request for this budget, `null` if there's none.
        - `id` string, uuid
        - `requested_amount_cents` integer
        - `created_at` string, date-time
    - object: `mode` is `tracking`. `allocated_amount_cents` is always greater than 0.
      - `id` string, uuid, required
      - `company_id` string, uuid, required
      - `name` string, required
      - `description` string, nullable
      - `currency` string, required
      - `mode` 'tracking', required: How the budget works. Set on creation and never changed afterwards. - `funded` ("Con saldo"): reserves company balance into the budget's pool. Card purchases and transfers that exceed it are declined. - `tracking` ("Solo control"): only measures spend against a planned amount. It reserves no company balance, and going over the planned amount declines nothing: its cards and the transfers imputed to it use the company's general balance, and their spend is still attributed to the budget. The card's own limit and the company's available balance still apply.
      - `allocated_amount_cents` integer, required: For a `funded` budget, the funds reserved into its pool from the company's global pool. For a `tracking` budget, the planned amount spend is measured against (always greater than 0).
      - `manager_id` string, nullable: User id of the group's manager ("Encargado").
      - `committable_cents` integer: For a `funded` budget, 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. A `tracking` budget has no pool to commit from: here the value is informational, `remaining_cents` floored at 0, and it limits neither the cards nor the transfers, which use the company's general balance. Use `remaining_cents` and `exceeded_cents` for that mode.
      - `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.
      - `used_cents` integer: What the budget's alerts measure: net spend plus the transfers imputed to it that are still in flight. Added via serializer method.
      - `remaining_cents` integer: What is left of the amount (`allocated_amount_cents - used_cents`). Negative once the budget is exceeded, which only a `tracking` budget can be. Added via serializer method.
      - `exceeded_cents` integer: By how much the budget was exceeded (`used_cents - allocated_amount_cents`, floored at 0). 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` 'per_transaction' | 'daily' | 'weekly' | 'monthly' | 'yearly', nullable: Auto-reload frequency of a prepaid (`allocation_based`) card. `per_transaction` reloads it after each purchase. In a `funded` budget each reload is capped at the budget's `committable_cents`; in a `tracking` budget the card reloads from the company's balance.
      - `recurrence_unit` 'week' | 'month' | 'year' | 'null', nullable: How often the budget renews, together with `recurrence_every`. `null` if it doesn't renew. Periods are counted from the budget's creation date, in America/Santiago. Each period starts with `base_amount_cents`, without carrying what was left of the previous one. While a budget renews, `allocated_amount_cents` and every consumption figure are those of the period in progress (`current_period`).
      - `recurrence_every` integer, nullable: How many `recurrence_unit` each period spans: 1 to 52 weeks, 1 to 24 months or 1 to 5 years. `null` if it doesn't renew.
      - `base_amount_cents` integer, nullable: What each new period starts with. A `funded` budget renews only if the company's free balance covers it (plus what's still in flight) and its prepaid cards don't hold more than it; otherwise the period in progress goes on with what it had, and the renewal is retried daily (`renewal_blocked_since`).
      - `period_ends_on` string, date, nullable: Scheduled renewal boundary: the day (America/Santiago) the next period is due to start. It is not a spending cutoff: the period in progress stays usable until the renewal actually runs (daily, after midnight). If a `funded` budget's renewal is blocked (`renewal_blocked_since`), this date stays in the past and the period in progress goes on with what it has. Unrelated to `ends_on`, the budget's closing date. `null` if it doesn't renew.
      - `ends_on` string, date, nullable: Closing date: the first day the budget can no longer be used (date in America/Santiago). From 00:00 that day it takes no new purchases or transfers, and it closes with the same rules as closing it by hand. `null` if it has none.
      - `closing` boolean: Whether its closing date came. It takes no new spend (`committable_cents` is 0 or less) until it closes. Added via serializer method.
      - `closing_since` string, date, nullable: Its closing date came but transfers or approved documents still in flight keep it open. It closes once they settle.
      - `renewal_blocked_since` string, date, nullable: Since when its renewal is pending (only a `funded` budget's renewal blocks), for either reason: - its prepaid cards hold more than `base_amount_cents`: what they hold stays loaded on them, inside the new period, so renewing would free money still on the cards; - the company's free balance doesn't cover `base_amount_cents` plus what's still in flight. The period in progress goes on with what it had, and the renewal is retried daily.
      - `current_period` object, nullable: The period in progress of a renewing budget (or one that renewed before), `null` otherwise. Added via serializer method.
        - `starts_at` string, date-time
        - `ends_on` string, date, nullable: Scheduled renewal boundary of this period, same as the budget's `period_ends_on`: not a spending cutoff, and it stays in the past while the renewal is blocked (`renewal_blocked_since`). The budget-level closing date is `ends_on`.
        - `refunds_cents` integer: Refunds of the period, which can leave it above its base amount.
        - `carried_commitments_cents` integer: Transfers and approved documents of earlier periods still in flight: reserved apart, outside this period's figures.
      - `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
      - `viewer` object: What the caller can do with this budget, so the client offers only that. Added via serializer method.
        - `role` string, nullable: The caller's role in the budget.
        - `can` object: One boolean per action. Only `request_funds` and `view_fund_movements` are documented here.
          - `request_funds` boolean: Whether the caller can ask for more funds (`POST /v1/budget_requests` with `kind: more_funds`): they're in the budget, don't have `budgets_manage` and the budget isn't closed.
          - `view_fund_movements` boolean: Whether the caller can read the budget's funds history (`GET /v1/budgets/{id}/fund_movements`): admin / `budgets_manage` users, Cardda staff and members of the budget. `false` for someone who sees it only because it's open to the company.
      - `own_pending_request` object, nullable: Only on `GET /v1/budgets/{id}`: the caller's own pending `more_funds` request for this budget, `null` if there's none.
        - `id` string, uuid
        - `requested_amount_cents` integer
        - `created_at` string, date-time

## Other responses

- `401`: Unauthorized - missing or invalid authentication token.

---

[API](https://skmtc.dev/cardda/apis/finance-api.md) - [All operations](https://skmtc.dev/cardda/apis/finance-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardda/apis/finance-api/revisions/59752c65ea74?raw)