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'

.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'

.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'

.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'

.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'

.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'

.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'

.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'