feat(*): Add support for per-seat costs (#8629)

Co-authored-by: Keiran Flanigan <keiran@clerk.dev>
Co-authored-by: Mauricio Antunes <mauricio.abreua@gmail.com>
Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com>
Co-authored-by: Alex Carpenter <alex.carpenter@clerk.dev>

Author: 5 people

.changeset/many-views-check.md

@@ -0,0 +1,20 @@
+---
+'@clerk/localizations': minor
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/react': minor
+'@clerk/testing': minor
+'@clerk/ui': minor
+---
+
+Add support for Clerk Billing plans with per-seat costs.
+
+- New invite-to-checkout flow when inviting members while on a plan that uses per-seat costs.
+- New localization values to support UI additions.
+- Support for the `orgId` and `minSeats` parameters to `getPlans()`.
+- Support for the `seatsQuantity` and `priceId` parameters to checkout creation.
+- New `totals` field on payments.
+- New `availablePrices` field on plans.
+- New `nextPayment` field on subscription items.
+- New `discounts` field on checkouts.
+- Additional fields on `nextPayment` for more granularity.

integration/templates/vue-vite/src/router.ts

@@ -36,6 +36,11 @@ const routes = [
     path: '/custom-pages/organization-profile',
     component: () => import('./views/custom-pages/OrganizationProfile.vue'),
   },
+  {
+    name: 'OrganizationProfile',
+    path: '/organization-profile',
+    component: () => import('./views/OrganizationProfile.vue'),
+  },
   {
     name: 'PricingTable',
     path: '/pricing-table',
@@ -119,7 +124,14 @@ const router = createRouter({
 
 router.beforeEach(async (to, _, next) => {
   const { isSignedIn, isLoaded } = useAuth();
-  const authenticatedPages = ['Profile', 'Admin', 'CustomUserProfile', 'CustomOrganizationProfile', 'UserAvatar'];
+  const authenticatedPages = [
+    'Profile',
+    'Admin',
+    'CustomUserProfile',
+    'CustomOrganizationProfile',
+    'OrganizationProfile',
+    'UserAvatar',
+  ];
 
   if (!isLoaded.value) {
     await waitForClerkJsLoaded(isLoaded);

integration/templates/vue-vite/src/views/OrganizationProfile.vue

@@ -0,0 +1,7 @@
+<script setup lang="ts">
+import { OrganizationProfile } from '@clerk/vue';
+</script>
+
+<template>
+  <OrganizationProfile />
+</template>

integration/tests/per-seat-pricing.test.ts

@@ -0,0 +1,100 @@
+import { expect, test } from '@playwright/test';
+
+import type { FakeOrganization, FakeUser } from '../testUtils';
+import { createTestUtils, testAgainstRunningApps } from '../testUtils';
+
+const INVITEE_EMAIL = 'one+clerk_test@clerk.dev';
+
+test.describe.configure({ mode: 'serial' });
+
+testAgainstRunningApps({})('per-seat pricing @billing', ({ app }) => {
+  let fakeAdmin: FakeUser;
+  let fakeOrganization: FakeOrganization;
+
+  test.beforeAll(async () => {
+    const u = createTestUtils({ app });
+
+    fakeAdmin = u.services.users.createFakeUser();
+    const admin = await u.services.users.createBapiUser(fakeAdmin);
+    fakeOrganization = await u.services.users.createFakeOrganization(admin.id);
+  });
+
+  test.afterAll(async () => {
+    await fakeOrganization.delete();
+    await fakeAdmin.deleteIfExists();
+    await app.teardown();
+  });
+
+  test('invites a member after purchasing additional seats', async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+    const fillInviteForm = async () => {
+      const emailInput = u.po.page.getByTestId('tag-input');
+      await emailInput.fill(INVITEE_EMAIL);
+      await emailInput.press('Enter');
+
+      await u.po.page.getByRole('button', { name: /select role/i }).click();
+      await u.po.page.getByRole('option', { name: /^member$/i }).click();
+    };
+
+    await u.po.signIn.goTo();
+    await u.po.signIn.waitForMounted();
+    await u.po.signIn.signInWithEmailAndInstantPassword({
+      email: fakeAdmin.email,
+      password: fakeAdmin.password,
+    });
+    await u.po.expect.toBeSignedIn();
+
+    await u.po.organizationProfile.goTo();
+    await u.po.organizationProfile.switchToBillingTab();
+    await expect(u.po.page.getByRole('heading', { name: 'Billing' })).toBeVisible();
+
+    await u.po.page.getByText(/^Switch plans$/).click();
+    await u.po.pricingTable.waitForMounted();
+    await u.po.pricingTable.startCheckout({ planSlug: 'bronze' });
+    await u.po.checkout.waitForMounted();
+    await u.po.checkout.fillTestCard();
+    await u.po.checkout.clickPayOrSubscribe();
+    await expect(u.po.checkout.root.getByText('Payment was successful!')).toBeVisible({
+      timeout: 15_000,
+    });
+    await u.po.checkout.confirmAndContinue();
+
+    await u.po.page.getByText(/^Members$/).click();
+    await expect(u.po.page.getByRole('heading', { name: 'Members' })).toBeVisible();
+
+    await u.po.page.getByRole('button', { name: 'Invite' }).click();
+    await fillInviteForm();
+
+    const purchaseSeatsButton = u.po.page.getByRole('button', { name: 'Purchase additional seats' });
+    await expect(purchaseSeatsButton).toBeVisible();
+    await purchaseSeatsButton.click();
+
+    await u.po.checkout.waitForMounted();
+    await u.po.checkout.clickPayOrSubscribe();
+    await expect(u.po.checkout.root.getByText('Payment was successful!')).toBeVisible({
+      timeout: 15_000,
+    });
+    await u.po.checkout.confirmAndContinue();
+    await u.po.checkout.root.waitFor({ state: 'hidden', timeout: 15_000 });
+
+    await u.po.organizationProfile.goTo();
+    await u.po.page.getByText(/^Members$/).click();
+    await expect(u.po.page.getByRole('heading', { name: 'Members' })).toBeVisible();
+    await u.po.page.getByRole('button', { name: 'Invite' }).click();
+    await fillInviteForm();
+
+    const sendInvitationsButton = u.po.page.getByRole('button', { name: 'Send invitations' });
+    await expect(sendInvitationsButton).toBeEnabled({ timeout: 15_000 });
+    await sendInvitationsButton.click({ timeout: 15_000 });
+
+    await expect(u.po.page.getByText('Invitations successfully sent')).toBeVisible({
+      timeout: 15_000,
+    });
+    await u.po.page.getByRole('button', { name: 'Finish' }).click();
+
+    await u.po.page.getByRole('tab', { name: /Invitations/i }).click();
+    await expect(u.po.page.getByText(INVITEE_EMAIL)).toBeVisible({
+      timeout: 15_000,
+    });
+  });
+});

integration/tests/pricing-table.test.ts

@@ -355,8 +355,7 @@ testAgainstRunningApps({})('pricing table @billing', ({ app }) => {
       await expect(u.po.checkout.root.getByText('Free trial')).toBeHidden();
 
       await expect(matchLineItem(u.po.checkout.root, 'Total Due after')).toBeHidden();
-      await expect(matchLineItem(u.po.checkout.root, 'Subtotal', '$999.00')).toBeVisible();
-      await expect(matchLineItem(u.po.checkout.root, 'Total Due Today', '$999.00')).toBeVisible();
+      await expect(matchLineItem(u.po.checkout.root, 'Total due today', '$999.00')).toBeVisible();
       expect(await countLineItems(u.po.checkout.root)).toBe(3);
 
       await u.po.checkout.root.getByRole('button', { name: /^pay\s\$/i }).waitFor({ state: 'visible' });

packages/clerk-js/bundlewatch.config.json

@@ -2,9 +2,9 @@
   "files": [
     { "path": "./dist/clerk.js", "maxSize": "549KB" },
     { "path": "./dist/clerk.browser.js", "maxSize": "71KB" },
-    { "path": "./dist/clerk.legacy.browser.js", "maxSize": "112KB" },
+    { "path": "./dist/clerk.legacy.browser.js", "maxSize": "114KB" },
     { "path": "./dist/clerk.no-rhc.js", "maxSize": "316KB" },
-    { "path": "./dist/clerk.native.js", "maxSize": "70KB" },
+    { "path": "./dist/clerk.native.js", "maxSize": "72KB" },
     { "path": "./dist/vendors*.js", "maxSize": "7KB" },
     { "path": "./dist/coinbase*.js", "maxSize": "36KB" },
     { "path": "./dist/base-account-sdk*.js", "maxSize": "203KB" },

packages/clerk-js/src/core/modules/billing/namespace.ts

@@ -36,8 +36,13 @@ export class Billing implements BillingNamespace {
   }
 
   getPlans = async (params?: GetPlansParams): Promise<ClerkPaginatedResponse<BillingPlanResource>> => {
-    const { for: forParam, ...safeParams } = params || {};
-    const searchParams = { ...safeParams, payer_type: forParam === 'organization' ? 'org' : 'user' };
+    const { for: forParam, orgId, minSeats, ...safeParams } = params || {};
+    const searchParams = {
+      ...safeParams,
+      payer_type: forParam === 'organization' ? 'org' : 'user',
+      org_id: orgId,
+      min_seats: minSeats,
+    };
     return await BaseResource._fetch({
       path: `${Billing.#pathRoot}/plans`,
       method: 'GET',

packages/clerk-js/src/core/modules/checkout/instance.ts

@@ -9,9 +9,16 @@ type CheckoutKey = string & { readonly __tag: 'CheckoutKey' };
 /**
  * Generate cache key for checkout instance
  */
-function cacheKey(options: { userId: string; orgId?: string; planId: string; planPeriod: string }): CheckoutKey {
-  const { userId, orgId, planId, planPeriod } = options;
-  return `${userId}-${orgId || 'user'}-${planId}-${planPeriod}` as CheckoutKey;
+function cacheKey(options: {
+  userId: string;
+  orgId?: string;
+  planId: string;
+  planPeriod: string;
+  seatsQuantity?: number;
+  priceId?: string;
+}): CheckoutKey {
+  const { userId, orgId, planId, planPeriod, seatsQuantity, priceId } = options;
+  return `${userId}-${orgId || 'user'}-${planId}-${planPeriod}-${seatsQuantity}-${priceId}` as CheckoutKey;
 }
 
 /**
@@ -26,7 +33,7 @@ const CheckoutSignalCache = new Map<
  * Create a checkout instance with the given options
  */
 function createCheckoutInstance(clerk: Clerk, options: __experimental_CheckoutOptions): CheckoutSignalValue {
-  const { for: forOrganization, planId, planPeriod } = options;
+  const { for: forOrganization, planId, planPeriod, seatsQuantity, priceId } = options;
 
   if (clerk.user === null) {
     throw new Error('Clerk: User is not authenticated');
@@ -43,6 +50,8 @@ function createCheckoutInstance(clerk: Clerk, options: __experimental_CheckoutOp
     orgId: forOrganization === 'organization' ? clerk.organization?.id : undefined,
     planId,
     planPeriod,
+    seatsQuantity,
+    priceId,
   });
 
   const checkoutInstance = CheckoutSignalCache.get(checkoutKey);
@@ -56,6 +65,8 @@ function createCheckoutInstance(clerk: Clerk, options: __experimental_CheckoutOp
     ...(forOrganization === 'organization' ? { orgId: clerk.organization?.id } : {}),
     planId,
     planPeriod,
+    seatsQuantity,
+    priceId,
   });
 
   CheckoutSignalCache.set(checkoutKey, { resource: checkout, signals });

packages/clerk-js/src/core/resources/BillingCheckout.ts

@@ -4,10 +4,10 @@ import { retry } from '@clerk/shared/retry';
 import type {
   BillingCheckoutJSON,
   BillingCheckoutResource,
-  BillingCheckoutTotals,
   BillingPayerResource,
   BillingPaymentMethodResource,
   BillingSubscriptionPlanPeriod,
+  BillingTotals,
   CheckoutFlowFinalizeParams,
   CheckoutFlowResource,
   CheckoutFlowResourceNonStrict,
@@ -34,7 +34,7 @@ export class BillingCheckout extends BaseResource implements BillingCheckoutReso
   planPeriod!: BillingSubscriptionPlanPeriod;
   planPeriodStart!: number | undefined;
   status!: 'needs_confirmation' | 'completed';
-  totals!: BillingCheckoutTotals;
+  totals!: BillingTotals;
   isImmediatePlanChange!: boolean;
   freeTrialEndsAt?: Date;
   payer!: BillingPayerResource;

packages/clerk-js/src/core/resources/BillingPayment.ts

@@ -5,10 +5,11 @@ import type {
   BillingPaymentMethodResource,
   BillingPaymentResource,
   BillingPaymentStatus,
+  BillingPaymentTotals,
   BillingSubscriptionItemResource,
 } from '@clerk/shared/types';
 
-import { billingMoneyAmountFromJSON } from '../../utils';
+import { billingMoneyAmountFromJSON, billingPaymentTotalsFromJSON } from '../../utils';
 import { unixEpochToDate } from '../../utils/date';
 import { BaseResource, BillingPaymentMethod, BillingSubscriptionItem } from './internal';
 
@@ -22,6 +23,7 @@ export class BillingPayment extends BaseResource implements BillingPaymentResour
   subscriptionItem!: BillingSubscriptionItemResource;
   chargeType!: BillingPaymentChargeType;
   status!: BillingPaymentStatus;
+  totals: BillingPaymentTotals | null = null;
 
   constructor(data: BillingPaymentJSON) {
     super();
@@ -42,6 +44,7 @@ export class BillingPayment extends BaseResource implements BillingPaymentResour
     this.subscriptionItem = new BillingSubscriptionItem(data.subscription_item);
     this.chargeType = data.charge_type;
     this.status = data.status;
+    this.totals = data.totals ? billingPaymentTotalsFromJSON(data.totals) : null;
     return this;
   }
 }