fix(clerk-js,localizations,shared,ui): Use new credits field

Author: dstaley

packages/clerk-js/sandbox/scenarios/checkout-account-credit.ts

@@ -22,19 +22,15 @@ export function CheckoutAccountCredit(): MockScenario {
   const subscriptionHandler = http.get('https://*.clerk.accounts.dev/v1/me/billing/subscription', () => {
     return HttpResponse.json({
       response: {
-        data: {
-          account_credit: 100,
-        },
+        data: {},
       },
     });
   });
 
   const paymentMethodsHandler = http.get('https://*.clerk.accounts.dev/v1/me/billing/payment_methods', () => {
     return HttpResponse.json({
       response: {
-        data: {
-          account_credit: 100,
-        },
+        data: {},
       },
     });
   });
@@ -161,11 +157,38 @@ export function CheckoutAccountCredit(): MockScenario {
             currency: 'string',
             currency_symbol: '$',
           },
-          account_credit: {
-            amount: 1,
-            amount_formatted: '10.00',
-            currency: 'string',
-            currency_symbol: '$',
+          credits: {
+            proration: {
+              amount: {
+                amount: 1,
+                amount_formatted: '5.00',
+                currency: 'string',
+                currency_symbol: '$',
+              },
+              cycle_days_remaining: 1,
+              cycle_days_total: 1,
+              cycle_remaining_percent: 1,
+            },
+            payer_credit: {
+              remaining_balance: {
+                amount: 1,
+                amount_formatted: '100.00',
+                currency: 'string',
+                currency_symbol: '$',
+              },
+              applied_amount: {
+                amount: 1,
+                amount_formatted: '10.00',
+                currency: 'string',
+                currency_symbol: '$',
+              },
+            },
+            total: {
+              amount: 1,
+              amount_formatted: '15.00',
+              currency: 'string',
+              currency_symbol: '$',
+            },
           },
         },
         subscription_item: {

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

@@ -1,6 +1,8 @@
 import type {
   BillingCheckoutTotals,
   BillingCheckoutTotalsJSON,
+  BillingCredits,
+  BillingCreditsJSON,
   BillingMoneyAmount,
   BillingMoneyAmountJSON,
   BillingStatementTotals,
@@ -16,6 +18,26 @@ export const billingMoneyAmountFromJSON = (data: BillingMoneyAmountJSON): Billin
   };
 };
 
+const billingCreditsFromJSON = (data: BillingCreditsJSON): BillingCredits => {
+  return {
+    proration: data.proration
+      ? {
+          amount: billingMoneyAmountFromJSON(data.proration.amount),
+          cycleDaysRemaining: data.proration.cycle_days_remaining,
+          cycleDaysTotal: data.proration.cycle_days_total,
+          cycleRemainingPercent: data.proration.cycle_remaining_percent,
+        }
+      : null,
+    payerCredit: data.payer_credit
+      ? {
+          remainingBalance: billingMoneyAmountFromJSON(data.payer_credit.remaining_balance),
+          appliedAmount: billingMoneyAmountFromJSON(data.payer_credit.applied_amount),
+        }
+      : null,
+    total: billingMoneyAmountFromJSON(data.total),
+  };
+};
+
 export const billingTotalsFromJSON = <T extends BillingStatementTotalsJSON | BillingCheckoutTotalsJSON>(
   data: T,
 ): T extends { total_due_now: BillingMoneyAmountJSON } ? BillingCheckoutTotals : BillingStatementTotals => {
@@ -31,8 +53,8 @@ export const billingTotalsFromJSON = <T extends BillingStatementTotalsJSON | Bil
   if ('credit' in data) {
     totals.credit = data.credit ? billingMoneyAmountFromJSON(data.credit) : null;
   }
-  if ('account_credit' in data) {
-    totals.accountCredit = data.account_credit ? billingMoneyAmountFromJSON(data.account_credit) : null;
+  if ('credits' in data) {
+    totals.credits = data.credits ? billingCreditsFromJSON(data.credits) : null;
   }
   if ('total_due_now' in data) {
     totals.totalDueNow = billingMoneyAmountFromJSON(data.total_due_now);

packages/localizations/src/en-US.ts

@@ -110,7 +110,7 @@ export const enUS: LocalizationResource = {
     },
     credit: 'Credit',
     creditRemainder: 'Credit for the remainder of your current subscription.',
-    accountCreditRemainder: 'Credit from account balance.',
+    payerCreditRemainder: 'Credit from account balance.',
     defaultFreePlanActive: "You're currently on the Free plan",
     free: 'Free',
     getStarted: 'Get started',

packages/shared/src/types/billing.ts

@@ -690,6 +690,24 @@ export interface BillingMoneyAmount {
   currencySymbol: string;
 }
 
+export interface BillingProrationCreditDetail {
+  amount: BillingMoneyAmount;
+  cycleDaysRemaining: number;
+  cycleDaysTotal: number;
+  cycleRemainingPercent: number;
+}
+
+export interface BillingPayerCredit {
+  remainingBalance: BillingMoneyAmount;
+  appliedAmount: BillingMoneyAmount;
+}
+
+export interface BillingCredits {
+  proration: BillingProrationCreditDetail | null;
+  payerCredit: BillingPayerCredit | null;
+  total: BillingMoneyAmount;
+}
+
 /**
  * The `BillingCheckoutTotals` type represents the total costs, taxes, and other pricing details for a checkout session.
  *
@@ -716,7 +734,7 @@ export interface BillingCheckoutTotals {
    * Any credits (like account balance or promo credits) that are being applied to the checkout.
    */
   credit: BillingMoneyAmount | null;
-  accountCredit: BillingMoneyAmount | null;
+  credits: BillingCredits | null;
   /**
    * Any outstanding amount from previous unpaid invoices that is being collected as part of the checkout.
    */

packages/shared/src/types/json.ts

@@ -695,6 +695,7 @@ export interface BillingSubscriptionItemJSON extends ClerkResourceJSON {
   credit?: {
     amount: BillingMoneyAmountJSON;
   };
+  credits?: BillingCreditsJSON;
   plan: BillingPlanJSON;
   plan_period: BillingSubscriptionPlanPeriod;
   status: BillingSubscriptionStatus;
@@ -744,6 +745,33 @@ export interface BillingMoneyAmountJSON {
   currency_symbol: string;
 }
 
+/**
+ * Contains proration credit details including billing cycle information.
+ */
+export interface BillingProrationCreditDetailJSON {
+  amount: BillingMoneyAmountJSON;
+  cycle_days_remaining: number;
+  cycle_days_total: number;
+  cycle_remaining_percent: number;
+}
+
+/**
+ * Contains payer credit details including the available balance and the amount applied to this checkout.
+ */
+export interface BillingPayerCreditJSON {
+  remaining_balance: BillingMoneyAmountJSON;
+  applied_amount: BillingMoneyAmountJSON;
+}
+
+/**
+ * Unified credits breakdown for checkout totals. Can be used instead of `credit` field.
+ */
+export interface BillingCreditsJSON {
+  proration: BillingProrationCreditDetailJSON | null;
+  payer_credit: BillingPayerCreditJSON | null;
+  total: BillingMoneyAmountJSON;
+}
+
 /**
  * @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.
  */
@@ -753,6 +781,7 @@ export interface BillingCheckoutTotalsJSON {
   tax_total: BillingMoneyAmountJSON;
   total_due_now: BillingMoneyAmountJSON;
   credit: BillingMoneyAmountJSON | null;
+  credits: BillingCreditsJSON | null;
   account_credit: BillingMoneyAmountJSON | null;
   past_due: BillingMoneyAmountJSON | null;
   total_due_after_free_trial: BillingMoneyAmountJSON | null;

packages/shared/src/types/localization.ts

@@ -207,7 +207,7 @@ export type __internal_LocalizationResource = {
     subtotal: LocalizationValue;
     credit: LocalizationValue;
     creditRemainder: LocalizationValue;
-    accountCreditRemainder: LocalizationValue;
+    payerCreditRemainder: LocalizationValue;
     totalDue: LocalizationValue;
     totalDueToday: LocalizationValue;
     pastDue: LocalizationValue;

packages/ui/src/components/Checkout/CheckoutForm.tsx

@@ -35,8 +35,9 @@ export const CheckoutForm = withCardStateProvider(() => {
     return null;
   }
 
-  const showProratedCredit = !!totals.credit?.amount && totals.credit.amount > 0;
-  const showAccountCredits = !!totals.accountCredit?.amount && totals.accountCredit.amount > 0;
+  const showProratedCredit = !!totals.credits?.proration?.amount && totals.credits.proration.amount.amount > 0;
+  const showAccountCredits =
+    !!totals.credits?.payerCredit?.appliedAmount && totals.credits.payerCredit.appliedAmount.amount > 0;
   const showPastDue = !!totals.pastDue?.amount && totals.pastDue.amount > 0;
   const showDowngradeInfo = !isImmediatePlanChange;
 
@@ -89,9 +90,9 @@ export const CheckoutForm = withCardStateProvider(() => {
           )}
           {showAccountCredits && (
             <LineItems.Group variant='tertiary'>
-              <LineItems.Title title={localizationKeys('billing.accountCreditRemainder')} />
+              <LineItems.Title title={localizationKeys('billing.payerCreditRemainder')} />
               <LineItems.Description
-                text={`- ${totals.accountCredit?.currencySymbol}${totals.accountCredit?.amountFormatted}`}
+                text={`- ${totals.credits?.payerCredit?.appliedAmount?.currencySymbol}${totals.credits?.payerCredit?.appliedAmount?.amountFormatted}`}
               />
             </LineItems.Group>
           )}