Subscriptions

Subscriptions lets your app sell recurring plans, such as a yearly membership, through Stripe. You declare the plans in config. The module handles checkout, upgrades, downgrades and the Stripe billing portal. Your code then asks one question: does this user hold plan X? For a one-time charge, use Payments.

The package is @frigear-nu/subscriptions. Stripe owns the products and prices. A plan is not a role: access follows what the user pays for, and "membership" is only the name the pages use. To give a role to paying users only, put the subscription requirement on it (see Permissions).

What you get

• Pages (opt-in): a membership page at /account/membership, and a success and a cancel page after checkout.
• Admin area (with Admin and Widget): a Membership tab where staff grant a free membership or send a payment link.
• Server routes (on by default): plans with live prices, the user's subscription, checkout and the billing portal. Staff routes need users:read from Users, and subscriptions:manage to change anything.
• Composables and helpers (on by default): useSubscription(), usePlans() and a subscription route middleware in the app, and hasActiveSubscription on the server.

Quick setup

pnpm add @frigear-nu/subscriptions @nuxthub/core @nuxt/ui

export default defineNuxtConfig({
  modules: [
    '@nuxthub/core',
    '@nuxt/ui',
    '@frigear-nu/menu', // optional
    '@frigear-nu/subscriptions', // installs Users and Stripe for you
  ],
  hub: { db: { dialect: 'sqlite', driver: 'libsql' }, kv: true },
  subscriptions: {
    plans: {
      member: { label: 'Member', rank: 1, prices: [{ lookupKey: 'member_yearly' }] },
      patron: { label: 'Patron', rank: 2, prices: [{ lookupKey: 'patron_yearly' }] },
    },
    settings: { pages: { membership: true, success: true, cancel: true } },
  },
})

pnpm db:generate

import { forbidden } from '@frigear-nu/module-kit/server'

export default defineEventHandler(async (event) => {
  const user = await requireUser(event)
  if (!await hasActiveSubscription(user.id, { plans: ['member', 'patron'] })) {
    throw forbidden('Members only.')
  }
  return { perks: [] }
})

Options

Options go under the subscriptions key.

plans left empty makes checkout require a priceId. It then accepts any active recurring Stripe price, and stored rows get planKey = null.

plans.<key>.label, description and features give way to subscriptions.catalog.<key>.* i18n keys.

plans.<key>.availability.disabledRanges dates are inclusive. {fullYear} becomes the current year, as in {fullYear}-06-01. Subscribers still see the plan.

settings.pages.* need @nuxt/ui.

Runtime config

public.subscriptions exposes the page paths, the plans without prices and allowChangeInPortal.

Permissions

The module registers these permissions with Authorization.

• Nobody holds subscriptions:manage by default. Granting a free membership gives away paid access, so you grant it by name to the roles that may. * does not cover it for a token, because it is session only.
• Staff reads of a user's membership use users:read, like the rest of the admin user page.
• Requirement: the module registers the subscription role requirement. A role with requirements: { subscription: '*' } counts only while the user holds an active or trialing subscription on any plan (free grants count). Use a plan key, or a list of keys, to name plans.
• Scope and policies: the module registers no named scope, role or policy. A token can carry the subscriptions:read permission directly.

export default defineNuxtConfig({
  authorization: {
    defaultRoles: ['user'],
    roles: {
      member: {
        label: 'Member',
        grant: ['member-area:view'],
        requirements: { subscription: ['member', 'patron'] }, // plan keys, or '*' for any plan
        auto: true, // held by everyone who meets the requirement; not assignable by hand
        inherit: ['user'],
      },
      coordinator: { label: 'Coordinator', grant: ['subscriptions:manage', 'users:read', 'users:list'] },
    },
  },
})

Module pages

Next steps

• Stripe setup – create the prices and the billing portal your plans use.
• Subscriptions app – build your own pricing page with the composables.