# `MishkaPay.Coupon.PromotionCode`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/nofile#L1)

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`).

Made with `MishkaPay.create_promotion_code/1`, read with `MishkaPay.fetch_promotion_code/3` and
`MishkaPay.list_promotion_codes/3`, turned off or on again with
`MishkaPay.update_promotion_code/1` (`active: false`).

What the caller gives:

  * `:provider`, `:tenant`: which provider, with whose keys.
  * `:coupon_id`: the coupon it applies.
  * `:code`: what the buyer types; the provider makes one when it is left out.
  * `:active`: whether it can be used now (`true` by default).
  * `:max_redemptions`, `:expires_at`: its own limits, on top of the coupon's.
  * `:first_time_transaction`: only for a buyer's first purchase.
  * `:minimum_amount`: only when the order is at least this `Money`.
  * `:customer_id`: only for this customer.
  * `:metadata`: extra pairs, string keys to string values.

What the provider fills in: `:id`, `:times_redeemed`, `:created_at`.

# `t`

```elixir
@type t() :: %MishkaPay.Coupon.PromotionCode{
  active: boolean() | nil,
  code: String.t() | nil,
  coupon_id: String.t() | nil,
  created_at: DateTime.t() | nil,
  customer_id: String.t() | nil,
  expires_at: DateTime.t() | nil,
  first_time_transaction: boolean() | nil,
  id: String.t() | nil,
  max_redemptions: pos_integer() | nil,
  metadata: map() | nil,
  minimum_amount: Money.t() | nil,
  provider: String.t() | nil,
  tenant: term() | nil,
  times_redeemed: non_neg_integer() | 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)` |
| `:coupon_id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:code` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=200)` |
| `:active` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:max_redemptions` | `pos_integer()` \| `nil` | no |  |  | `validate(integer, min_len=1)` |
| `:expires_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:first_time_transaction` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:minimum_amount` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:customer_id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:times_redeemed` | `non_neg_integer()` \| `nil` | no |  |  | `validate(integer)` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:metadata` | `map()` \| `nil` | no | `%{}` |  | `validate(map)`<br>validator `{MishkaPay.Checkout, :metadata}` |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

---

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