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 withbilling_cycle_anchor: :now(a new period has nothing to prorate from).:billing_cycle_anchor::nowstarts 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_incompleteor:default_incomplete; left out, the provider's default.
Every option left out is the provider's own default.
Summary
Functions
A sample %MishkaPay.Subscription.Change{} populated from defaults + type-based fallbacks.
Types
@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} |