feat(clerk-js,localizations,shared,ui): Add support for account credi…

.changeset/shy-loops-type.md

@@ -0,0 +1,8 @@
+---
+'@clerk/localizations': minor
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/ui': minor
+---
+
+Add support for account credits in checkout.

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

@@ -0,0 +1,313 @@
+import {
+  clerkHandlers,
+  http,
+  HttpResponse,
+  EnvironmentService,
+  SessionService,
+  setClerkState,
+  type MockScenario,
+  UserService,
+} from '@clerk/msw';
+
+export function CheckoutAccountCredit(): MockScenario {
+  const user = UserService.create();
+  const session = SessionService.create(user);
+
+  setClerkState({
+    environment: EnvironmentService.MULTI_SESSION,
+    session,
+    user,
+  });
+
+  const subscriptionHandler = http.get('https://*.clerk.accounts.dev/v1/me/billing/subscription', () => {
+    return HttpResponse.json({
+      response: {
+        data: {
+          account_credit: 100,
+        },
+      },
+    });
+  });
+
+  const paymentMethodsHandler = http.get('https://*.clerk.accounts.dev/v1/me/billing/payment_methods', () => {
+    return HttpResponse.json({
+      response: {
+        data: {
+          account_credit: 100,
+        },
+      },
+    });
+  });
+
+  const checkoutAccountCreditHandler = http.post('https://*.clerk.accounts.dev/v1/me/billing/checkouts', () => {
+    return HttpResponse.json({
+      response: {
+        object: 'commerce_checkout',
+        id: 'string',
+        plan: {
+          object: 'commerce_plan',
+          id: 'string',
+          name: 'Pro',
+          fee: {
+            amount: 0,
+            amount_formatted: '25.00',
+            currency: 'string',
+            currency_symbol: '$',
+          },
+          annual_monthly_fee: {
+            amount: 0,
+            amount_formatted: 'string',
+            currency: 'string',
+            currency_symbol: 'string',
+          },
+          annual_fee: {
+            amount: 0,
+            amount_formatted: 'string',
+            currency: 'string',
+            currency_symbol: 'string',
+          },
+          description: null,
+          is_default: true,
+          is_recurring: true,
+          publicly_visible: true,
+          has_base_fee: true,
+          for_payer_type: 'string',
+          slug: 'string',
+          avatar_url: null,
+          free_trial_enabled: true,
+          free_trial_days: null,
+          features: [
+            {
+              object: 'feature',
+              id: 'string',
+              name: 'string',
+              description: null,
+              slug: 'string',
+              avatar_url: null,
+            },
+          ],
+        },
+        plan_period: 'month',
+        payer: {
+          object: 'commerce_payer',
+          id: 'string',
+          instance_id: 'string',
+          user_id: null,
+          first_name: null,
+          last_name: null,
+          email: null,
+          organization_id: null,
+          organization_name: null,
+          image_url: 'https://example.com',
+          created_at: 1,
+          updated_at: 1,
+        },
+        payment_method: {
+          object: 'commerce_payment_method',
+          id: 'string',
+          payer_id: 'string',
+          payment_type: 'card',
+          is_default: true,
+          gateway: 'string',
+          gateway_external_id: 'string',
+          gateway_external_account_id: null,
+          last4: null,
+          status: 'active',
+          wallet_type: null,
+          card_type: null,
+          expiry_year: null,
+          expiry_month: null,
+          created_at: 1,
+          updated_at: 1,
+          is_removable: true,
+        },
+        external_gateway_id: 'string',
+        status: 'needs_confirmation',
+        totals: {
+          subtotal: {
+            amount: 1,
+            amount_formatted: '25.00',
+            currency: 'string',
+            currency_symbol: '$',
+          },
+          tax_total: {
+            amount: 1,
+            amount_formatted: 'string',
+            currency: 'string',
+            currency_symbol: 'string',
+          },
+          grand_total: {
+            amount: 1,
+            amount_formatted: 'string',
+            currency: 'string',
+            currency_symbol: 'string',
+          },
+          total_due_after_free_trial: {
+            amount: 1,
+            amount_formatted: 'string',
+            currency: 'string',
+            currency_symbol: 'string',
+          },
+          total_due_now: {
+            amount: 1,
+            amount_formatted: '10.00',
+            currency: 'string',
+            currency_symbol: '$',
+          },
+          past_due: null,
+          credit: {
+            amount: 1,
+            amount_formatted: '5.00',
+            currency: 'string',
+            currency_symbol: '$',
+          },
+          account_credit: {
+            amount: 1,
+            amount_formatted: '10.00',
+            currency: 'string',
+            currency_symbol: '$',
+          },
+        },
+        subscription_item: {
+          object: 'commerce_subscription_item',
+          id: 'string',
+          instance_id: 'string',
+          status: 'active',
+          credit: {
+            amount: {
+              amount: 1,
+              amount_formatted: 'string',
+              currency: 'string',
+              currency_symbol: 'string',
+            },
+            cycle_days_remaining: 1,
+            cycle_days_total: 1,
+            cycle_remaining_percent: 1,
+          },
+          plan_id: 'string',
+          price_id: 'string',
+          plan: {
+            object: 'commerce_plan',
+            id: 'string',
+            name: 'string',
+            fee: {
+              amount: 0,
+              amount_formatted: 'string',
+              currency: 'string',
+              currency_symbol: 'string',
+            },
+            annual_monthly_fee: {
+              amount: 0,
+              amount_formatted: 'string',
+              currency: 'string',
+              currency_symbol: 'string',
+            },
+            annual_fee: {
+              amount: 0,
+              amount_formatted: 'string',
+              currency: 'string',
+              currency_symbol: 'string',
+            },
+            description: null,
+            is_default: true,
+            is_recurring: true,
+            publicly_visible: true,
+            has_base_fee: true,
+            for_payer_type: 'string',
+            slug: 'string',
+            avatar_url: null,
+            free_trial_enabled: true,
+            free_trial_days: null,
+            features: [
+              {
+                object: 'feature',
+                id: 'string',
+                name: 'string',
+                description: null,
+                slug: 'string',
+                avatar_url: null,
+              },
+            ],
+          },
+          plan_period: 'month',
+          payment_method_id: 'string',
+          payment_method: {
+            object: 'commerce_payment_method',
+            id: 'string',
+            payer_id: 'string',
+            payment_type: 'card',
+            is_default: true,
+            gateway: 'string',
+            gateway_external_id: 'string',
+            gateway_external_account_id: null,
+            last4: null,
+            status: 'active',
+            wallet_type: null,
+            card_type: null,
+            expiry_year: null,
+            expiry_month: null,
+            created_at: 1,
+            updated_at: 1,
+            is_removable: true,
+          },
+          lifetime_paid: {
+            amount: 0,
+            amount_formatted: 'string',
+            currency: 'string',
+            currency_symbol: 'string',
+          },
+          amount: {
+            amount: 0,
+            amount_formatted: 'string',
+            currency: 'string',
+            currency_symbol: 'string',
+          },
+          next_payment: {
+            amount: {
+              amount: 0,
+              amount_formatted: 'string',
+              currency: 'string',
+              currency_symbol: 'string',
+            },
+            date: 1,
+          },
+          payer_id: 'string',
+          payer: {
+            object: 'commerce_payer',
+            id: 'string',
+            instance_id: 'string',
+            user_id: null,
+            first_name: null,
+            last_name: null,
+            email: null,
+            organization_id: null,
+            organization_name: null,
+            image_url: 'https://example.com',
+            created_at: 1,
+            updated_at: 1,
+          },
+          is_free_trial: true,
+          period_start: 1,
+          period_end: null,
+          proration_date: 'string',
+          canceled_at: null,
+          past_due_at: null,
+          ended_at: null,
+          created_at: 1,
+          updated_at: 1,
+        },
+        plan_period_start: 1,
+        is_immediate_plan_change: true,
+        free_trial_ends_at: 1,
+        needs_payment_method: true,
+      },
+    });
+  });
+
+  return {
+    description: 'Checkout with account credit',
+    handlers: [checkoutAccountCreditHandler, subscriptionHandler, paymentMethodsHandler, ...clerkHandlers],
+    initialState: { session, user },
+    name: 'checkout-account-credit',
+  };
+}

packages/clerk-js/sandbox/scenarios/index.ts

@@ -1 +1,2 @@
 export { UserButtonSignedIn } from './user-button-signed-in';
+export { CheckoutAccountCredit } from './checkout-account-credit';

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

@@ -31,7 +31,9 @@ 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 ('total_due_now' in data) {
     totals.totalDueNow = billingMoneyAmountFromJSON(data.total_due_now);
   }

packages/localizations/src/en-US.ts

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

packages/shared/src/types/billing.ts

@@ -716,6 +716,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;
   /**
    * Any outstanding amount from previous unpaid invoices that is being collected as part of the checkout.
    */

packages/shared/src/types/json.ts

@@ -753,6 +753,7 @@ export interface BillingCheckoutTotalsJSON {
   tax_total: BillingMoneyAmountJSON;
   total_due_now: BillingMoneyAmountJSON;
   credit: BillingMoneyAmountJSON | null;
+  account_credit: BillingMoneyAmountJSON | null;
   past_due: BillingMoneyAmountJSON | null;
   total_due_after_free_trial: BillingMoneyAmountJSON | null;
 }

packages/shared/src/types/localization.ts

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