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),:pausedor:canceled.:items: what it charges for, each aMishkaPay.Pricewith its:interval,:quantityand:item_id(the line aMishkaPay.Subscription.Changenames).:pause_behavior,:resumes_at: while collection is paused (MishkaPay.pause_collection/4), what happens to its invoices (:void,:keep_as_draftor: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:truewhen it ends at:current_period_end(seeMishkaPay.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/3lists them all).:schedule_id: theMishkaPay.Subscription.Schedulethat 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
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
@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.
| Field | Type | Required | Default | Description | Derives |
|---|---|---|---|---|---|
:provider | String.t() | yes | validate(not_nil_value, string) | ||
:id | String.t() | yes | validate(not_nil_value, string, not_empty) | ||
:status | atom() | yes | validate(not_nil_value, enum=Atom[incomplete::incomplete_expired::trialing::active::past_due::unpaid::paused::canceled]) | ||
:items | [MishkaPay.Price.t()] | nil | no | [] | ||
:customer_id | String.t() | nil | no | validate(string) | ||
:customer_email | String.t() | nil | no | validate(string) | ||
:customer_name | String.t() | nil | no | validate(string) | ||
:current_period_start | DateTime.t() | nil | no | validate(struct) | ||
:current_period_end | DateTime.t() | nil | no | validate(struct) | ||
:cancel_at_period_end | boolean() | nil | no | false | validate(boolean) | |
:cancel_at | DateTime.t() | nil | no | validate(struct) | ||
:canceled_at | DateTime.t() | nil | no | validate(struct) | ||
:trial_end | DateTime.t() | nil | no | validate(struct) | ||
:latest_invoice_id | String.t() | nil | no | validate(string) | ||
:schedule_id | String.t() | nil | no | validate(string) | ||
:pause_behavior | :void | :keep_as_draft | :mark_uncollectible | nil | no | validate(enum=Atom[void::keep_as_draft::mark_uncollectible])<br>validator {MishkaPay.Subscription, :pause_behavior} | ||
:resumes_at | DateTime.t() | nil | no | validate(struct) | ||
:reference | String.t() | nil | no | validate(string) | ||
:owner | String.t() | nil | no | validate(string) | ||
:metadata | map() | nil | no | %{} | validate(map) | |
:created_at | DateTime.t() | nil | no | validate(struct) | ||
:change | MishkaPay.Subscription.Change.t() | nil | no | 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. | ||
:schedule | MishkaPay.Subscription.Schedule.t() | nil | no | 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. |
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.
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.
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.
@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.