---
title: "Ask for more funds or a new budget"
method: POST
path: "/v1/budget_requests"
tags: ["Budget request"]
---

# Ask for more funds or a new budget

`POST /v1/budget_requests`

## Request

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

Creates a pending budget request and notifies whoever can approve it.

## Who can ask
- `more_funds` ("Más fondos"): someone in the budget (its Encargado, a co-encargado,
  or a participant, explicit or through a card) **without** `budgets_manage`. An admin
  / `budgets_manage` user gets `budget_requests/use_top_up`: they adjust the budget
  directly, with `POST /v1/budgets/{id}/top_up` for a `funded` budget or
  `PATCH /v1/budgets/{id}/amount` for a `tracking` one. `GET /v1/budgets/{id}` says whether
  the caller can ask (`viewer.can.request_funds`) and returns their pending request
  (`own_pending_request`).
- `new_budget` ("Presupuesto nuevo"): any active member of the company.

Only one pending request per person and budget (`more_funds`) or per person and name
(`new_budget`): another one answers `budget_requests/already_pending`.

## Parameters

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

## Request body

- union: Body to ask for more funds or for a new budget. Params go at the top level (no wrapper key).
  - object
    - `kind` 'more_funds', required
    - `amount_cents` integer, required: What's asked for. Must be over 0 (`budget_requests/invalid_amount`).
    - `reason` string, required: Why it's needed. Required.
    - `budget_id` string, uuid, required: `more_funds` only, required: the budget that needs more funds.
    - `period_scope` 'current_period' | 'next_periods': `more_funds` only. Required when the budget renews (`recurrence_unit` set), and refused when it doesn't; a mismatch answers `422` with only `message` (unlike approval, which answers `budget_requests/invalid_period_scope`): - `current_period`: for the period in progress. - `next_periods`: raise what each period starts with from the next renewal on.
    - `name` string: `new_budget` only, required: name of the budget asked for.
    - `recurrence_unit` 'week' | 'month' | 'year': `new_budget` only: how often it should renew. Omit it for a budget that doesn't renew.
    - `recurrence_every` integer: `new_budget` only, with `recurrence_unit`: 1 to 52 weeks, 1 to 24 months or 1 to 5 years.
    - `participant_ids` string[]: `new_budget` only: users to add to the budget as participants.
  - object
    - `kind` 'new_budget', required
    - `amount_cents` integer, required: What's asked for. Must be over 0 (`budget_requests/invalid_amount`).
    - `reason` string, required: Why it's needed. Required.
    - `budget_id` string, uuid: `more_funds` only, required: the budget that needs more funds.
    - `period_scope` 'current_period' | 'next_periods': `more_funds` only. Required when the budget renews (`recurrence_unit` set), and refused when it doesn't; a mismatch answers `422` with only `message` (unlike approval, which answers `budget_requests/invalid_period_scope`): - `current_period`: for the period in progress. - `next_periods`: raise what each period starts with from the next renewal on.
    - `name` string, required: `new_budget` only, required: name of the budget asked for.
    - `recurrence_unit` 'week' | 'month' | 'year': `new_budget` only: how often it should renew. Omit it for a budget that doesn't renew.
    - `recurrence_every` integer: `new_budget` only, with `recurrence_unit`: 1 to 52 weeks, 1 to 24 months or 1 to 5 years.
    - `participant_ids` string[]: `new_budget` only: users to add to the budget as participants.

## Response `201`

The request created, `pending`.

