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

A discount the provider keeps: a percent or an amount off, once, for some months of a
subscription, or forever. A guarded_struct. Buyers redeem it through a `MishkaPay.Coupon.PromotionCode`
they type, or a checkout applies it directly (`MishkaPay.Checkout.Discounts`).

Made with `MishkaPay.create_coupon/1`, read with `MishkaPay.fetch_coupon/3` and
`MishkaPay.list_coupons/3`, removed with `MishkaPay.delete_coupon/3` (codes already given keep
their discount on what they were applied to).

What the caller gives:

  * `:provider`, `:tenant`: which provider, with whose keys.
  * `:id`: optional, the coupon's own id (`"SPRING"`); the provider makes one when it is left out.
  * `:name`: what the buyer sees on the checkout and the invoice.
  * `:percent_off` (more than 0, at most 100) or `:amount_off` (a `Money`): one of them.
  * `:duration`: `:once` (the default), `:repeating` for `:duration_in_months` of a
    subscription, or `:forever`.
  * `:max_redemptions`: how many times it may be used in all.
  * `:redeem_by`: the last moment it may be used.
  * `:metadata`: extra pairs, string keys to string values.

What the provider fills in: `:valid` (it can still be used), `:times_redeemed`, `:created_at`.

# `t`

```elixir
@type t() :: %MishkaPay.Coupon{
  amount_off: Money.t() | nil,
  created_at: DateTime.t() | nil,
  duration: (:once | :repeating | :forever) | nil,
  duration_in_months: pos_integer() | nil,
  id: String.t() | nil,
  max_redemptions: pos_integer() | nil,
  metadata: map() | nil,
  name: String.t() | nil,
  percent_off: Decimal.t() | nil,
  promotion_code: MishkaPay.Coupon.PromotionCode.t() | nil,
  provider: String.t() | nil,
  redeem_by: DateTime.t() | nil,
  tenant: term() | nil,
  times_redeemed: non_neg_integer() | nil,
  valid: boolean() | 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, max_len=200)` |
| `:name` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=200)` |
| `:percent_off` | `Decimal.t()` \| `nil` | no |  |  | validator `{MishkaPay.Coupon, :percent_off}` |
| `:amount_off` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:duration` | `:once` \| `:repeating` \| `:forever` \| `nil` | no | `:once` |  | `validate(not_nil_value, enum=Atom[once::repeating::forever])`<br>validator `{MishkaPay.Coupon, :duration}` |
| `:duration_in_months` | `pos_integer()` \| `nil` | no |  |  | `validate(integer, min_len=1)` |
| `:max_redemptions` | `pos_integer()` \| `nil` | no |  |  | `validate(integer, min_len=1)` |
| `:redeem_by` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:metadata` | `map()` \| `nil` | no | `%{}` |  | `validate(map)`<br>validator `{MishkaPay.Checkout, :metadata}` |
| `:valid` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:times_redeemed` | `non_neg_integer()` \| `nil` | no |  |  | `validate(integer)` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:promotion_code` | [`MishkaPay.Coupon.PromotionCode.t()`](`t:MishkaPay.Coupon.PromotionCode.t/0`) \| `nil` | no |  | A code a buyer types at the checkout (`SPRING10`) that applies a `MishkaPay.Coupon`, with its own limits. A guarded_struct. A checkout lets buyers type codes with `allow_promotion_codes: true`, or applies one itself through `discounts` (`MishkaPay.Checkout.Discounts`). |  |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

---

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