# `MishkaPay.PortalSession.Configuration`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/lib/mishka_pay/portal_session.ex#L85)

What buyers may do in the provider's customer portal (`MishkaPay.PortalSession`), kept at the
provider as one setup a portal session names by `:configuration`: a site can keep one for
monthly buyers and another for teams. Made with `MishkaPay.create_portal_configuration/1`,
changed with `MishkaPay.update_portal_configuration/1`, read with
`MishkaPay.fetch_portal_configuration/3` and `MishkaPay.list_portal_configurations/3`. A
guarded_struct.

What the caller gives, every field optional (a change sends only what it names):

  * `:provider`, `:tenant`: which provider, with whose keys.
  * `:name`: the host's own name for it; `:active`: `false` turns it off (a provider never
    deletes one).
  * The portal page's header: `:headline`, `:privacy_policy_url`, `:terms_of_service_url`; and
    `:default_return_url`, where buyers go back when a session names no `return_url`.
  * `:invoice_history`: `true` shows their past bills; `:payment_method_update`: `true` lets
    them change their card.
  * `:customer_update`: which of their details they may change, from `:email`, `:address`,
    `:shipping`, `:phone`, `:tax_id`, `:name`; `[]` none.
  * `:subscription_cancel`: `:immediately`, `:at_period_end`, or `:off`.
  * `:subscription_update`: what they may change on a plan, from `:price`, `:quantity`,
    `:promotion_code`; `[]` nothing. With `:price`, `:plans` (`MishkaPay.PortalSession.Configuration.Plans`) lists the
    products and prices they may switch to, and `:proration` says how the change bills:
    `:create_prorations`, `:always_invoice` or `:none`.
  * `:metadata`: extra pairs, string keys to string values.

What the provider fills in: `:id` (`bpc_...` at Stripe), `:default` (`true` for the one a
session without `:configuration` uses), `:created_at`.

## Plans

Each of `:plans` is a `MishkaPay.PortalSession.Configuration.Plans`, a sub_field of this struct:
a product a buyer may switch their subscription to in the customer portal, with the prices of
it on offer.

  * `:product_id`: the catalog product (`MishkaPay.Product`).
  * `:price_ids`: its recurring prices the buyer may pick, one or more.

# `t`

```elixir
@type t() :: %MishkaPay.PortalSession.Configuration{
  active: boolean() | nil,
  created_at: DateTime.t() | nil,
  customer_update: list() | nil,
  default: boolean() | nil,
  default_return_url: String.t() | nil,
  headline: String.t() | nil,
  id: String.t() | nil,
  invoice_history: boolean() | nil,
  metadata: map() | nil,
  name: String.t() | nil,
  payment_method_update: boolean() | nil,
  plans: [MishkaPay.PortalSession.Configuration.Plans.t()] | nil,
  privacy_policy_url: String.t() | nil,
  proration: (:create_prorations | :always_invoice | :none) | nil,
  provider: String.t(),
  subscription_cancel: (:off | :immediately | :at_period_end) | nil,
  subscription_update: list() | nil,
  tenant: term() | nil,
  terms_of_service_url: String.t() | 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)` |
| `:name` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=256)` |
| `:active` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:default` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:headline` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=60)` |
| `:privacy_policy_url` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:terms_of_service_url` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:default_return_url` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:invoice_history` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:payment_method_update` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:customer_update` | `list()` \| `nil` | no |  |  | validator `{MishkaPay.PortalSession.Configuration, :customer_update}` |
| `:subscription_cancel` | `:off` \| `:immediately` \| `:at_period_end` \| `nil` | no |  |  | `validate(enum=Atom[off::immediately::at_period_end])`<br>validator `{MishkaPay.PortalSession.Configuration, :subscription_cancel}` |
| `:subscription_update` | `list()` \| `nil` | no |  |  | validator `{MishkaPay.PortalSession.Configuration, :subscription_update}` |
| `:plans` | [`[MishkaPay.PortalSession.Configuration.Plans.t()]`](`t:MishkaPay.PortalSession.Configuration.Plans.t/0`) \| `nil` | no |  |  | `validate(list)` |
| `:proration` | `:create_prorations` \| `:always_invoice` \| `:none` \| `nil` | no |  |  | `validate(enum=Atom[create_prorations::always_invoice::none])`<br>validator `{MishkaPay.PortalSession.Configuration, :proration}` |
| `:metadata` | `map()` \| `nil` | no | `%{}` |  | `validate(map)`<br>validator `{MishkaPay.Checkout, :metadata}` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

---

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