- BudgetRequest: A budget request ("solicitud de presupuesto"): a company member asks an admin for more funds for a budget they belong to (`more_funds`, "Más fondos") or for a new budget (`new_budget`, "Presupuesto nuevo"). An admin approves it (optionally changing the amount) or rejects it with a note; whoever asked can withdraw it while it's pending. Amounts are in the smallest currency unit (v1 is CLP-only, so cents == pesos).
  - `id` string, uuid, required
  - `company_id` string, uuid, required
  - `kind` 'more_funds' | 'new_budget', required: - `more_funds` ("Más fondos"): more money for an existing budget (`budget_id`). - `new_budget` ("Presupuesto nuevo"): a budget that doesn't exist yet; approving it creates the budget and `budget_id` points to it from then on.
  - `status` 'pending' | 'approved' | 'rejected' | 'withdrawn' | 'canceled', required: - `pending`: waiting for an admin. - `approved`: an admin approved it; the money moved (or the budget was created). - `rejected`: an admin rejected it; `resolution_note` says why. - `withdrawn`: whoever asked withdrew it. - `canceled`: the budget closed while it was pending (`resolution_note` is `budget_closed`).
  - `budget_id` string, uuid, nullable: The budget asked about (`more_funds`), or the one created on approval (`new_budget`). `null` for a `new_budget` request not approved.
  - `requested_amount_cents` integer, required: What was asked for.
  - `approved_amount_cents` integer, nullable: What the admin approved (the amount asked for unless changed). `null` until approved.
  - `currency` string, required
  - `period_scope` 'current_period' | 'next_periods' | 'null', nullable: Only for `more_funds` on a recurring budget (`null` otherwise): - `current_period`: the money is for the period in progress. - `next_periods`: raises what each period starts with (`base_amount_cents`) from the next renewal on.
  - `reason` string: Why the requester needs it.
  - `resolution_note` string, nullable: The admin's note when rejecting it. `budget_closed` when it was canceled because its budget closed.
  - `name` string, nullable: Name of the budget asked for (`new_budget` only).
  - `recurrence_unit` 'week' | 'month' | 'year' | 'null', nullable: How often the budget asked for should renew (`new_budget` only). `null` if it shouldn't.
  - `recurrence_every` integer, nullable: How many `recurrence_unit` each period of the budget asked for spans (`new_budget` only).
  - `participant_ids` string[]: Users the requester wants in the new budget (`new_budget` only; empty otherwise).
  - `origin_channel` 'web' | 'whatsapp', required: Where it was asked from.
  - `resolved_at` string, date-time, nullable: When it was approved, rejected, withdrawn or canceled.
  - `created_at` string, date-time, required
  - `requested_by` object, required: Who asked.
    - `id` string
    - `name` string, nullable
    - `email` string
  - `resolved_by` object, nullable: Who approved, rejected or withdrew it. `null` while pending or when canceled.
    - `id` string
    - `name` string, nullable
    - `email` string
  - `budget` object, nullable: The budget it's about (`budget_id`), `null` if there's none.
    - `id` string, uuid
    - `name` string
    - `mode` 'funded' | 'tracking'
    - `recurring` boolean: Whether it renews (`recurrence_unit` set).
    - `closing` boolean: Whether its closing date came.
    - `dissolved` boolean: Whether it's closed.
    - `period_ends_on` string, date, nullable: Scheduled renewal boundary of its period in progress. `null` if it doesn't renew.
    - `base_amount_cents` integer, nullable
    - `allocated_amount_cents` integer
  - `next_period_check` object, nullable: Only for users with `budgets_manage` (`null` for anyone else), on a pending `next_periods` request for a `funded` ("Con saldo") budget: the figures to warn that the company's free balance wouldn't renew the budget with the higher base today. `null` otherwise.
    - `current_base_cents` integer: What each period starts with today.
    - `available_for_base_cents` integer: The most the company's free balance could renew it with today.

## Other responses

- `401`: Unauthorized - missing or invalid authentication token, or a caller outside the company.
- `403`: `budget_requests/not_a_member` (the caller isn't an active member of the company) or `budget_requests/not_a_budget_member` (`more_funds` on a budget the caller isn't in).
- `404`: `budget_requests/budget_not_found`: `budget_id` missing or not a budget of the company.
- `409`: `budget_requests/already_pending`: the caller already has a pending request for that budget (or name).
- `422`: `budget_requests/use_top_up` (an admin / `budgets_manage` user asking for more funds), `budget_requests/budget_closed` (the budget is closed) or `budget_requests/invalid_amount` (`amount_cents` missing, not an integer or not over 0). Other failures (a missing `reason` or `name`, a `period_scope` that doesn't match the budget's periodicity, an invalid `recurrence_every`, a participant who isn't an active member) answer only `message`.

---

[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)