MishkaPay.Subscription (Mishka Pay v0.0.1)

Copy Markdown View Source

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.

Summary

Types

t()

The struct that builder/1 returns.

Functions

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.

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

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.

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

Types

t()

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

FieldTypeRequiredDefaultDescriptionDerives
:providerString.t()yesvalidate(not_nil_value, string)
:idString.t()yesvalidate(not_nil_value, string, not_empty)
:statusatom()yesvalidate(not_nil_value, enum=Atom[incomplete::incomplete_expired::trialing::active::past_due::unpaid::paused::canceled])
:items[MishkaPay.Price.t()] | nilno[]
:customer_idString.t() | nilnovalidate(string)
:customer_emailString.t() | nilnovalidate(string)
:customer_nameString.t() | nilnovalidate(string)
:current_period_startDateTime.t() | nilnovalidate(struct)
:current_period_endDateTime.t() | nilnovalidate(struct)
:cancel_at_period_endboolean() | nilnofalsevalidate(boolean)
:cancel_atDateTime.t() | nilnovalidate(struct)
:canceled_atDateTime.t() | nilnovalidate(struct)
:trial_endDateTime.t() | nilnovalidate(struct)
:latest_invoice_idString.t() | nilnovalidate(string)
:schedule_idString.t() | nilnovalidate(string)
:pause_behavior:void | :keep_as_draft | :mark_uncollectible | nilnovalidate(enum=Atom[void::keep_as_draft::mark_uncollectible])<br>validator {MishkaPay.Subscription, :pause_behavior}
:resumes_atDateTime.t() | nilnovalidate(struct)
:referenceString.t() | nilnovalidate(string)
:ownerString.t() | nilnovalidate(string)
:metadatamap() | nilno%{}validate(map)
:created_atDateTime.t() | nilnovalidate(struct)
:changeMishkaPay.Subscription.Change.t() | nilnoA 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.
:scheduleMishkaPay.Subscription.Schedule.t() | nilnoA 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.

Functions

builder(attrs_or_input, error \\ false)

change_prorates?(attrs)

@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(field)

example()

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

keys()

keys(field)

schedule_needs(attrs)

@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()

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