# `Tink.Budgets`
[🔗](https://github.com/iamkanishka/tink.ex/blob/v0.1.1/lib/tink/budgets.ex#L1)

Business Finance Management (BFM) Budgets API.

Comprehensive budget management for business financial planning with support for
one-off and recurring budgets, progress tracking, and budget history.

## Features

- **One-off Budgets**: Single-period budgets
- **Recurring Budgets**: Monthly, quarterly, or yearly budgets
- **Progress Tracking**: Monitor budget performance
- **Budget History**: View historical budget data
- **Allocation Rules**: Category, account, and tag-based allocation

## Prerequisites

- Generated user with bearer token (user authentication token)
- Accounts created and linked to user
- (Optional) Transactions ingested for budget tracking

## Quick Start

    # Create client with user bearer token
    client = Tink.client(access_token: user_bearer_token)

    # Create budget
    {:ok, budget} = Tink.Budgets.create_budget(client, %{
      title: "Marketing Q1",
      type: "EXPENSE",
      target_amount: %{
        value: %{unscaled_value: 50000, scale: 0},
        currency_code: "SEK"
      },
      recurrence: %{
        frequency: "MONTHLY",
        start: "2024-01-01",
        end: "2024-03-31"
      },
      allocation_rules: %{
        expense_allocation_rules: [
          %{
            categories: [%{id: "marketing-category-id"}],
            accounts: [%{id: "account-id"}],
            tags: []
          }
        ],
        income_allocation_rules: []
      }
    })

# `create_budget`

```elixir
@spec create_budget(Tink.Client.t(), map()) :: {:ok, map()} | {:error, Tink.Error.t()}
```

Creates a new business budget.

## Required Scope

User bearer token (not client credentials)

## Examples

    {:ok, budget} = Tink.Budgets.create_budget(client, %{
      title: "Test budget",
      description: "Test budget's description",
      type: "INCOME",
      target_amount: %{
        value: %{unscaled_value: 123, scale: 0},
        currency_code: "SEK"
      },
      recurrence: %{
        frequency: "ONE_OFF",
        start: "2021-07-01",
        end: "2021-07-31"
      },
      allocation_rules: %{
        expense_allocation_rules: [],
        income_allocation_rules: [
          %{
            categories: [%{id: "category-id"}],
            accounts: [%{id: "account-id"}],
            tags: []
          }
        ]
      }
    })

# `delete_budget`

```elixir
@spec delete_budget(Tink.Client.t(), String.t()) :: :ok | {:error, Tink.Error.t()}
```

Deletes a budget.

## Examples

    :ok = Tink.Budgets.delete_budget(client, "budget_id")

# `get_budget`

```elixir
@spec get_budget(Tink.Client.t(), String.t()) ::
  {:ok, map()} | {:error, Tink.Error.t()}
```

Gets details for a specific budget.

## Examples

    {:ok, budget} = Tink.Budgets.get_budget(client, "budget_id")

# `get_budget_history`

```elixir
@spec get_budget_history(Tink.Client.t(), String.t()) ::
  {:ok, map()} | {:error, Tink.Error.t()}
```

Gets the history of a budget across all periods.

## Examples

    {:ok, history} = Tink.Budgets.get_budget_history(client, "budget_id")

# `list_budgets`

```elixir
@spec list_budgets(
  Tink.Client.t(),
  keyword()
) :: {:ok, map()} | {:error, Tink.Error.t()}
```

Lists all business budgets with optional filtering.

## Examples

    {:ok, budgets} = Tink.Budgets.list_budgets(client)
    {:ok, on_track} = Tink.Budgets.list_budgets(client, progress_status_in: ["ON_TRACK"])

# `update_budget`

```elixir
@spec update_budget(Tink.Client.t(), String.t(), map()) ::
  {:ok, map()} | {:error, Tink.Error.t()}
```

Updates an existing budget.

## Examples

    {:ok, updated} = Tink.Budgets.update_budget(client, "budget_id", %{
      title: "New title",
      target_amount: %{
        value: %{unscaled_value: 1000000, scale: 0},
        currency_code: "SEK"
      }
    })

---

*Consult [api-reference.md](api-reference.md) for complete listing*