feat(clerk-js,localizations,shared): Render credits (#7885)

Author: dstaley

.changeset/sharp-monkeys-live.md

@@ -0,0 +1,7 @@
+---
+'@clerk/localizations': minor
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+Add support for displaying proration and account credits on payment attempts and statements.

packages/clerk-js/bundlewatch.config.json

@@ -1,6 +1,6 @@
 {
   "files": [
-    { "path": "./dist/clerk.js", "maxSize": "929KB" },
+    { "path": "./dist/clerk.js", "maxSize": "930KB" },
     { "path": "./dist/clerk.browser.js", "maxSize": "87KB" },
     { "path": "./dist/clerk.legacy.browser.js", "maxSize": "129KB" },
     { "path": "./dist/clerk.headless*.js", "maxSize": "67KB" },

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

@@ -1,4 +1,5 @@
 import type {
+  BillingCredits,
   BillingMoneyAmount,
   BillingSubscriptionItemJSON,
   BillingSubscriptionItemResource,
@@ -12,7 +13,7 @@ import type {
 
 import { unixEpochToDate } from '@/utils/date';
 
-import { billingMoneyAmountFromJSON } from '../../utils';
+import { billingCreditsFromJSON, billingMoneyAmountFromJSON } from '../../utils';
 import { Billing } from '../modules/billing/namespace';
 import { BaseResource, BillingPlan, DeletedObject } from './internal';
 
@@ -75,6 +76,7 @@ export class BillingSubscriptionItem extends BaseResource implements BillingSubs
   credit?: {
     amount: BillingMoneyAmount;
   };
+  credits?: BillingCredits;
   isFreeTrial!: boolean;
 
   constructor(data: BillingSubscriptionItemJSON) {
@@ -103,6 +105,8 @@ export class BillingSubscriptionItem extends BaseResource implements BillingSubs
     this.credit =
       data.credit && data.credit.amount ? { amount: billingMoneyAmountFromJSON(data.credit.amount) } : undefined;
 
+    this.credits = data.credits ? billingCreditsFromJSON(data.credits) : undefined;
+
     this.isFreeTrial = this.withDefault(data.is_free_trial, false);
     return this;
   }

packages/clerk-js/src/ui/components/PaymentAttempts/PaymentAttemptPage.tsx

@@ -233,14 +233,26 @@ function PaymentAttemptBody({ subscriptionItem }: { subscriptionItem: BillingSub
             text={`${subscriptionItem.amount?.currencySymbol}${subscriptionItem.amount?.amountFormatted}`}
           />
         </LineItems.Group>
-        {subscriptionItem.credit && subscriptionItem.credit.amount.amount > 0 && (
-          <LineItems.Group variant='tertiary'>
-            <LineItems.Title title={localizationKeys('billing.credit')} />
-            <LineItems.Description
-              text={`- ${subscriptionItem.credit.amount.currencySymbol}${subscriptionItem.credit.amount.amountFormatted}`}
-            />
-          </LineItems.Group>
-        )}
+        {subscriptionItem.credits &&
+          subscriptionItem.credits.proration &&
+          subscriptionItem.credits.proration.amount.amount > 0 && (
+            <LineItems.Group variant='tertiary'>
+              <LineItems.Title title={localizationKeys('billing.prorationCredit')} />
+              <LineItems.Description
+                text={`- ${subscriptionItem.credits.proration.amount.currencySymbol}${subscriptionItem.credits.proration.amount.amountFormatted}`}
+              />
+            </LineItems.Group>
+          )}
+        {subscriptionItem.credits &&
+          subscriptionItem.credits.payer &&
+          subscriptionItem.credits.payer.appliedAmount.amount > 0 && (
+            <LineItems.Group variant='tertiary'>
+              <LineItems.Title title={localizationKeys('billing.accountCredit')} />
+              <LineItems.Description
+                text={`- ${subscriptionItem.credits.payer.appliedAmount.currencySymbol}${subscriptionItem.credits.payer.appliedAmount.amountFormatted}`}
+              />
+            </LineItems.Group>
+          )}
       </LineItems.Root>
     </Box>
   );

packages/clerk-js/src/ui/components/Statements/StatementPage.tsx

@@ -137,12 +137,24 @@ export const StatementPage = () => {
                             </SimpleButton>
                           }
                         />
-                        {item.subscriptionItem.credit && item.subscriptionItem.credit.amount.amount > 0 ? (
+                        {item.subscriptionItem.credits &&
+                        item.subscriptionItem.credits.proration &&
+                        item.subscriptionItem.credits.proration.amount.amount > 0 ? (
                           <Statement.SectionContentDetailsListItem
                             label={localizationKeys(
                               `${localizationRoot}.billingPage.statementsSection.itemCaption__proratedCredit`,
                             )}
-                            value={`(${item.subscriptionItem.credit.amount.currencySymbol}${item.subscriptionItem.credit.amount.amountFormatted})`}
+                            value={`(${item.subscriptionItem.credits.proration.amount.currencySymbol}${item.subscriptionItem.credits.proration.amount.amountFormatted})`}
+                          />
+                        ) : null}
+                        {item.subscriptionItem.credits &&
+                        item.subscriptionItem.credits.payer &&
+                        item.subscriptionItem.credits.payer.appliedAmount.amount > 0 ? (
+                          <Statement.SectionContentDetailsListItem
+                            label={localizationKeys(
+                              `${localizationRoot}.billingPage.statementsSection.itemCaption__payerCredit`,
+                            )}
+                            value={`(${item.subscriptionItem.credits.payer.appliedAmount.currencySymbol}${item.subscriptionItem.credits.payer.appliedAmount.amountFormatted})`}
                           />
                         ) : null}
                       </Statement.SectionContentDetailsList>

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

@@ -18,7 +18,7 @@ export const billingMoneyAmountFromJSON = (data: BillingMoneyAmountJSON): Billin
   };
 };
 
-const billingCreditsFromJSON = (data: BillingCreditsJSON): BillingCredits => {
+export const billingCreditsFromJSON = (data: BillingCreditsJSON): BillingCredits => {
   return {
     proration: data.proration
       ? {

packages/localizations/src/en-US.ts

@@ -109,6 +109,8 @@ export const enUS: LocalizationResource = {
       totalDueAfterTrial: 'Total Due after trial ends in {{days}} days',
     },
     credit: 'Credit',
+    prorationCredit: 'Prorated credit',
+    accountCredit: 'Account credit',
     creditRemainder: 'Credit for the remainder of your current subscription.',
     payerCreditRemainder: 'Credit from account balance.',
     defaultFreePlanActive: "You're currently on the Free plan",
@@ -314,6 +316,7 @@ export const enUS: LocalizationResource = {
         empty: 'No statements to display',
         itemCaption__paidForPlan: 'Paid for {{plan}} {{period}} plan',
         itemCaption__proratedCredit: 'Prorated credit for partial usage of previous subscription',
+        itemCaption__payerCredit: 'Credit from account balance',
         itemCaption__subscribedAndPaidForPlan: 'Subscribed and paid for {{plan}} {{period}} plan',
         notFound: 'Statement not found',
         tableHeader__amount: 'Amount',
@@ -1144,6 +1147,7 @@ export const enUS: LocalizationResource = {
         empty: 'No statements to display',
         itemCaption__paidForPlan: 'Paid for {{plan}} {{period}} plan',
         itemCaption__proratedCredit: 'Prorated credit for partial usage of previous subscription',
+        itemCaption__payerCredit: 'Credit from account balance',
         itemCaption__subscribedAndPaidForPlan: 'Subscribed and paid for {{plan}} {{period}} plan',
         notFound: 'Statement not found',
         tableHeader__amount: 'Amount',

packages/shared/src/types/billing.ts

@@ -548,6 +548,7 @@ export interface BillingSubscriptionItemResource extends ClerkResource {
      */
     amount: BillingMoneyAmount;
   };
+  credits?: BillingCredits;
   /**
    * A function to cancel the subscription item. Accepts the following parameters:
    * <ul>

packages/shared/src/types/localization.ts

@@ -206,6 +206,8 @@ export type __internal_LocalizationResource = {
     availableFeatures: LocalizationValue;
     subtotal: LocalizationValue;
     credit: LocalizationValue;
+    prorationCredit: LocalizationValue;
+    accountCredit: LocalizationValue;
     creditRemainder: LocalizationValue;
     payerCreditRemainder: LocalizationValue;
     totalDue: LocalizationValue;
@@ -910,6 +912,7 @@ export type __internal_LocalizationResource = {
         empty: LocalizationValue;
         itemCaption__paidForPlan: LocalizationValue;
         itemCaption__proratedCredit: LocalizationValue;
+        itemCaption__payerCredit: LocalizationValue;
         itemCaption__subscribedAndPaidForPlan: LocalizationValue;
         notFound: LocalizationValue;
         tableHeader__date: LocalizationValue;
@@ -1148,6 +1151,7 @@ export type __internal_LocalizationResource = {
         empty: LocalizationValue;
         itemCaption__paidForPlan: LocalizationValue<'plan' | 'period'>;
         itemCaption__proratedCredit: LocalizationValue;
+        itemCaption__payerCredit: LocalizationValue;
         itemCaption__subscribedAndPaidForPlan: LocalizationValue<'plan' | 'period'>;
         notFound: LocalizationValue;
         tableHeader__date: LocalizationValue;