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
:subscriptioncapability. Without it the checkout isErrors.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.
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
| Status | Means | Access |
|---|---|---|
:trialing | In the free trial | Give |
:active | Paid for the current period | Give |
:past_due | A renewal failed and the provider tries again | Your product decides (a grace period) |
:unpaid | The retries ran out | Take away |
:canceled | Ended | Take away |
:incomplete, :incomplete_expired | The first payment never finished | Do not give |
:paused | Paused | Take 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
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.
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_idorquantityto keep it.prorationis:create_prorations(the default),:always_invoiceor:none. preview_subscription_change/1sets:proration_dateto now if you give none. Pass the same date tochange_subscription/1.- A subscription with several items needs
item_id:. billing_cycle_anchor: :nowstarts 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
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_collectionstops charging without canceling.behavioris:void,:keep_as_draftor:mark_uncollectible.- The default cancel lets the buyer keep what they paid for.
at: :nowends 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.
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.
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
:iterationsperiods of:intervalor until:end_at, not both. The last phase may leave both out. end_behavioris: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 callupdate_subscription_schedule/1with the current phase (its ownstart_at) and the next one. release_subscription_schedule/3ends the plan and keeps the subscription.cancel_subscription_schedule/4ends both.
Next steps
- Bill by usage with meters: a price that follows what the customer used.
- Save customers and cards, and open the billing portal: let buyers change plans themselves.
- Keep payments in Ash resources and Mishka CMS: gate pages with a subscription policy.
- Test code that takes payments: test clocks for renewals.