feat(clerk-js,shared,ui): Add seats info to payment attempts page

.changeset/billing-seat-tier-rows-payment-attempt.md

@@ -0,0 +1,7 @@
+---
+'@clerk/shared': minor
+'@clerk/clerk-js': minor
+'@clerk/ui': minor
+---
+
+Surface seat-based billing details on payment attempts. The payment attempt resource now exposes a `totals` field (`BillingPaymentTotals`) carrying optional `baseFee` and `perUnitTotals` breakdowns. The payment-attempt detail page renders a "Seats" line (`{quantity} × {feePerBlock}`, or the tier total for unlimited tiers) between the plan title and subtotal when the subscription item is seat-billed.

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;
   }
 }

packages/clerk-js/src/utils/__tests__/billing.test.ts

@@ -0,0 +1,70 @@
+import type { BillingMoneyAmountJSON, BillingPaymentTotalsJSON } from '@clerk/shared/types';
+import { describe, expect, it } from 'vitest';
+
+import { billingPaymentTotalsFromJSON } from '../billing';
+
+const moneyJSON = (amount: number): BillingMoneyAmountJSON => ({
+  amount,
+  amount_formatted: (amount / 100).toFixed(2),
+  currency: 'USD',
+  currency_symbol: '$',
+});
+
+describe('billingPaymentTotalsFromJSON', () => {
+  it('maps subtotal, grand_total, and tax_total', () => {
+    const data: BillingPaymentTotalsJSON = {
+      subtotal: moneyJSON(4500),
+      grand_total: moneyJSON(5000),
+      tax_total: moneyJSON(500),
+    };
+
+    const totals = billingPaymentTotalsFromJSON(data);
+
+    expect(totals.subtotal.amount).toBe(4500);
+    expect(totals.grandTotal.amount).toBe(5000);
+    expect(totals.taxTotal.amount).toBe(500);
+    expect(totals.baseFee).toBeNull();
+    expect(totals.perUnitTotals).toBeUndefined();
+  });
+
+  it('maps base_fee when present', () => {
+    const data: BillingPaymentTotalsJSON = {
+      subtotal: moneyJSON(5000),
+      grand_total: moneyJSON(5000),
+      tax_total: moneyJSON(0),
+      base_fee: moneyJSON(1000),
+    };
+
+    expect(billingPaymentTotalsFromJSON(data).baseFee?.amount).toBe(1000);
+  });
+
+  it('maps per_unit_totals tiers with snake_case → camelCase conversion', () => {
+    const data: BillingPaymentTotalsJSON = {
+      subtotal: moneyJSON(5000),
+      grand_total: moneyJSON(5000),
+      tax_total: moneyJSON(0),
+      per_unit_totals: [
+        {
+          name: 'seats',
+          block_size: 1,
+          tiers: [
+            { quantity: 5, fee_per_block: moneyJSON(1000), total: moneyJSON(5000) },
+            { quantity: null, fee_per_block: moneyJSON(0), total: moneyJSON(0) },
+          ],
+        },
+      ],
+    };
+
+    const totals = billingPaymentTotalsFromJSON(data);
+
+    expect(totals.perUnitTotals).toHaveLength(1);
+    expect(totals.perUnitTotals?.[0].name).toBe('seats');
+    expect(totals.perUnitTotals?.[0].blockSize).toBe(1);
+    expect(totals.perUnitTotals?.[0].tiers[0]).toMatchObject({
+      quantity: 5,
+      feePerBlock: { amount: 1000 },
+      total: { amount: 5000 },
+    });
+    expect(totals.perUnitTotals?.[0].tiers[1].quantity).toBeNull();
+  });
+});

packages/clerk-js/src/utils/billing.ts

@@ -5,6 +5,8 @@ import type {
   BillingCreditsJSON,
   BillingMoneyAmount,
   BillingMoneyAmountJSON,
+  BillingPaymentTotals,
+  BillingPaymentTotalsJSON,
   BillingPerUnitTotal,
   BillingPerUnitTotalJSON,
   BillingStatementTotals,
@@ -32,6 +34,16 @@ const billingPerUnitTotalsFromJSON = (data: BillingPerUnitTotalJSON[]): BillingP
   }));
 };
 
