Sell and manage subscriptions

v0.0.1

A subscription starts as a checkout in subscription mode. After that you read it, change its plan, pause or cancel it, plan changes ahead with schedules and give access from its status. This guide covers each of those with Stripe, which has the full set. PayPal subscriptions are smaller. See Take payments with PayPal. Selling a plan from a Mishka CMS site follows the same calls, with the site id as the tenant.

Before you begin

  • Mishka Pay installed and a Stripe key for the site. See Get Started.
  • A webhook endpoint, so the subscription stays current after renewals and failed payments. See Receive and verify webhooks.
  • The provider needs the :subscription capability. Without it the checkout is Errors.Unsupported.

Start a subscription

Use the checkout from Take a one-time payment with mode: :subscription. Every item needs an interval, or a provider price id.

elixir
MishkaPay.checkout(%{
  provider: "stripe",
  tenant: site.id,
  mode: :subscription,
  trial_days: 14,
  items: [
    %{
      name: "Pro plan",
      amount: %{amount: "9", currency: "USD"},
      interval: :month,
      interval_count: 1,
      tax_code: "txcd_10103001"
    }
  ],
  success_url:
    url(~p"/welcome") <> "?session_id={CHECKOUT_SESSION_ID}",
  cancel_url: url(~p"/pricing"),
  reference: account.id
})

interval is :day, :week, :month or :year. A one-time checkout refuses an item with an interval, and refuses trial_days. When the buyer returns, fetch_checkout/3 gives the :subscription_id. Read it with fetch_subscription/3.

billing_mode (:flexible or :classic) and proration_discounts (:itemized or :included) say how the provider counts prorations. Left out, the site's keys decide, and then Mishka Pay sends Stripe's recommended ones, :flexible and :itemized.

Read the status and give access

StatusMeansAccess
:trialingIn the free trialGive
:activePaid for the current periodGive
:past_dueA renewal failed and the provider tries againYour product decides (a grace period)
:unpaidThe retries ran outTake away
:canceledEndedTake away
:incomplete, :incomplete_expiredThe first payment never finishedDo not give
:pausedPausedTake away

cancel_at_period_end: true means the subscription still runs until current_period_end, then ends. Do not compute access from dates yourself. Give or take access from the status, and listen to mishka_pay:subscription:changed or the Ash subscription row to know when it moves.

Find subscriptions

elixir
MishkaPay.list_subscriptions("stripe", site.id,
  customer_id: customer.id,
  status: :all
)

MishkaPay.list_subscriptions("stripe", site.id,
  price_id: pro.id,
  status: :past_due,
  limit: 50
)

MishkaPay.search_subscriptions("stripe", site.id,
  reference: account.id
)

MishkaPay.search_subscriptions("stripe", site.id,
  status: :active,
  metadata: %{"plan" => "pro"}
)

Both answer a MishkaPay.Page and need the :subscription_list capability. Without status:, Stripe leaves canceled subscriptions out of a list. A search needs status:, reference: or metadata:, and Stripe's index can lag by up to a minute, so read a subscription you already know by id with fetch_subscription/3.

Change the plan or the quantity

Preview the bill first. Then apply the change with the same proration date, so the bill equals the preview.

elixir
change = %{
  provider: "stripe",
  tenant: site.id,
  subscription_id: sub.id,
  price_id: team_price.id,
  quantity: 5,
  proration: :always_invoice
}

{:ok, preview} =
  MishkaPay.preview_subscription_change(change)

{:ok, sub} =
  MishkaPay.change_subscription(
    Map.put(change, :proration_date, proration_date)
  )
  • Leave out price_id or quantity to keep it. proration is :create_prorations (the default), :always_invoice or :none.
  • preview_subscription_change/1 sets :proration_date to now if you give none. Pass the same date to change_subscription/1.
  • A subscription with several items needs item_id:.
  • billing_cycle_anchor: :now starts a new period at once. payment_behavior: says what happens if charging the difference fails.
  • A credit for unused time shows on the bill as a line with a negative amount.

Pause, cancel and resume

elixir
MishkaPay.pause_collection("stripe", sub.id, site.id,
  behavior: :void,
  resumes_at: resumes_at
)

MishkaPay.resume_collection("stripe", sub.id, site.id)

# at the period's end
MishkaPay.cancel_subscription("stripe", sub.id, site.id)
# now
MishkaPay.cancel_subscription("stripe", sub.id, site.id,
  at: :now
)

# takes back a cancel at period end
MishkaPay.resume_subscription("stripe", sub.id, site.id)
  • pause_collection stops charging without canceling. behavior is :void, :keep_as_draft or :mark_uncollectible.
  • The default cancel lets the buyer keep what they paid for. at: :now ends it at once.
  • A subscription that is already canceled cannot be resumed. Start a new checkout.

Charge a one-off amount on the next renewal

A setup fee or an extra seat this month is an invoice item. Without an :invoice_id it waits for the customer's next bill, a renewal included.

elixir
MishkaPay.create_invoice_item(%{
  provider: "stripe",
  tenant: site.id,
  customer_id: customer.id,
  name: "Setup fee",
  amount: %{amount: "25", currency: "USD"},
  reference: "fee-" <> account.id
})

See Count tax, send invoices and issue credit notes for the rest.

Plan changes ahead with a schedule

A change on a set date, an intro price or a membership that stops after twelve months is a subscription schedule, in phases. The provider needs the :subscription_schedule capability.

elixir
MishkaPay.create_subscription_schedule(%{
  provider: "stripe",
  tenant: site.id,
  customer_id: customer.id,
  end_behavior: :cancel,
  reference: "member-" <> member.id,
  phases: [
    %{
      items: [%{id: intro.id}],
      iterations: 3,
      interval: :month,
      trial: true
    },
    %{
      items: [%{id: full.id, quantity: 2}],
      end_at: ~U[2027-12-01 00:00:00Z]
    }
  ]
})
  • A phase charges catalog prices by id, for :iterations periods of :interval or until :end_at, not both. The last phase may leave both out.
  • end_behavior is :release (the subscription goes on as the last phase left it) or :cancel.
  • To plan from a running subscription, create a schedule with subscription_id: sub.id, then call update_subscription_schedule/1 with the current phase (its own start_at) and the next one.
  • release_subscription_schedule/3 ends the plan and keeps the subscription. cancel_subscription_schedule/4 ends both.

Next steps