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

A change to a running subscription: a new plan, a new quantity (seats), or both, and how the
provider bills the difference. A guarded_struct, given to `MishkaPay.change_subscription/1` and
`MishkaPay.preview_subscription_change/1`.

  * `:provider`, `:tenant`, `:subscription_id`: which subscription, with whose keys.
  * `:item_id`: which of its items changes (`si_...` at Stripe, `MishkaPay.Price`'s `:item_id`);
    left out, its only item.
  * `:price_id`: the new plan, a catalog price; left out, the plan stays.
  * `:quantity`: the new quantity; left out, it stays.
  * `:proration`: how the difference is billed: `:create_prorations` (the provider's default:
    credit and charge wait for the next invoice), `:always_invoice` (bill it now) or `:none`
    (no credit, no charge until the next period).
  * `:proration_date`: the moment the difference is counted from; give the one a preview used,
    so the change bills exactly what the preview showed. It goes only with prorations, and not
    with `billing_cycle_anchor: :now` (a new period has nothing to prorate from).
  * `:billing_cycle_anchor`: `:now` starts a new period at once; `:unchanged` (the default)
    keeps the dates.
  * `:payment_behavior`: what happens when charging the difference fails:
    `:allow_incomplete`, `:error_if_incomplete`, `:pending_if_incomplete` or
    `:default_incomplete`; left out, the provider's default.

Every option left out is the provider's own default.

# `t`

```elixir
@type t() :: %MishkaPay.Subscription.Change{
  billing_cycle_anchor: (:now | :unchanged) | nil,
  item_id: String.t() | nil,
  payment_behavior:
    (:allow_incomplete
     | :error_if_incomplete
     | :pending_if_incomplete
     | :default_incomplete)
    | nil,
  price_id: String.t() | nil,
  proration: (:create_prorations | :always_invoice | :none) | nil,
  proration_date: DateTime.t() | nil,
  provider: String.t(),
  quantity: pos_integer() | nil,
  subscription_id: String.t(),
  tenant: term() | nil
}
```

The struct that `builder/1` returns.

| Field | Type | Required | Default | Description | Derives |
| --- | --- | --- | --- | --- | --- |
| `:provider` | `String.t()` | yes |  |  | `sanitize(trim) validate(not_nil_value, string, not_empty)` |
| `:tenant` | `term()` \| `nil` | no |  |  |  |
| `:subscription_id` | `String.t()` | yes |  |  | `sanitize(trim) validate(not_nil_value, string, not_empty)` |
| `:item_id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:price_id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:quantity` | `pos_integer()` \| `nil` | no |  |  | `validate(integer, min_len=1)` |
| `:proration` | `:create_prorations` \| `:always_invoice` \| `:none` \| `nil` | no |  |  | `validate(enum=Atom[create_prorations::always_invoice::none])`<br>validator `{MishkaPay.Subscription, :proration}` |
| `:proration_date` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:billing_cycle_anchor` | `:now` \| `:unchanged` \| `nil` | no |  |  | `validate(enum=Atom[now::unchanged])`<br>validator `{MishkaPay.Subscription, :anchor}` |
| `:payment_behavior` | `:allow_incomplete` \| `:error_if_incomplete` \| `:pending_if_incomplete` \| `:default_incomplete` \| `nil` | no |  |  | `validate(enum=Atom[allow_incomplete::error_if_incomplete::pending_if_incomplete::default_incomplete])`<br>validator `{MishkaPay.Subscription, :payment_behavior}` |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

---

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