+export const billingPaymentTotalsFromJSON = (data: BillingPaymentTotalsJSON): BillingPaymentTotals => {
+  return {
+    subtotal: billingMoneyAmountFromJSON(data.subtotal),
+    grandTotal: billingMoneyAmountFromJSON(data.grand_total),
+    taxTotal: billingMoneyAmountFromJSON(data.tax_total),
+    baseFee: data.base_fee ? billingMoneyAmountFromJSON(data.base_fee) : null,
+    perUnitTotals: data.per_unit_totals ? billingPerUnitTotalsFromJSON(data.per_unit_totals) : undefined,
+  };
+};
+
 export const billingCreditsFromJSON = (data: BillingCreditsJSON): BillingCredits => {
   return {
     proration: data.proration

packages/localizations/src/en-US.ts

@@ -168,6 +168,11 @@ export const enUS: LocalizationResource = {
     },
     reSubscribe: 'Resubscribe',
     seats: 'Seats',
+    seatsWithLimit: 'Seats (up to {{limit}})',
+    seatBreakdownSingular: '1 seat at {{rate}}/mo',
+    seatBreakdownPlural: '{{chargeable}} seats at {{rate}}/mo',
+    seatBreakdownIncludedSingular: '1 seat at {{rate}}/mo ({{totalSeats}} total - {{included}} included)',
+    seatBreakdownIncludedPlural: '{{chargeable}} seats at {{rate}}/mo ({{totalSeats}} total - {{included}} included)',
     seeAllFeatures: 'See all features',
     startFreeTrial: 'Start free trial',
     startFreeTrial__days: 'Start {{days}}-day free trial',

packages/shared/src/types/billing.ts

@@ -505,6 +505,35 @@ export type BillingPaymentChargeType = 'checkout' | 'recurring';
  */
 export type BillingPaymentStatus = 'pending' | 'paid' | 'failed';
 
+/**
+ * The `BillingPaymentTotals` type represents the per-payment cost breakdown, including any base fee
+ * and per-unit (for example, seats) subtotals.
+ *
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
+export interface BillingPaymentTotals {
+  /**
+   * The price of the items before taxes, credits, or discounts are applied.
+   */
+  subtotal: BillingMoneyAmount;
+  /**
+   * The total amount for the payment, including taxes and after credits/discounts are applied.
+   */
+  grandTotal: BillingMoneyAmount;
+  /**
+   * The amount of tax included in the payment.
+   */
+  taxTotal: BillingMoneyAmount;
+  /**
+   * The flat base fee charged on top of any per-unit fees.
+   */
+  baseFee?: BillingMoneyAmount | null;
+  /**
+   * Per-unit cost breakdown for this payment (for example, seats).
+   */
+  perUnitTotals?: BillingPerUnitTotal[];
+}
+
 /**
  * The `BillingPaymentResource` type represents a payment attempt for a user or Organization.
  *
@@ -547,6 +576,11 @@ export interface BillingPaymentResource extends ClerkResource {
    * The current status of the payment.
    */
   status: BillingPaymentStatus;
+  /**
+   * Per-payment breakdown with optional base fee and per-unit (for example, seats) subtotals.
+   * Absent on older responses.
+   */
+  totals?: BillingPaymentTotals | null;
 }
 
 /**

packages/shared/src/types/json.ts

@@ -740,6 +740,19 @@ export interface BillingStatementGroupJSON extends ClerkResourceJSON {
   items: BillingPaymentJSON[];
 }
 
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ *
+ * Per-payment cost breakdown including optional base fee and per-unit (for example, seats) subtotals.
+ */
+export interface BillingPaymentTotalsJSON {
+  subtotal: BillingMoneyAmountJSON;
+  grand_total: BillingMoneyAmountJSON;
+  tax_total: BillingMoneyAmountJSON;
+  base_fee?: BillingMoneyAmountJSON | null;
+  per_unit_totals?: BillingPerUnitTotalJSON[];
+}
+
 /**
  * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
@@ -754,6 +767,11 @@ export interface BillingPaymentJSON extends ClerkResourceJSON {
   subscription_item: BillingSubscriptionItemJSON;
   charge_type: BillingPaymentChargeType;
   status: BillingPaymentStatus;
+  /**
+   * Per-payment breakdown with optional base fee and per-unit (for example, seats)
+   * subtotals. Absent on older responses.
+   */
+  totals?: BillingPaymentTotalsJSON | null;
 }
 
 /**

packages/shared/src/types/localization.ts

@@ -191,6 +191,11 @@ export type __internal_LocalizationResource = {
     keepSubscription: LocalizationValue;
     reSubscribe: LocalizationValue;
     seats: LocalizationValue;
+    seatsWithLimit: LocalizationValue<'limit'>;
+    seatBreakdownSingular: LocalizationValue<'rate'>;
+    seatBreakdownPlural: LocalizationValue<'chargeable' | 'rate'>;
+    seatBreakdownIncludedSingular: LocalizationValue<'totalSeats' | 'included' | 'rate'>;
+    seatBreakdownIncludedPlural: LocalizationValue<'totalSeats' | 'included' | 'chargeable' | 'rate'>;
     subscribe: LocalizationValue;
     startFreeTrial: LocalizationValue;
     startFreeTrial__days: LocalizationValue<'days'>;

packages/ui/src/components/PaymentAttempts/PaymentAttemptPage.tsx

@@ -1,9 +1,10 @@
 import { __internal_usePaymentAttemptQuery } from '@clerk/shared/react/index';
-import type { BillingSubscriptionItemResource } from '@clerk/shared/types';
+import type { BillingPaymentResource } from '@clerk/shared/types';
 
 import { Alert } from '@/ui/elements/Alert';
 import { Header } from '@/ui/elements/Header';
 import { LineItems } from '@/ui/elements/LineItems';
+import { getPlanSeatLimit, getSeatsPerUnitTotal, summarizeSeatCharges } from '@/ui/utils/billingPlanSeats';
 import { formatDate } from '@/ui/utils/formatDate';
 import { truncateWithEndVisible } from '@/ui/utils/truncateTextWithEndVisible';
 
@@ -42,8 +43,6 @@ export const PaymentAttemptPage = () => {
     enabled: Boolean(params.paymentAttemptId),
   });
 
-  const subscriptionItem = paymentAttempt?.subscriptionItem;
-
   if (isLoading) {
     return (
       <Box sx={{ display: 'flex', justifyContent: 'center', alignItems: 'center', height: '100%' }}>
@@ -147,7 +146,7 @@ export const PaymentAttemptPage = () => {
               {paymentAttempt.status}
             </Badge>
           </Box>
-          <PaymentAttemptBody subscriptionItem={subscriptionItem} />
+          <PaymentAttemptBody paymentAttempt={paymentAttempt} />
           <Box
             elementDescriptor={descriptors.paymentAttemptFooter}
             as='footer'
@@ -198,18 +197,25 @@ export const PaymentAttemptPage = () => {
   );
 };
 
-function PaymentAttemptBody({ subscriptionItem }: { subscriptionItem: BillingSubscriptionItemResource | undefined }) {
-  if (!subscriptionItem) {
+function PaymentAttemptBody({ paymentAttempt }: { paymentAttempt: BillingPaymentResource | undefined }) {
+  if (!paymentAttempt) {
     return null;
   }
 
+  const { subscriptionItem } = paymentAttempt;
+
   const fee =
     subscriptionItem.planPeriod === 'month'
       ? // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         subscriptionItem.plan.fee!
       : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         subscriptionItem.plan.annualMonthlyFee!;
 
+  const seatsTotal = subscriptionItem.seats != null ? getSeatsPerUnitTotal(paymentAttempt.totals) : undefined;
+  const seatSummary = summarizeSeatCharges(seatsTotal);
+  const seatsChargeable = seatSummary ? seatSummary.totalSeats - seatSummary.included : 0;
+  const planSeatLimit = getPlanSeatLimit(subscriptionItem.plan);
+
   return (
     <Box
       elementDescriptor={descriptors.paymentAttemptBody}
@@ -225,6 +231,42 @@ function PaymentAttemptBody({ subscriptionItem }: { subscriptionItem: BillingSub
             text={`${fee.currencySymbol}${fee.amountFormatted}`}
           />
         </LineItems.Group>
+        {seatSummary && (
+          <LineItems.Group>
+            <LineItems.Title
+              title={
+                planSeatLimit != null
+                  ? localizationKeys('billing.seatsWithLimit', { limit: planSeatLimit })
+                  : localizationKeys('billing.seats')
+              }
+              description={(() => {
+                const rate = `${seatSummary.paidTier.feePerBlock.currencySymbol}${seatSummary.paidTier.feePerBlock.amountFormatted}`;
+                const isSingular = seatsChargeable === 1;
+                if (seatSummary.included > 0) {
+                  return isSingular
+                    ? localizationKeys('billing.seatBreakdownIncludedSingular', {
+                        totalSeats: seatSummary.totalSeats,
+                        included: seatSummary.included,
+                        rate,
+                      })
+                    : localizationKeys('billing.seatBreakdownIncludedPlural', {
+                        totalSeats: seatSummary.totalSeats,
+                        included: seatSummary.included,
+                        chargeable: seatsChargeable,
+                        rate,
+                      });
+                }
+                return isSingular
+                  ? localizationKeys('billing.seatBreakdownSingular', { rate })
+                  : localizationKeys('billing.seatBreakdownPlural', { chargeable: seatsChargeable, rate });
+              })()}
+            />
+            <LineItems.Description
+              prefix={subscriptionItem.planPeriod === 'annual' ? 'x12' : undefined}
+              text={`${seatSummary.paidTier.total.currencySymbol}${seatSummary.paidTier.total.amountFormatted}`}
+            />
+          </LineItems.Group>
+        )}
         <LineItems.Group
           borderTop
           variant='tertiary'