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_idand 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 moreMishkaPay.Price, each a catalog price by:idwith its:quantity(1 unless given).- How long, one of:
:iterationsperiods of:interval(:day,:week,:monthor:year;iterations: 12, interval: :monthis 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:truemakes the whole phase a free trial;:trial_end_atends a trial inside it.:proration: how a change of price at the phase's start is billed::create_prorations,:always_invoiceor:none.
The provider fills in :start_at and :end_at of every phase.
Summary
Functions
A sample %MishkaPay.Subscription.Schedule{} populated from defaults + type-based fallbacks.
Types
@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()] | nil | no | validate(list) | ||
:metadata | map() | nil | no | %{} | validate(map)<br>validator {MishkaPay.Checkout, :metadata} |