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

A plan for a subscription over time, in phases (`MishkaPay.Subscription.Schedule.Phases`): a change of
plan on a set date, an intro price, a membership that stops after twelve months. Made with
`MishkaPay.create_subscription_schedule/1`, read with `MishkaPay.fetch_subscription_schedule/3`
and `MishkaPay.list_subscription_schedules/3`, changed with
`MishkaPay.update_subscription_schedule/1`, and ended with
`MishkaPay.release_subscription_schedule/3` (the subscription goes on alone) or
`MishkaPay.cancel_subscription_schedule/4` (the subscription ends too). A guarded_struct.

What the caller gives to make one, in one of two ways:

  * from a running subscription: `:subscription_id`, nothing else; its one phase is the
    subscription as it is now, and a change (`update_subscription_schedule/1`) adds the next;
  * new: `:customer_id` and its `:phases`, from `:start_at` (now unless given); the
    subscription starts when the first phase does.

A new schedule also takes `:billing_mode` (`:flexible`, the default, or `:classic`) and
`:proration_discounts` (`:itemized`, the default, or `:included`), as a checkout does
(`MishkaPay.Checkout`); left out, the tenant's own (`MishkaPay.Credentials`) apply. A schedule
made from a subscription keeps the subscription's billing mode, and a change cannot set one.

And on either, `:reference` (the caller's own id: it makes the idempotency key, so the same
reference never makes two) and `:metadata`. A change (`:id` given) names only what it changes:
`:phases` (all of them from the current one on, the current one with the start it has),
`:end_behavior`, `:proration` (how the change itself is billed), `:metadata`.

`:end_behavior` says what happens after the last phase: `:release` (the subscription goes on
as the last phase left it) or `:cancel` (it ends).

What the provider fills in: `:id` (`sub_sched_...` at Stripe), `:status` (`:not_started`,
`:active`, `:completed`, `:released` or `:canceled`), `:subscription_id` (the subscription it
runs), `:released_subscription_id` (the one it let go), every phase's dates, `:current_phase`
(the index of the phase running now), and `:created_at`, `:released_at`, `:canceled_at`,
`:completed_at`.

## Phases

Each of `:phases` is a `MishkaPay.Subscription.Schedule.Phases`, a sub_field of this struct: one
stretch of the schedule, what the subscription charges, and for how long. Phases follow each
other; when the last one ends the schedule does what its `:end_behavior` says.

  * `:items`: one or more `MishkaPay.Price`, each a catalog price by `:id` with its
    `:quantity` (1 unless given).
  * How long, one of: `:iterations` periods of `:interval` (`:day`, `:week`, `:month` or
    `:year`; `iterations: 12, interval: :month` is a year), or until `:end_at`. The last phase
    may leave both out: it then runs one period of its prices.
  * `:start_at`: when it starts; only the first phase of a schedule takes one, and a change
    to a running schedule names its current phase with the start it has.
  * `:trial`: `true` makes the whole phase a free trial; `:trial_end_at` ends a trial inside it.
  * `:proration`: how a change of price at the phase's start is billed: `:create_prorations`,
    `:always_invoice` or `:none`.

The provider fills in `:start_at` and `:end_at` of every phase.

# `t`

```elixir
@type t() :: %MishkaPay.Subscription.Schedule{
  billing_mode: (:flexible | :classic) | nil,
  canceled_at: DateTime.t() | nil,
  completed_at: DateTime.t() | nil,
  created_at: DateTime.t() | nil,
  current_phase: non_neg_integer() | nil,
  customer_id: String.t() | nil,
  end_behavior: (:release | :cancel) | nil,
  id: String.t() | nil,
  metadata: map() | nil,
  phases: [MishkaPay.Subscription.Schedule.Phases.t()] | nil,
  proration: (:create_prorations | :always_invoice | :none) | nil,
  proration_discounts: (:itemized | :included) | nil,
  provider: String.t(),
  reference: String.t() | nil,
  released_at: DateTime.t() | nil,
  released_subscription_id: String.t() | nil,
  start_at: DateTime.t() | nil,
  status: (:not_started | :active | :completed | :released | :canceled) | nil,
  subscription_id: String.t() | nil,
  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 |  |  |  |
| `:id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:customer_id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:subscription_id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:start_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:end_behavior` | `:release` \| `:cancel` \| `nil` | no |  |  | `validate(enum=Atom[release::cancel])`<br>validator `{MishkaPay.Subscription, :end_behavior}` |
| `:billing_mode` | `:flexible` \| `:classic` \| `nil` | no |  |  | `validate(enum=Atom[flexible::classic])`<br>validator `{MishkaPay.Checkout, :billing_mode}` |
| `:proration_discounts` | `:itemized` \| `:included` \| `nil` | no |  |  | `validate(enum=Atom[itemized::included])`<br>validator `{MishkaPay.Checkout, :proration_discounts}` |
| `:proration` | `:create_prorations` \| `:always_invoice` \| `:none` \| `nil` | no |  |  | `validate(enum=Atom[create_prorations::always_invoice::none])`<br>validator `{MishkaPay.Subscription, :proration}` |
| `:reference` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=200)` |
| `:status` | `:not_started` \| `:active` \| `:completed` \| `:released` \| `:canceled` \| `nil` | no |  |  | `validate(enum=Atom[not_started::active::completed::released::canceled])` |
| `:current_phase` | `non_neg_integer()` \| `nil` | no |  |  | `validate(integer)` |
| `:released_subscription_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:released_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:canceled_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:completed_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:phases` | [`[MishkaPay.Subscription.Schedule.Phases.t()]`](`t:MishkaPay.Subscription.Schedule.Phases.t/0`) \| `nil` | no |  |  | `validate(list)` |
| `:metadata` | `map()` \| `nil` | no | `%{}` |  | `validate(map)`<br>validator `{MishkaPay.Checkout, :metadata}` |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

---

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