# `MishkaPay.Price`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/lib/mishka_pay/price.ex#L5)

A price: one line of a checkout (what the buyer pays for, how much and how many), or a price in
the provider's catalog for a `MishkaPay.Product`. A guarded_struct.

  * `:name`: what the buyer sees, such as "Elixir ebook".
  * `:amount`: the price of one, a `Money` checked by `MishkaPay.Money` (`%{amount: "19.99",
    currency: "USD"}` works too).
  * `:quantity`: 1 by default.
  * `:tax_code`: the provider's tax category of what is sold, such as Stripe's `"txcd_10302000"`
    for a downloaded e-book. A provider that is the merchant of record (Stripe Managed
    Payments) needs it to work out the tax. A price the provider already knows (`:id`) carries
    its own tax code there, so this one is not sent with it.
  * `:id`: the provider's own id of a price it already knows (`price_...` at Stripe). With it,
    the provider's price is used and `:name` and `:amount` may be left out.
  * `:tax_behavior`: `:exclusive` (tax is added on top, as in the US) or `:inclusive` (the
    amount already holds the tax, as in much of Europe); what a provider counting the tax
    (Stripe Tax, Managed Payments) does with the amount.
  * `:tax_rate_ids`: on a checkout's or a bill's line, the seller's own tax rates added to it
    (`MishkaPay.TaxRate`), instead of a provider counting the tax. A catalog price and a payment
    link take none.
  * `:interval`, `:interval_count`: a price charged again on a schedule, for a subscription:
    every `:interval_count` (1 by default) `:day`, `:week`, `:month` or `:year`. Left out, the
    price is paid once.
  * `:meter_id`: a `MishkaPay.Meter` the price bills by usage: each `:interval`, the customer
    pays `:amount` for each unit the meter counted. It needs an `:interval`.

In the catalog (`MishkaPay.create_price/1`, `MishkaPay.list_prices/3`) a price also has:

  * `:provider`, `:tenant`: which provider's catalog, with whose keys.

  * `:product_id`: the product it sells; with `:amount` it is all a new price needs.
  * `:lookup_key`: the host's own name for it (`"pro-monthly"`), to find it without its id.
  * `:active`: on sale; `MishkaPay.archive_price/3` turns it off (a provider never deletes a
    price that was used).
  * `:metadata`: extra pairs, string keys to string values.
  * `:created_at`: filled in by the provider.

On a subscription's item (`MishkaPay.Subscription`), `:item_id` is the provider's id of that
line (`si_...` at Stripe).

# `t`

```elixir
@type t() :: %MishkaPay.Price{
  active: boolean() | nil,
  amount: Money.t() | nil,
  created_at: DateTime.t() | nil,
  id: String.t() | nil,
  interval: (:day | :week | :month | :year) | nil,
  interval_count: pos_integer() | nil,
  item_id: String.t() | nil,
  lookup_key: String.t() | nil,
  metadata: map() | nil,
  meter_id: String.t() | nil,
  name: String.t() | nil,
  product_id: String.t() | nil,
  provider: String.t() | nil,
  quantity: pos_integer() | nil,
  tax_behavior: (:inclusive | :exclusive) | nil,
  tax_code: String.t() | nil,
  tax_rate_ids: list() | nil,
  tenant: term() | nil
}
```

The struct that `builder/1` returns.

| Field | Type | Required | Default | Description | Derives |
| --- | --- | --- | --- | --- | --- |
| `:provider` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:tenant` | `term()` \| `nil` | no |  |  |  |
| `:id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:name` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=250)` |
| `:amount` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:tax_code` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=100)` |
| `:interval` | `:day` \| `:week` \| `:month` \| `:year` \| `nil` | no |  |  | `validate(enum=Atom[day::week::month::year])`<br>validator `{MishkaPay.Price, :interval}` |
| `:interval_count` | `pos_integer()` \| `nil` | no |  |  | `validate(integer, min_len=1)` |
| `:meter_id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:tax_behavior` | `:inclusive` \| `:exclusive` \| `nil` | no |  |  | `validate(enum=Atom[inclusive::exclusive])`<br>validator `{MishkaPay.Price, :tax_behavior}` |
| `:tax_rate_ids` | `list()` \| `nil` | no |  |  | `sanitize(each=[trim]) validate(list, each=[string, not_empty])` |
| `:quantity` | `pos_integer()` \| `nil` | no | `1` |  | `validate(not_nil_value, integer, min_len=1)` |
| `:product_id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:lookup_key` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=200)` |
| `:active` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:metadata` | `map()` \| `nil` | no | `%{}` |  | `validate(map)`<br>validator `{MishkaPay.Checkout, :metadata}` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:item_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

A sample %MishkaPay.Price{} populated from defaults + type-based fallbacks.

# `keys`

# `keys`

---

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