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

One subscription as the provider sees it, read with `MishkaPay.fetch_subscription/3`. A
guarded_struct the provider fills in; the provider is the source of truth, so read it again
rather than keep it.

  * `:id`: the provider's id (`sub_...` at Stripe).
  * `:status`: `:incomplete` (the first payment is not done), `:incomplete_expired` (it never
    was), `:trialing`, `:active`, `:past_due` (a renewal failed and is being tried again),
    `:unpaid` (the tries ran out), `:paused` or `:canceled`.
  * `:items`: what it charges for, each a `MishkaPay.Price` with its `:interval`, `:quantity`
    and `:item_id` (the line a `MishkaPay.Subscription.Change` names).
  * `:pause_behavior`, `:resumes_at`: while collection is paused
    (`MishkaPay.pause_collection/4`), what happens to its invoices (`:void`,
    `:keep_as_draft` or `:mark_uncollectible`) and when collection starts again by itself.
  * `:customer_id`, `:customer_email`, `:customer_name`: the buyer.
  * `:current_period_start`, `:current_period_end`: the period paid for now.
  * `:cancel_at_period_end`: `true` when it ends at `:current_period_end` (see
    `MishkaPay.cancel_subscription/4`); `:cancel_at`, `:canceled_at`: when it ends, or ended.
  * `:trial_end`: when the trial ends, for one in trial.
  * `:latest_invoice_id`: its newest invoice (`MishkaPay.list_invoices/3` lists them all).
  * `:schedule_id`: the `MishkaPay.Subscription.Schedule` that runs it, when one does.
  * `:reference`, `:metadata`: the caller's own id from the checkout, and extra pairs;
    `:owner`: who it is for, as the checkout named them (`MishkaPay.Checkout`).
  * `:created_at`: when the provider made it.

# `t`

```elixir
@type t() :: %MishkaPay.Subscription{
  cancel_at: DateTime.t() | nil,
  cancel_at_period_end: boolean() | nil,
  canceled_at: DateTime.t() | nil,
  change: MishkaPay.Subscription.Change.t() | nil,
  created_at: DateTime.t() | nil,
  current_period_end: DateTime.t() | nil,
  current_period_start: DateTime.t() | nil,
  customer_email: String.t() | nil,
  customer_id: String.t() | nil,
  customer_name: String.t() | nil,
  id: String.t(),
  items: [MishkaPay.Price.t()] | nil,
  latest_invoice_id: String.t() | nil,
  metadata: map() | nil,
  owner: String.t() | nil,
  pause_behavior: (:void | :keep_as_draft | :mark_uncollectible) | nil,
  provider: String.t(),
  reference: String.t() | nil,
  resumes_at: DateTime.t() | nil,
  schedule: MishkaPay.Subscription.Schedule.t() | nil,
  schedule_id: String.t() | nil,
  status: atom(),
  trial_end: DateTime.t() | nil
}
```

The struct that `builder/1` returns.

| Field | Type | Required | Default | Description | Derives |
| --- | --- | --- | --- | --- | --- |
| `:provider` | `String.t()` | yes |  |  | `validate(not_nil_value, string)` |
| `:id` | `String.t()` | yes |  |  | `validate(not_nil_value, string, not_empty)` |
| `:status` | `atom()` | yes |  |  | `validate(not_nil_value, enum=Atom[incomplete::incomplete_expired::trialing::active::past_due::unpaid::paused::canceled])` |
| `:items` | [`[MishkaPay.Price.t()]`](`t:MishkaPay.Price.t/0`) \| `nil` | no | `[]` |  |  |
| `:customer_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:customer_email` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:customer_name` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:current_period_start` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:current_period_end` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:cancel_at_period_end` | `boolean()` \| `nil` | no | `false` |  | `validate(boolean)` |
| `:cancel_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:canceled_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:trial_end` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:latest_invoice_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:schedule_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:pause_behavior` | `:void` \| `:keep_as_draft` \| `:mark_uncollectible` \| `nil` | no |  |  | `validate(enum=Atom[void::keep_as_draft::mark_uncollectible])`<br>validator `{MishkaPay.Subscription, :pause_behavior}` |
| `:resumes_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:reference` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:owner` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:metadata` | `map()` \| `nil` | no | `%{}` |  | `validate(map)` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:change` | [`MishkaPay.Subscription.Change.t()`](`t:MishkaPay.Subscription.Change.t/0`) \| `nil` | no |  | 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`. |  |
| `:schedule` | [`MishkaPay.Subscription.Schedule.t()`](`t:MishkaPay.Subscription.Schedule.t/0`) \| `nil` | no |  | 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. |  |

# `builder`

# `change_prorates?`

```elixir
@spec change_prorates?(map()) :: boolean()
```

Whether a subscription change makes prorations that a `proration_date` counts from: true unless
its `proration` is `:none` or its `billing_cycle_anchor` is `:now`.

Date such a change once and send the same `proration_date` to the preview and to the change, so
the change bills what the preview showed.

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

# `schedule_needs`

```elixir
@spec schedule_needs(map()) :: [atom()]
```

The fields a new schedule cannot go without: none more from a subscription, its customer and
phases otherwise. `MishkaPay.create_subscription_schedule/1` asks for them once it is built.

# `statuses`

```elixir
@spec statuses() :: [atom()]
```

Every status a subscription can be in, as `:status` names them: what
`MishkaPay.list_subscriptions/3` and `MishkaPay.search_subscriptions/3` filter by.

---

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