# `Beancount.Directives.Commodity`
[🔗](https://github.com/thanos/beancount_ex/blob/v0.6.0/lib/beancount/directives/commodity.ex#L1)

The `commodity` directive declares a currency or commodity.

See the [Beancount Commodity directive](https://beancount.github.io/docs/beancount_language_syntax/#commodity).

## Beancount syntax

    2026-01-01 commodity USD
      name: "US Dollar"
      asset-class: "cash"

General form: `YYYY-MM-DD commodity Currency`

## Elixir struct

    %Beancount.Directives.Commodity{
      date: ~D[2026-01-01],
      currency: "USD",
      metadata: %{"name" => "US Dollar", "asset-class" => "cash"}
    }

Or use `Beancount.commodity/3`:

    Beancount.commodity(~D[2026-01-01], "USD",
      metadata: %{"name" => "US Dollar", "asset-class" => "cash"}
    )

## Fields

  * `date` - `Date.t()` associated with the commodity (often its introduction
    date; used for ordering, not validation).
  * `currency` - commodity symbol, e.g. `"USD"`, `"AAPL"`, `"HOOL"`.
  * `metadata` - optional map for descriptive attributes (`name`, `asset-class`,
    etc.) gathered by plugins and reports.

# `t`

```elixir
@type t() :: %Beancount.Directives.Commodity{
  currency: String.t(),
  date: Date.t(),
  metadata: map()
}
```

---

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