MishkaPay.Subscription.Schedule (Mishka Pay v0.0.1)

Copy Markdown View Source

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.

Summary

Types

t()

The struct that builder/1 returns.

Functions

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

Types

t()

@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.

FieldTypeRequiredDefaultDescriptionDerives
:providerString.t()yessanitize(trim) validate(not_nil_value, string, not_empty)
:tenantterm() | nilno
:idString.t() | nilnosanitize(trim) validate(string, not_empty)
:customer_idString.t() | nilnosanitize(trim) validate(string, not_empty)
:subscription_idString.t() | nilnosanitize(trim) validate(string, not_empty)
:start_atDateTime.t() | nilnovalidate(struct)
:end_behavior:release | :cancel | nilnovalidate(enum=Atom[release::cancel])<br>validator {MishkaPay.Subscription, :end_behavior}
:billing_mode:flexible | :classic | nilnovalidate(enum=Atom[flexible::classic])<br>validator {MishkaPay.Checkout, :billing_mode}
:proration_discounts:itemized | :included | nilnovalidate(enum=Atom[itemized::included])<br>validator {MishkaPay.Checkout, :proration_discounts}
:proration:create_prorations | :always_invoice | :none | nilnovalidate(enum=Atom[create_prorations::always_invoice::none])<br>validator {MishkaPay.Subscription, :proration}
:referenceString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=200)
:status:not_started | :active | :completed | :released | :canceled | nilnovalidate(enum=Atom[not_started::active::completed::released::canceled])
:current_phasenon_neg_integer() | nilnovalidate(integer)
:released_subscription_idString.t() | nilnovalidate(string)
:created_atDateTime.t() | nilnovalidate(struct)
:released_atDateTime.t() | nilnovalidate(struct)
:canceled_atDateTime.t() | nilnovalidate(struct)
:completed_atDateTime.t() | nilnovalidate(struct)
:phases[MishkaPay.Subscription.Schedule.Phases.t()] | nilnovalidate(list)
:metadatamap() | nilno%{}validate(map)<br>validator {MishkaPay.Checkout, :metadata}

Functions

builder(attrs_or_input, error \\ false)

enforce_keys()

enforce_keys(field)

example()

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

keys()

keys(field)